am2rican5:skill-builder

Skill Builder

Critical Rules

• NEVER overwrite an existing SKILL.md without reading it first and showing the user what will change
• ALWAYS run scripts/validate-skill.sh after creating or updating a skill — do not skip validation
• ALWAYS use kebab-case for skill names and folder names — no spaces, capitals, or underscores
• WHEN the description exceeds 1024 characters, shorten it — trim verbose phrases, not trigger coverage
• WHEN SKILL.md exceeds 5,000 words, move detailed content to references/ and link to it
• NEVER include README.md inside the skill folder — all documentation goes in SKILL.md or references/

Instructions

Step 1: Determine Create or Update

1. IF $ARGUMENTS contains a path to an existing SKILL.md → read it and go to Step 5 (Update)
2. IF $ARGUMENTS contains a skill name → use it as the new skill name
3. IF no arguments → ask the user: "What should this skill do? Describe the workflow in 1-2 sentences."

From the user's description, derive:

• A kebab-case skill name (e.g., "generate frontend designs" → frontend-design)
• 2-3 concrete use cases the skill enables

Step 2: Write Frontmatter

Build the YAML frontmatter with ALL required and recommended fields:

---
name: <kebab-case-name>
description: <[What it does] + [When to use it] + [Key capabilities] + [Do NOT use for]>
disable-model-invocation: true
allowed-tools: "<space-separated tool list>"
compatibility: <environment requirements>
argument-hint: <expected arguments, if any>
metadata:
  author: <user or org name>
  version: 1.0.0
  category: <category>
---

Description formula — include ALL four parts:

1. What: One sentence on what the skill does
2. When: Trigger phrases users would say (include 4-6 variations)
3. Capabilities: Key things the skill enables
4. Negative triggers: "Do NOT use for..." to prevent over-triggering on adjacent use cases

Allowed-tools: Only list tools the skill actually needs. Common sets:

• Read-only analysis: "Read Glob Grep"
• File creation: "Read Write Bash Glob"
• File editing: "Read Edit Write Glob Grep"
• Full access: "Read Edit Write Bash Glob Grep"

Step 3: Write the Body

Write the skill body using this exact section structure:

## Critical Rules (5-8 rules)

• Format: NEVER/ALWAYS/WHEN X, DO Y — trigger-action only
• Put the most important safety rules first
• Include rules about validation, error handling, and user confirmation

## Instructions with numbered ### Step N: Title subsections

• Each step should be actionable and specific
• Include expected inputs, actions, and outputs
• Use code blocks for commands, file formats, and templates
• Link to references/ for detailed content that would bloat the main file

## Examples (at least 2)

• Format: "User says: ..." → brief summary of actions → "Result: ..."
• Cover the most common use case and one edge case

## Troubleshooting (at least 2 entries)

• Format: ### Problem title → **Cause:** → **Solution:**
• Cover the most likely failure modes

Step 4: Validate and Finalize

1. Write the SKILL.md file to skills/<name>/SKILL.md
2. Run validation: bash skills/skill-builder/scripts/validate-skill.sh skills/<name>/SKILL.md
3. IF validation fails → fix each reported issue and re-run
4. IF validation passes → show the user the final result

After validation passes, check progressive disclosure:

• IF word count > 3,000 → suggest extracting detailed sections to references/
• IF word count < 1,000 → the skill may be too thin — suggest adding more examples or troubleshooting

Step 5: Update an Existing Skill

WHEN updating instead of creating:

1. Read the existing SKILL.md
2. Run bash skills/skill-builder/scripts/validate-skill.sh <path-to-SKILL.md> to identify current issues
3. Present findings grouped by severity:
   • Missing fields: frontmatter gaps (allowed-tools, compatibility, etc.)
   • Missing sections: Critical Rules, Examples, Troubleshooting
   • Structural issues: word count, description length, kebab-case
   • Content quality: vague descriptions, missing negative triggers, no trigger phrases
4. For each issue, show the proposed fix with before/after
5. WAIT for user approval before applying changes
6. Apply approved changes
7. Re-run validation to confirm all issues resolved

Examples

Example 1: Creating a new skill

User says: "Create a skill for generating API documentation from OpenAPI specs"

Result: Created skills/api-doc-generator/SKILL.md with frontmatter (name, description with triggers and negative triggers, allowed-tools, compatibility), Critical Rules (5 rules), Instructions (4 steps: load spec, analyze endpoints, generate docs, validate output), 2 examples, 2 troubleshooting entries. Validation passes at 1,847 words.

Example 2: Updating an existing skill

User says: "/skill-builder skills/self-improve/SKILL.md"

Result: Read existing file, ran validation — found 2 issues (missing allowed-tools, missing compatibility). Proposed fixes with exact content. After approval, applied changes and re-validated: PASS at 628 words.

Troubleshooting

Validation fails on missing sections

Cause: The SKILL.md body is missing one of: Critical Rules, Instructions, Examples, Troubleshooting. Solution: The validator checks for ## .*<Section> headers (case-insensitive). Ensure each section uses a level-2 heading containing the exact word. For example, ## Critical Rules or ## Instructions — not ## Setup or ## Usage.

Description exceeds 1024 characters

Cause: Too many trigger phrases or verbose capability descriptions. Solution: Shorten the "What it does" part to one sentence. Use shorter trigger phrases. Keep the "Do NOT use for" clause to one sentence. Aim for 400-700 characters.

Word count over 5,000

Cause: Detailed reference content, long examples, or verbose protocol descriptions inline. Solution: Create a references/ subdirectory. Move the longest sections (usually examples or protocol specs) there. Replace inline content with a link: "See references/<file>.md for details."

Skill doesn't trigger on expected phrases

Cause: The description field is too vague or missing the user's actual vocabulary. Solution: Add more trigger phrase variations to the description. Include both formal ("orchestrate parallel agents") and casual ("run agents at the same time") phrasings. Test by asking Claude: "When would you use the skill?"