Skip to main content
command CX Codex

sync-skills-readme — Claude Code command to update README

sync-skills-readme scans skills/ and refreshes the Available Skills table in the root README.md. Use it after adding or changing skills.

MIT ★ 2,707 updated 2026-03-05

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/sync-skills-readme.md
Open on GitHub

What sync-skills-readme does

The command reads name and description from each skill’s SKILL.md, assigns a category, then builds a compact table with links to skill READMEs. Long descriptions are shortened. Skills are grouped by category and sorted by name.

It replaces the Available Skills section while leaving the rest of the root README alone. The workflow uses Bash, Read, and Edit; it explicitly avoids Grep. A skill without SKILL.md or the required metadata is skipped with a warning. If the README has no Available Skills section, the command stops with an error, so the file needs manual attention.

What it helps with

  • refresh the README table after changing skills/
  • collect skill names and descriptions from SKILL.md files
  • group and sort skills by category
  • replace the skills section without changing other README sections

Example prompts for the agent

  • Refresh the Available Skills table in the root README.md from the current skills/ directory.
  • Rebuild the skills list, using the metadata in each SKILL.md.
  • Update the README skills table and keep its other sections unchanged.

How to install sync-skills-readme

Manually: put the files in place

.claude/commands/sync-skills-readme.md

Call it with /sync-skills-readme. For all projects use ~/.claude/commands/

Questions about sync-skills-readme

How do I install sync-skills-readme in Claude Code?

Place the command file at .claude/commands/sync-skills-readme.md.

What does sync-skills-readme do?

It reads skill metadata, assigns categories, and rebuilds the Available Skills table in the root README.md.

What happens if the README has no Available Skills section?

The command stops with an error. A skill missing SKILL.md or its name or description metadata is skipped with a warning.

Source text

sync-skills-readme.md · MIT
---
description: Sync root README.md with current skills inventory from skills/ directory
---

# Sync Skills README

Update the root README.md "Available Skills" table with all skills currently in the `skills/` directory. This command scans skills, reads their metadata, categorizes them, and regenerates the table.

## Workflow

### 1. Scan Skills Directory

Use Bash to list all skill directories:

```bash
ls -1 skills/
```

For each skill directory found, proceed to step 2.

### 2. Extract Skill Metadata

For each skill, read the SKILL.md frontmatter to extract:
- `name:` field (skill identifier)
- `description:` field (what the skill does)

Use the Read tool to read `skills/[skill-name]/SKILL.md` and extract the YAML frontmatter between the `---` markers.

**Example:**
```yaml
---
name: codex
description: Use when the user asks to run Codex CLI for code analysis...
---
```

Extract both fields for table generation.

### 3. Categorize Skills

Assign each skill to a category based on its purpose. Use this mapping:

| Category | Emoji | Keywords in name/description |
|----------|-------|------------------------------|
| AI Tools | 🤖 | codex, gemini, perplexity, ai, llm, model |
| Meta | 🔮 | command-creator, plugin-forge, plugin, command |
| Documentation | 📝 | docs, documentation, handoff, requirements, diagram, mermaid, draw, excalidraw, marp, slide, c4-architecture |
| Development | 🛠️ | session, handoff, entropy, development, workflow, database, dependency |
| Design & Frontend | 🎨 | design, frontend, ui, openapi, typescript, system |
| Utilities | 🔧 | domain, meme, web-to-markdown, utility, tool, datadog |
| Planning | 🎯 | plan, planning, spec, forge, gepetto, requirements, clarity, game-changing, features |
| Professional | 👔 | professional, communication, career, soft-skill, feedback, conversation |
| Testing | 🧪 | test, testing, qa, quality |
| Git | 📦 | commit, git, branch, pr, pull-request |

**Categorization logic:**
1. Check the skill name and description (case-insensitive)
2. Match against keywords in the table above
3. Assign to the first matching category
4. If no match, default to "Utilities" (🔧)

### 4. Generate Compact Table

Create a markdown table with this exact format:

```markdown
## 📚 Available Skills

| Category | Skill | Description |
|----------|-------|-------------|
| 🤖 AI Tools | [codex](skills/codex/README.md) | Advanced code analysis with GPT-5.2 |
| 🤖 AI Tools | [gemini](skills/gemini/README.md) | Large-scale review (200k+ context) |
...
```

