skill-creator

# Skill Creator A skill is a folder that teaches an agent how to handle a specific task or workflow: ``` your-skill-name/ ├── SKILL.md # Required — YAML frontmatter + Markdown instructions ├── scripts/ # Optional — executable code (Python, Bash, ...) ├── references/ # Optional — docs loaded only when needed └── assets/ # Optional — templates, fonts, icons used in output ``` Skills rely on **progressive disclosure**: the frontmatter is always in context (so it decides *when* the skill loads), the SKILL.md body loads when relevant, and linked files load only on demand. Keep each level as small as it can be. ## Workflow: Creating a New Skill ### Step 1: Define 2-3 concrete use cases Before writing anything, pin down with the user: - What does the user want to accomplish? (outcome, not feature) - What triggers it? Collect literal phrases users would say. - What steps does the workflow require, in order? - Which tools are needed (built-in, scripts, MCP servers)? - What domain knowledge or best practices must be embedded? Write each use case as: **Trigger → Steps → Result**. If the user is vague, propose use cases and confirm rather than guessing silently. Identify the category — it shapes the structure: 1. **Document & asset creation** — embed style guides, templates, quality checklists. 2. **Workflow automation** — step-by-step process with validation gates. 3. **MCP enhancement** — orchestrate MCP tool calls in sequence with domain expertise. ### Step 2: Plan the folder structure - Folder name: kebab-case only (`my-skill` — no spaces, capitals, or underscores) and it should match the frontmatter `name`. - `SKILL.md` must be named exactly that, case-sensitive. - Never put a `README.md` inside the skill folder. - Keep SKILL.md under ~5,000 words; move detail to `references/` and link to it. - For critical validations, prefer a bundled script over prose — code is deterministic, language interpretation isn't. ### Step 3: Write the frontmatter The frontmatter is the single most important part — it alone decides whether the skill ever loads. ```yaml --- name: your-skill-name description: [What it does] + [When to use it, with literal trigger phrases] + [negative triggers if needed] --- ``` Rules (hard requirements): - `description` MUST state both WHAT the skill does and WHEN to use it, under 1024 characters. - Include specific phrases users would actually say, and file types if relevant. - No XML angle brackets anywhere in frontmatter (it is injected into the system prompt). - `name` must not use reserved prefixes ("claude", "anthropic"). Weak: `description: Helps with projects.` Strong: `description: Manages Linear sprint workflows including planning, task creation, and status tracking. Use when the user mentions "sprint", "Linear tasks", or asks to "create tickets".` Optional `disable-model-invocation: true` makes the skill user-only: the agent never sees it (no skill catalog entry, no `skill_search` hit, and the `skill` tool refuses it), while `/skill-name` still works for the user. Use it for a long or interrupting workflow whose timing the user should control — a multi-phase orchestration, a deploy, anything with side effects. Leave it off by default; a skill the agent cannot see is a skill it cannot offer. Keep the "only when the user asks" rule in the `description` and body as well, so the skill still behaves if the flag is ever removed. For all optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and more good/bad examples, read `references/frontmatter.md`. ### Step 4: Write the instructions Recommended body structure: ```markdown # Skill Name ## Instructions ### Step 1: [First major step] Exact commands / tool calls, with expected output described. ## Examples User says X → actions → result. ## Troubleshooting Error → cause → fix. ``` Best practices: - Be specific and actionable: give exact commands with flags and expected output, not vibes ("validate the data"). - Put critical instructions at the top; use `## Important` headers for must-not-skip rules. - Include error handling for the failures users will actually hit. - Reference bundled resources explicitly ("Before writing queries, read the API-patterns file in references/"). - Number steps that must happen in order; state data dependencies between steps. For proven structural patterns (sequential orchestration, multi-MCP coordination, iterative refinement, context-aware tool selection, domain-specific intelligence), read `references/patterns.md`. ### Step 5: Validate Run the bundled validator on the skill folder: ```bash python scripts/validate_skill.py /path/to/your-skill-name ``` It checks naming, frontmatter format and length, forbidden content, missing linked files, and body size. Fix every ERROR; treat WARNINGs as review prompts. Expected output on success: `PASS` with 0 errors. ### Step 6: Test and iterate Iterate on a single challenging task until it succeeds, then extract the winning approach into the skill — this gives faster signal than broad testing. Then cover: 1. **Triggering**: obvious phrasing loads it, paraphrases load it, unrelated queries don't. 2. **Function**: outputs correct, tool calls succeed, edge cases handled. 3. **Baseline comparison**: fewer corrections / tool calls / tokens than without the skill. Debugging trick: ask the agent "When would you use the [name] skill?" — it will paraphrase the description back; fix what's missing. Full test-case templates and iteration signals are in `references/testing.md`. ## Workflow: Reviewing an Existing Skill When asked to review or improve a skill: 1. Read its SKILL.md and run `python scripts/validate_skill.py <folder>`. 2. Diagnose against the common failure modes: - **Never triggers** → description too generic or missing user-facing trigger phrases. Rewrite with literal phrases and keywords. - **Triggers too often** → add negative triggers ("Do NOT use for...") and narrow the scope. - **Loads but instructions ignored** → instructions too verbose, buried, or ambiguous. Move critical rules to the top, replace prose validations with a script. - **Slow / degraded responses** → SKILL.md too large; move detail into `references/`. 3. Propose concrete edits (before/after for the description), not general advice. 4. If the user brings failure examples from real sessions, encode the fix as an explicit instruction or troubleshooting entry — that is the highest-value iteration loop. ## Quick Checklist Before delivering a skill, verify: - [ ] Folder is kebab-case and matches frontmatter `name` - [ ] `SKILL.md` exact filename; no `README.md` inside the folder - [ ] Frontmatter has `---` delimiters, `name`, and a WHAT+WHEN `description` under 1024 chars - [ ] No XML angle brackets in frontmatter - [ ] Instructions specific and actionable, with examples and error handling - [ ] Every referenced `scripts/`, `references/`, `assets/` file actually exists - [ ] `validate_skill.py` passes with 0 errors - [ ] Triggering tested: fires on target phrasings, silent on unrelated ones