#Create Skill

Package a workflow, convention, or domain expertise into a reusable skill — then iterate on it.

#What a Skill Is

A markdown file with YAML frontmatter that extends an agent with specialized context. Open spec: https://agentskills.io/specificationOpen in a new tab.

Only name and description are always loaded. Body loads when description matches. References load on demand. Scripts execute without entering context. Treat the context window as a public good — every token must justify itself.

#Structure

<skill-name>/
├── SKILL.md          # Required: frontmatter + instructions
├── scripts/          # Optional: deterministic executables
├── references/       # Optional: deep docs, variant-specific guides
└── assets/           # Optional: templates, fixtures

Project scope: .claude/skills/<skill-name>/. Global scope: ~/.claude/skills/<skill-name>/. Ask user if unclear. Don't pre-create empty subdirectories.

#Progressive Disclosure

Three loading tiers — design around them:

Budgets are heuristics, not hard limits. If your body crosses ~500 lines, that's a signal to push detail into references/<topic>.md and link from the body with "read this when X". Multi-variant skills (AWS/GCP/Azure, REST/GraphQL) keep selection logic in the body and put variant detail in references/ so only the relevant file is read.

#Degrees of Freedom

Match guardrails to task fragility:

Narrow bridge → low freedom. Open field → high freedom. Over-constraining creative tasks degrades them; under-constraining fragile ones breaks them.

#Workflow

1. Capture intent. Extract from conversation first — tools used, sequence, corrections, formats. Confirm gaps with user: what should it enable, when should it trigger, what's the output, is success verifiable.
2. Pick name. kebab-case, action-oriented. Single verbs are fine (validate, refactor); verb-noun is fine (create-skill, create-delivery). Match existing project convention and check .claude/skills/ for overlap — extend instead of duplicating triggers.
3. Decide freedom level + structure. Body alone, or body + scripts, or body + references. Don't add resources speculatively.
4. Draft frontmatter + body. Imperative form. Explain why over piling on MUST. Real input → real output examples beat abstract templates.
5. Write and validate against the pre-save checklist (appendix below). Confirm with the user before writing only if the skill is large, ambiguous in scope, or replaces an existing one; for small additions, just write and show the diff.
6. Iterate on real tasks. Stop when output is good and feedback is empty — not when the skill is exhaustive.

#Frontmatter

---
name: <kebab-case-name>
description: <what it does>. Use when <triggers — user says X, Y, Z, or contexts A, B>. <Any scope or constraint>.
---

The pushiness/no-surprises balance. Two competing failures exist:

• Under-trigger — skill never fires when it should. Cause: shy description, missing trigger phrases.
• Surprise — skill fires when it shouldn't, or does something not advertised. Cause: scope creep in the description, or behaviour in the body that the description didn't promise.

Resolution: advertise broadly within the skill's real scope, never beyond it. Pushy phrasing applies to trigger coverage (synonyms, casual phrasings, implicit asks) — not to scope expansion. If you find yourself adding "and also handles X" to broaden triggers, X needs to actually work, or the description is now a lie.

Good — broad trigger coverage, accurate scope:

description: Apply SOLID/KISS/YAGNI cleanup to generated code. Use when user says "refactor", "simplify", "clean this up", "tidy", or after any code-generation skill completes. Removes over-abstraction, hidden coupling, and dead code.

#Body Template

---
name: <name>
description: <what + when>
---

# <Title>

<One-line purpose.>

## Workflow

1. <Step + why it matters>
2. <Step + why it matters>

## Example

<Concrete input → concrete output.>

## Anti-patterns

- <Mistake + why it bites>

#Iteration Loop

Skills run for thousands of future invocations, not just the case in front of you. Resist overfitting.

1. Draft skill.
2. Run on 2–3 realistic prompts (the kind a real user actually types, not abstract sketches).
3. Read transcripts, not just outputs. Look for:
   • Wasted steps the skill caused → remove the offending instructions.
   • Repeated boilerplate across runs → extract to a script (see Scripts appendix below).
   • Misinterpretations → clarify why the rule exists, not just restate it harder. A MUST wall is a yellow flag — usually a missing rationale, not a missing constraint.
4. Generalize the fix. If you're tempted to add a narrow if X then Y rule, step back — is there a framing or metaphor that covers the whole class? Narrow patches accumulate; framings compose.
5. Re-run. Stop when output is good and feedback is empty.

When a recurring pattern emerges across the project, update the relevant skill rather than re-deriving it each session.

#When NOT to Create a Skill

• Single-use task → just do it in chat.
• Project-wide convention → CLAUDE.md.
• Rule enforced by lint/types → leave it to tooling.
• Already covered by existing skill → extend that skill.
• Time-sensitive knowledge (API quirks of the week, deadlines) → don't bake it in. Skills load long after they're written, and stale facts compound across every future invocation.

#Anti-patterns

• Vague description — won't trigger.
• "When to use" only in the body — body doesn't load until the description matches. Trigger info must live in the description.
• Scope drift — adding triggers the body doesn't actually handle. Causes surprises; the inverse failure of under-triggering.
• Duplicating CLAUDE.md — project-wide rules belong there, not in a skill.
• Overfitting to today's demo case — narrow rules that don't generalize.
• Pre-creating empty scripts//references//assets/ — only add when used.
• Overlapping triggers with existing skills — check first, extend instead.

#Appendix A — Pre-Save Checklist

Run through this before declaring a skill done.

Description

• States what it does AND when to trigger
• Includes realistic user phrases ("user says X / Y / Z")
• Advertises broadly within the skill's real scope (no false advertising, no shy hedging)
• No overlap with existing skills — or extends them explicitly

Body

• Imperative form ("Run validation" not "You should run validation")
• Every rule explains why, not only what
• Examples are concrete (real input → real output)
• No MUST/NEVER walls — rationale instead
• No time-sensitive info in the main flow (or quarantined under "old patterns")
• Rare cases and deep detail live in references/, linked with "read when X"

Resources

• No empty scripts//references//assets/ directories
• Scripts solve problems, never punt back to Claude with "figure it out"
• Scripts have explicit error handling and fail loudly with useful messages
• No unjustified magic numbers
• Required packages listed in body and verified available
• Forward slashes only (no Windows paths)
• Validation step included for critical operations

Coverage

• At least 3 distinct trigger scenarios named in the description
• Tested on at least one real task before declaring done

#Appendix B — Bundling Scripts

Read this when deciding whether to add code under scripts/.

When to bundle

Add a script when:

• Same code keeps getting rewritten across runs (signal: 3+ test runs reinventing the same helper).
• Determinism matters — file transforms, parsing, formatting, anything where drift across invocations is a bug.
• Operation is fragile and must execute identically every time.

If a one-paragraph instruction works reliably, don't bundle a script. Scripts add maintenance cost.

Script rules

• Solve the problem, don't delegate. A script that says "now ask Claude to fill in X" is a leak. Either Claude handles the whole step in prose, or the script handles it deterministically. No hybrids.
• Fail loudly. Explicit error handling with useful messages — stack traces and silent exits waste the next session's debugging budget.
• No unjustified magic numbers. Constants need a comment explaining the value.
• List required packages in the skill body. And verify they're actually available in the target environment.
• Forward slashes only. No Windows paths — they break cross-platform reuse.
• Include a validation step for critical operations. Destructive or fragile work needs a self-check before committing changes.

Path conventions

Reference scripts from the body with their relative path (e.g. scripts/validate.sh). Don't hard-code absolute paths — they break when the skill is installed elsewhere.