**Table structure:**
- Column 1: Category emoji + name (e.g., "🤖 AI Tools")
- Column 2: Skill name as markdown link to its README
- Column 3: Short description (max ~50 chars, extracted from SKILL.md description field)

**Sorting:**
- Group by category (AI Tools first, then Meta, Documentation, Design & Frontend, Development, Planning, Professional, Testing, Git, Utilities last)
- Within each category, sort skills alphabetically by name

**Description shortening:**
- If description is longer than 50 characters, create a shortened version
- Keep it concise and action-oriented
- Examples:
  - "Use when the user asks to run Codex CLI for code analysis, refactoring, or automated editing" → "Advanced code analysis with GPT-5.2"
  - "Create comprehensive API handoff documentation for frontend developers after backend implementation" → "API handoff docs for frontend"

### 5. Update README.md

Use the Edit tool to replace the "Available Skills" section in the root README.md.

**Find and replace:**
1. Locate the section starting with `## 📚 Available Skills`
2. Find the end of the table (marked by the next `---` separator or next `##` heading)
3. Replace everything between those markers with the newly generated table

**Important:**
- Preserve the `---` separator after the table
- Do NOT modify other sections (Quick Navigation, Installation, etc.)
- Only replace the table content, keep the section heading

### 6. Report Results

After updating README.md, report to the user:

```
✅ README.md updated successfully

📊 Summary:
- Total skills: [count]
- Categories: [list of categories with counts]
- Skills added/updated: [list if any changes detected]

The Available Skills table in README.md now reflects all skills in the skills/ directory.
```

## Error Handling

**If a skill directory doesn't have SKILL.md:**
- Skip that skill
- Warn the user: "⚠️ Skipped [skill-name]: No SKILL.md found"

**If SKILL.md doesn't have required frontmatter:**
- Skip that skill
- Warn: "⚠️ Skipped [skill-name]: Missing name or description in frontmatter"

**If README.md section not found:**
- Error and stop: "❌ Could not find '## 📚 Available Skills' section in README.md"

## Tools to Use

- **Bash** - List skills directory
- **Read** - Read SKILL.md files for metadata extraction
- **Edit** - Update README.md with new table
- **DO NOT use Grep** - Read files directly for accurate frontmatter parsing

## Success Criteria

- All valid skills from skills/ directory appear in the table
- Skills are correctly categorized with appropriate emojis
- Table maintains compact format (3 columns)
- Descriptions are concise and readable
- README.md is updated without breaking other sections

© softaworks · MIT · softaworks/agent-toolkit

Similar slash commands

All slash commands for Writing and docs →

From the same set79

The whole set →
communication-excellence-coach communication-excellence-coach reviews communication drafts, calibrates tone for different audiences, and runs roleplay practice for difficult conversations. CX Codex ★ 2,707repo stars sync-branch Syncs a feature branch with the latest main via rebase. Runs on /sync-branch and updates the PR with force-push. CX Codex +1 ★ 2,707repo stars compose-email compose-email — a command for drafting professional emails using the What-Why-How framework. Provide context and get a ready-to-send draft with clear structure, matching tone, and concrete next steps. CX Codex +1 ★ 2,707repo stars viral-tweet viral-tweet converts rough draft thoughts into high-engagement posts tailored to the recommendation system of X. CX Codex +1 ★ 2,707repo stars explain-pr-changes explain-pr-changes — a command that generates detailed pull request summaries with architectural visualizations. Helps reviewers grasp the essence and impact of changes in minutes. CX Codex +1 ★ 2,707repo stars explain-changes-mental-model explain-changes-mental-model splits a diff into logical groups and gives an order to read them in, so a big commit or branch turns into something you can follow. CX Codex +1 ★ 2,707repo stars add-skill add-skill — a command to copy a skill into your project with naming validation and automatic README generation. Saves time on structure checks and documentation. CX Codex +1 ★ 2,707repo stars codex-plan codex-plan interviews you about project requirements and writes a structured planning prompt targeted at gpt-5.2-codex. CX Codex +1 ★ 2,707repo stars

Project sponsors

Companies that keep this analytics open