| name | skill-craft |
| description | Create, review, and improve high-quality Agent Skills that follow proven engineering patterns. Use this skill whenever the user wants to create a new skill, improve an existing skill, review a skill for quality, convert a workflow into a reusable skill, or mentions "create skill", "write skill", "skill quality", "SKILL.md" — even if they just say "turn this into a skill" or "make this repeatable" (in any language).
|
| version | 1.0.0 |
| license | MIT |
Skill Craft
Create Agent Skills that are clear, maintainable, and effective. A well-crafted
skill turns a one-off AI interaction into a repeatable, high-quality workflow that
works reliably across different projects and contexts.
Most skills fail not because of bad instructions, but because of bad architecture:
they're too long for the AI to hold in context, too vague for consistent results,
or too rigid to adapt across projects. This skill teaches the structural patterns
that avoid those failure modes.
When to activate
- User wants to create a new skill from scratch
- User wants to improve or refactor an existing skill
- User says "turn this into a skill" or "make this repeatable"
- User wants a quality review of a SKILL.md file
- User mentions "skill quality", "SKILL.md best practices"
Skill anatomy
Every skill follows this structure:
skill-name/
├── SKILL.md (required — the only file the AI reads first)
├── references/ (optional — detailed docs loaded on-demand)
│ ├── topic-a.md
│ └── topic-b.md
├── scripts/ (optional — executable code for deterministic tasks)
│ └── helper.py
└── assets/ (optional — templates, icons, fonts used in output)
└── template.html
Three-level loading (progressive disclosure)
This is the most important architectural pattern. It controls how much context
the AI consumes, which directly affects response quality:
| Level | What | Context cost | When loaded |
|---|
| L1: Metadata | name + description in frontmatter | ~100 words | Always — this is how the AI decides whether to use the skill |
| L2: SKILL.md body | Instructions, workflow, rules | <500 lines ideal | When the skill triggers |
| L3: Bundled resources | references/, scripts/, assets/ | Unlimited | On-demand, only when a specific phase needs them |
Why this matters: An AI reading a 2000-line SKILL.md will lose focus on the
early instructions by the time it reaches the end. Progressive disclosure keeps
the orchestration layer lean and loads details only when needed — the same
principle behind lazy loading in software.
Workflow
Phase 1 — Capture intent
Start by understanding what the skill should do. Extract from conversation
context or ask directly:
- What: What should the AI be able to do with this skill?
- When: What user phrases or contexts should trigger it?
- Output: What does the final output look like?
- Constraints: What must the skill NOT do? What tools does it need?
- Audience: Who will use this skill — technical users, non-technical, both?
If the current conversation already contains a workflow the user wants to
capture (e.g., they say "turn this into a skill"), extract answers from the
conversation history: the tools used, the sequence of steps, corrections the
user made, input/output formats observed.
Phase 2 — Architect the skill
Before writing any instructions, decide the structural layout.
Decision tree for file organization:
Is the skill workflow > 300 lines of instructions?
├─ No → Single SKILL.md, no reference files
└─ Yes → Split by phase:
├─ Core orchestration → SKILL.md (<500 lines)
├─ Detailed procedures → references/
├─ Output templates → root level or assets/
└─ Deterministic scripts → scripts/
What goes WHERE:
| Content type | Location | Reason |
|---|
| Trigger logic, workflow overview, rules | SKILL.md | Must be in L2 context for orchestration |
| Detailed step-by-step procedures | references/ | Only needed during specific phases |
| Scoring criteria, deduction tables | references/ | Heavy detail, loaded during scoring only |
| Output templates (reports, prompts) | Root level | Referenced by name from SKILL.md |
| Helper scripts, code generation | scripts/ | Executed as black boxes, not loaded into context |
| Static assets (HTML templates, fonts) | assets/ | Used in output generation |
Reference files need a map. At the bottom of SKILL.md, include a reference
table so the AI knows which file to read and when:
## Reference files
| File | Purpose | When to read |
|------|---------|-------------|
| [references/scanning.md](...) | Phase 1 procedures | Before scanning |
| [references/scoring.md](...) | Deduction criteria | During Phase 3 |
Phase 3 — Write the skill
Read references/patterns-catalog.md for the
complete catalog of proven writing patterns with examples.
Key principles:
1. Write a "pushy" description.
The description field is the primary trigger mechanism. AI models tend to
under-trigger skills — they err on the side of not using them. Combat this by
making the description generously inclusive about when to activate.
description: Create MCP servers for external API integration.
description: >
Guide for creating high-quality MCP servers that enable LLMs to interact
with external services through well-designed tools. Use when building MCP
servers to integrate external APIs or services, whether in Python or
TypeScript. Also use when the user mentions "MCP", "tool integration",
"external API", or wants to connect AI to any third-party service.
2. Explain the WHY, not just the WHAT.
Today's AI models are smart. When they understand why an instruction exists,
they can adapt it intelligently to edge cases. When they only know what to do,
they follow it rigidly and break on anything unexpected.
# Weak — rigid, no context:
ALWAYS run lints after each file edit.
# Strong — explains the reasoning:
Run lints after each file edit. Vibe-coded changes often introduce subtle
errors that compound if left unchecked — catching them immediately prevents
cascading failures in later steps.
3. Use imperative mood, present tense.
Write instructions as direct commands: "Read the file", "Run the scan",
"Ask the user". Avoid passive voice and conditional hedging.
4. Structure for scannability.
The AI reads the full SKILL.md on every invocation. Use tables, short
paragraphs, and clear headers so it can quickly find the relevant section
for the current task. Walls of text get lost in the attention window.
5. Include concrete examples.
Examples ground abstract instructions. Show input/output pairs, command
invocations, and expected results.
6. Define fallbacks for every external tool.
Any tool can fail. If your skill depends on npx some-tool, include what
to do when it fails: manual alternative, graceful degradation, or explicit
skip-and-document.
7. End with a rules section.
Rules are the hard constraints that override everything else. Keep them
numbered, short, and unambiguous. Rules exist for things the AI might
otherwise get wrong — if the instruction is obvious, it doesn't need a rule.
Phase 4 — Review & refine
After writing, evaluate the skill against the quality checklist:
Structure quality:
Instruction quality:
Robustness:
Content hygiene:
Improving an existing skill
When reviewing or improving a skill, follow this diagnostic sequence:
- Read the full SKILL.md and all referenced files.
- Check the structure against the checklist above.
- Identify the #1 problem — usually one of:
- Too long (>500 lines, needs progressive disclosure)
- Too vague (missing examples, unclear workflow)
- Too rigid (all MUSTs, no WHY explanations)
- Missing fallbacks (breaks when a tool is unavailable)
- Poor description (under-triggers, misses valid use cases)
- Fix the #1 problem first, then re-evaluate.
- Generalize from specific feedback. If a skill fails on a test case,
don't add a narrow patch — understand why it failed and fix the underlying
pattern so it works across similar cases.
Common refactoring moves
| Symptom | Refactoring |
|---|
| SKILL.md > 500 lines | Extract detailed procedures to references/ |
| Same code generated in every invocation | Bundle it as a script in scripts/ |
| Inconsistent output format | Add a template file in root or assets/ |
| Description doesn't trigger reliably | Rewrite as "pushy" with more trigger phrases |
| Instructions ignored in long skills | Move critical rules to the top, not the bottom |
| Tool failures crash the workflow | Add explicit fallback blocks |
Rules
- SKILL.md stays under 500 lines. If approaching the limit, extract detail
into reference files. This is a hard constraint — longer skills degrade AI
performance because instructions at the end receive less attention.
- Description is the trigger. Invest disproportionate effort in the
description field. A perfect skill with a bad description never activates.
- Every reference file needs a reason to exist. Don't split for the sake
of splitting. A file in
references/ should contain >50 lines of detail
that's only needed during a specific phase.
- Explain, don't command. Replace rigid MUSTs with reasoning. The AI
follows reasoned instructions more reliably than arbitrary commands.
- Fallbacks are not optional. Any workflow step that depends on an external
tool must have a documented fallback path.
- Test with edge cases. After writing, mentally run the skill against:
a trivial project, a massive monorepo, a non-standard stack, and a user
who gives minimal context. If any of these break the workflow, fix it.
- Version your skills. Use semantic versioning in the frontmatter. Bump
patch for fixes, minor for new features, major for breaking workflow changes.
Reference files
Skill Craft v1.0.0 — Built on patterns from anthropics/skills
