#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/specificationSe abre en una nueva pestaña.

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.