am2rican5:skill-builder

What this skill does

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

```yaml
---
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-name> skill?"