/sync-skills-readme

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:

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:

---
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:

## 📚 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