Chapter 16: SKILL.md — Building Reusable AI Skills
Learning Objectives
By the end of this chapter, you will be able to:
- Define what a Skill is and explain its role in extending AI coding agents
- Describe current skill packaging conventions and their adoption across platforms
- Master SKILL.md anatomy: YAML frontmatter and markdown body
- Structure skill directories with references, scripts, and assets
- Understand skill discovery directories and their priority order
- Explain progressive loading: Discovery → Activation → Execution
- Create a complete "spec-writer" skill for SDD-compliant specifications
- Create a complete "code-reviewer" skill that reviews code against specifications
- Apply the Skill vs Rule decision framework
- Install and use community skills
- Apply best practices: token limits, reference files, when-to-use specificity
What Is a Skill?
A Skill is a packaged, reusable capability that extends what an AI coding agent can do. Unlike rules (which provide persistent context) or AGENTS.md (which provides project-level instruction), skills are task-specific and on-demand. The agent discovers skills by name and description, activates them when relevant, and follows their instructions to perform specialized workflows.
Think of a skill as a teachable moment: when the user asks for something the agent doesn't fully know—writing SDD-compliant specifications, performing a specific code review format, generating commit messages in a team format—the skill provides the missing knowledge. The agent applies it, produces better output, and the skill remains available for future use.
Skills vs. Rules vs. AGENTS.md
| Aspect | Skill | Rule | AGENTS.md |
|---|---|---|---|
| Purpose | Task-specific capability | Project convention | Project context |
| Loading | On-demand when relevant | Conditional (always, intelligent, file, manual) | Always |
| Scope | Reusable across projects | Project-specific | Project-specific |
| Size | Typically <5000 tokens | Typically <500 lines | Variable |
| When | Agent deems task relevant | Based on activation mode | Every prompt |
Skill: "When the user asks for a specification, use this template and process." Rule: "When editing TypeScript files, follow these conventions." AGENTS.md: "This project uses Express, follows REST conventions, and requires tests."
Skills Packaging Conventions
Skills currently follow a set of emerging conventions for packaging AI agent capabilities. In practice, implementations differ by platform. Common elements include:
- File format (SKILL.md with YAML frontmatter)
- Directory structure
- Discovery mechanism
- Metadata schema
Platform Support (Implementation Varies)
| Platform | Skills Support | Discovery Paths |
|---|---|---|
| Cursor | Yes | .cursor/skills/, ~/.cursor/skills/ |
| Claude Code | Yes | .claude/skills/ |
| Codex | Yes | .codex/skills/ |
| Roo Code | Via Memory Banks | .roo/ |
| Gemini CLI | Yes | Compatible paths |
| VS Code | Via extensions | Varies |
These conventions enable partial portability: a skill written for one platform can often be adapted to another with minor changes, but metadata fields, discovery paths, and activation behavior may differ.
Practical rule: treat skills as "portable with adaptation," not "write once, run everywhere."
SKILL.md File Anatomy
Every skill centers on a SKILL.md file. It has two parts: YAML frontmatter (metadata) and markdown body (instructions).
YAML Frontmatter
The frontmatter appears at the top of the file, between --- delimiters:
---
name: spec-writer
description: Writes SDD-compliant specifications from user stories and feature descriptions. Use when creating specifications, writing requirements, or converting product descriptions into structured specs.
version: 1.0.0
license: MIT
compatibility:
- cursor
- claude
- codex
metadata:
author: Your Team
category: specification
allowed-tools:
- read_file
- write
---
Required Fields
| Field | Type | Purpose |
|---|---|---|
name | string | Unique identifier. Lowercase, hyphens. Max 64 chars. |
description | string | What the skill does and when to use it. Max 1024 chars. Critical for discovery. |
Optional Fields
| Field | Type | Purpose |
|---|---|---|
version | string | Semantic version for tracking |
license | string | License (MIT, Apache-2.0, etc.) |
compatibility | array | Platforms that support this skill |
metadata | object | Author, category, tags |
allowed-tools | array | Tools the skill may use (constrains agent) |
The Description: Critical for Discovery
The agent uses the description to decide when to apply the skill. It is injected into the system prompt during discovery. Write it in third person and include both WHAT and WHEN:
Bad:
description: Helps with specs
Good:
description: Writes SDD-compliant specifications from user stories and feature descriptions. Use when creating specifications, writing requirements, converting product descriptions into structured specs, or when the user mentions "spec", "requirements", or "feature spec".
Include trigger terms: "spec", "requirements", "feature spec", "user story", "acceptance criteria". The more specific the when-to-use, the better the agent's activation decision.
Markdown Body
The body contains the instructions the agent follows when the skill is activated. Typical sections:
| Section | Purpose |
|---|---|
| Instructions | Step-by-step process |
| When to Use | Refined activation criteria |
| Process Steps | Numbered workflow |
| Examples | Concrete input/output samples |
| Templates | Output format structures |
| References | Links to detailed docs |
Skill Directory Structure
Skills are stored as directories containing SKILL.md and optional supporting files:
.cursor/skills/spec-writer/
├── SKILL.md # Required: main instruction file
├── references/ # Optional: reference documents
│ ├── spec-template.md
│ └── component-checklist.md
├── scripts/ # Optional: automation scripts
│ └── validate-spec.sh
└── assets/ # Optional: templates, examples
└── example-spec.md
SKILL.md
The main file. Keep it under 5000 tokens (roughly 500 lines) for optimal loading. Use progressive disclosure: essential content in SKILL.md, details in references.
references/
Detailed documentation the agent reads when needed. Link from SKILL.md: "For the full template, see references/spec-template.md." Keep references one level deep—deeply nested references may be partially read.
scripts/
Executable helpers. Use when the skill involves validation, transformation, or automation that is more reliable as a script than as generated code. Document how to run them.
assets/
Templates, examples, and static resources. Use for content that doesn't change and benefits from being read as a file rather than inlined.
Skill Discovery Directories
Agents discover skills by scanning configured directories. A common priority order (often first match wins when skills have the same name) is:
.agents/skills/— Project-level (emerging standard).cursor/skills/— Project-level (Cursor)~/.cursor/skills/— User/global (Cursor).claude/skills/— Project-level (Claude Code compatibility).codex/skills/— Project-level (Codex compatibility).roo/— Project-level (Roo Code Memory Banks)
Project skills (.cursor/skills/, .agents/skills/) are shared with anyone using the repository. User skills (~/.cursor/skills/) are personal and available across all projects.
When the same skill name exists in multiple locations, the project-level path typically overrides the user-level path, allowing project-specific customization.
Progressive Loading
Skills use a three-phase loading model to balance discovery cost with activation depth:
Phase 1: Discovery (~100 tokens per skill)
The agent scans skill directories and reads only name and description from each SKILL.md. This lightweight pass builds a catalog. The agent uses descriptions to rank relevance for the current task.
Phase 2: Activation (<5000 tokens)
When the agent deems a skill relevant, it loads the full SKILL.md (and optionally referenced files). The token budget is typically under 5000 tokens to avoid crowding the context. Skills that exceed this may be truncated or load only partial content.
Phase 3: Execution
The agent follows the skill's instructions. It may read referenced files, run scripts, or apply templates. Execution continues until the task is complete or the agent determines the skill no longer applies.
Implication: Write concise SKILL.md files. Put extensive content in reference files. The agent will load references when the skill instructs it to.
Tutorial: Create a Spec-Writer Skill
This tutorial walks you through creating a complete "spec-writer" skill that produces SDD-compliant specifications.
Step 1: Create the Directory
mkdir -p .cursor/skills/spec-writer/references
Step 2: Write the YAML Frontmatter
Create .cursor/skills/spec-writer/SKILL.md:
---
name: spec-writer
description: Writes SDD-compliant specifications from user stories, feature descriptions, and product requirements. Use when creating specifications, writing requirements, converting product descriptions into structured specs, or when the user mentions "spec", "requirements", "feature spec", "user story", or "acceptance criteria".
version: 1.0.0
---
# Spec-Writer Skill
## When to Use
Apply this skill when the user wants to:
- Create a new feature specification
- Convert a user story or PRD into a structured spec
- Expand a vague feature description into a complete spec
- Add missing components to an incomplete spec
## Process
1. **Gather input**: Extract or request the feature description, user story, or requirements.
2. **Identify gaps**: Use [NEEDS CLARIFICATION: specific question] for any ambiguity.
3. **Follow the template**: Produce a spec with all 10 components (see references/spec-template.md).
4. **Validate**: Ensure each acceptance criterion is Given/When/Then testable.
## The 10 Components
Every specification MUST include:
| # | Component | Purpose |
|---|-----------|---------|
| 1 | Problem Statement | Why; who; pain; impact |
| 2 | User Journeys | Narrative scenarios |
| 3 | Functional Requirements | What the system must do |
| 4 | Non-Functional Requirements | Quality attributes |
| 5 | Acceptance Criteria | Testable conditions |
| 6 | Edge Cases | Boundaries, errors |
| 7 | Constraints | What NOT to do |
| 8 | Dependencies | Internal and external |
| 9 | Observability | Logs, metrics, alerts |
| 10 | Security Requirements | Auth, encryption, audit |
## Rules
- **Focus on WHAT, not HOW**: No implementation details, tech stack, or code structure.
- **Mark ambiguities**: Use [NEEDS CLARIFICATION: specific question] — never guess.
- **Testable criteria**: Every acceptance criterion must be Given/When/Then.
- **No premature detail**: Keep abstraction appropriate for the spec phase.
## Output Format
Use the structure in [references/spec-template.md](/appendices/spec-templates).
## Example
**Input**: "Users need to reset their password by email."
**Output**: A full specification with Problem (users locked out, support burden), User Journeys (successful reset, expired link, rate limited), Functional Requirements (request, validate token, set password, rate limit), Acceptance Criteria (testable), Edge Cases (expired, invalid, already used), Constraints (no email enumeration), Dependencies (email service, user store), Observability (logs, metrics), Security (token entropy, HTTPS).
Step 3: Create the Reference Template
Create .cursor/skills/spec-writer/references/spec-template.md:
# Feature [ID]: [Name]
## Problem
[1-3 sentences. Who experiences the problem? What is the pain? What is the impact?]
- **Who**: [User role or persona]
- **Pain**: [What they experience]
- **Impact**: [Consequence of not solving]
## User Journeys
### Journey 1: [Name]
[Narrative: 2-5 sentences from user perspective]
### Journey 2: [Name]
[Alternative or error path]
## Functional Requirements
### FR-1: [Capability Name]
[Precise description]
### FR-2: [Capability Name]
[Precise description]
## Non-Functional Requirements
### NFR-1: [Attribute] — [Measurable target]
[Description]
## Acceptance Criteria
- **AC-1**: Given [precondition], When [action], Then [expected result]
- **AC-2**: Given [precondition], When [action], Then [expected result]
## Edge Cases
- **EC-1**: [Boundary or error condition]
- **EC-2**: [Boundary or error condition]
## Constraints
- **C-1**: [What must NOT happen]
- **C-2**: [What must NOT happen]
## Dependencies
### Internal
- [Service/component]: [operations needed]
### External
- [System]: [integration required]
## Observability
### Logs
- [Event]: [fields to log]
### Metrics
- [metric_name]: [description]
### Alerts
- [Condition]: [action]
## Security Requirements
- **SEC-1**: [Auth, crypto, or audit requirement]
- **SEC-2**: [Auth, crypto, or audit requirement]
Step 4: Test the Skill
In Cursor, prompt:
"Create a specification for: Users need to export their data to CSV. Include all 10 components. Use the spec-writer skill."
Expected behavior: The agent loads the spec-writer skill and produces a complete, structured specification following the template.
Tutorial: Create a Code-Reviewer Skill
This tutorial creates a "code-reviewer" skill that reviews code against specifications.
Step 1: Create the Directory
mkdir -p .cursor/skills/code-reviewer/references
Step 2: Write the SKILL.md
Create .cursor/skills/code-reviewer/SKILL.md:
---
name: code-reviewer
description: Reviews code against specifications, constraints, and coding standards. Use when reviewing pull requests, examining code changes, validating implementation against specs, or when the user asks for a code review.
version: 1.0.0
---
# Code-Reviewer Skill
## When to Use
Apply this skill when the user wants to:
- Review code for spec compliance
- Validate implementation against a specification
- Check code against project constraints
- Perform a structured code review
## Process
1. **Load context**: Read the specification (if provided) and the code under review.
2. **Map requirements**: For each acceptance criterion, identify the implementing code.
3. **Check compliance**: Verify each AC is satisfied. Note gaps.
4. **Check constraints**: Verify no constraint violations.
5. **Check quality**: Assess readability, error handling, tests.
6. **Report**: Use the output format below.
## Review Dimensions
### Spec Compliance
- Every acceptance criterion has implementing code
- Edge cases are handled
- Constraints are respected
### Code Quality
- Logic is correct
- Error handling is comprehensive
- Functions are focused
- Naming is clear
### Security
- No obvious vulnerabilities (injection, XSS, etc.)
- Auth/authz used correctly
- Sensitive data handled properly
### Tests
- Acceptance criteria have test coverage
- Edge cases are tested
- Tests are meaningful (not just pass)
## Output Format
```markdown
# Code Review: [Feature/PR name]
## Spec Compliance
| AC | Status | Notes |
|----|--------|-------|
| AC-1 | ✅/❌ | [Brief note] |
| AC-2 | ✅/❌ | [Brief note] |
## Constraint Check
| Constraint | Status | Notes |
|------------|--------|-------|
| [Constraint] | ✅/❌ | [Brief note] |
## Findings
### Critical (must fix)
- [Finding]
### Suggestions (consider)
- [Finding]
### Nice to have
- [Finding]
## Summary
[2-3 sentence overall assessment]
Severity Levels
- Critical: Spec violation, constraint violation, security issue, broken logic
- Suggestion: Quality improvement, better error handling, clearer code
- Nice to have: Optional enhancement, style preference
### Step 3: Test the Skill
Provide a specification and code, then prompt:
> "Review this code against the specification. Use the code-reviewer skill. Provide the full review report."
**Expected behavior**: The agent produces a structured review with spec compliance table, constraint check, and findings by severity.
---
## Skill vs Rule: Decision Framework
When should you create a **Skill** vs a **Rule**?
### Create a Skill When:
- The task is **specialized** and not needed for every conversation
- The instructions are **substantial** (process, templates, examples)
- The capability is **reusable across projects**
- The agent should **activate on recognition** of the task type
- You want **progressive loading** (discovery first, full load on activation)
**Examples**: Spec-writing, code review, commit message generation, database schema analysis, API client generation.
### Create a Rule When:
- The guidance applies to **many or all** edits in a file type
- The content is **concise** (under 50 lines typical)
- It encodes **project-specific conventions**
- It should apply **whenever** certain files are open
- You want **always-on** or **file-triggered** activation
**Examples**: TypeScript error handling pattern, React component structure, API naming conventions, test file format.
### Create AGENTS.md Content When:
- The guidance is **project-wide** and **always relevant**
- It's **foundational** (architecture, stack, workflow)
- It doesn't fit the "task-specific" or "file-specific" model
**Examples**: "This project uses Express. All endpoints require auth. Tests go in __tests__."
### Decision Tree
Is it project-wide and always relevant? YES → AGENTS.md NO ↓
Is it file-type or session triggered? YES → Rule NO ↓
Is it a specialized task with substantial instructions? YES → Skill NO → Consider Rule or inline in prompt
---
## Installing Community Skills
Community skills can be installed via package managers or manual copy.
### Using npx (when available)
```bash
npx agent-skills install spec-writer
This fetches the skill from a registry and installs it to the appropriate directory.
Manual Installation
- Clone or download the skill repository
- Copy the skill directory to
.cursor/skills/(project) or~/.cursor/skills/(user) - Verify SKILL.md has correct frontmatter
Verifying Installation
List skills in Cursor: the skill should appear in the skill picker or be discoverable when you prompt for a task that matches its description.
Best Practices
1. Keep SKILL.md Under 5000 Tokens
Long skills consume context. Use progressive disclosure: essential instructions in SKILL.md, details in reference files.
2. Reference Files Instead of Inlining
Instead of:
## Template
[500 lines of template]
Use:
## Template
See [references/spec-template.md](/appendices/spec-templates).
The agent reads the file when needed. Saves tokens during discovery and activation.
3. Be Specific About When-to-Use
Vague: "Helps with specifications." Specific: "Writes SDD-compliant specifications. Use when creating specs, converting user stories, or when the user mentions 'spec', 'requirements', 'acceptance criteria'."
Specific descriptions improve activation accuracy.
4. Write in Third Person
The description is injected into the system prompt. Use third person:
- ✅ "Processes Excel files and generates reports"
- ❌ "I can help you process Excel files"
5. Include Trigger Terms
Add keywords the user might say: "spec", "requirements", "review", "commit message", "test generation". These help the agent match the skill to the request.
6. Provide Concrete Examples
Examples anchor the agent. Show input → output pairs. For workflows, show a complete example.
7. One Concern Per Skill
Don't combine spec-writing and code review in one skill. Split into focused skills. The agent can activate multiple skills when needed.
8. Version Your Skills
Use the version field. When you update a skill, increment the version. This helps track changes and debug activation issues.
9. Test Skills with Edge Cases
Verify your skill with:
- Minimal input (does it ask for more or fail gracefully?)
- Ambiguous input (does it use [NEEDS CLARIFICATION]?)
- Complex input (does it handle all components?)
- Wrong input (does it reject or correct?)
10. Document Skill Dependencies
If your skill assumes certain project structure (e.g., specs/features/), document it. If it requires specific tools (e.g., npx), note them. Users should know prerequisites before installing.
Skill Debugging and Troubleshooting
Skill Not Activating
Symptoms: Agent doesn't use the skill when you expect it to.
Checks:
- Description: Does it include trigger terms the user might say?
- Location: Is the skill in a discovery directory? Check priority order.
- Name: Unique? No conflict with another skill?
- Format: Valid YAML frontmatter? No syntax errors?
Skill Activates but Produces Poor Output
Symptoms: Agent uses the skill but output doesn't follow instructions.
Checks:
- Instructions: Are they clear and unambiguous? Add examples.
- Token limit: Is the skill truncated? Move content to references.
- Conflicting context: Do rules or AGENTS.md contradict the skill?
- Examples: Are they representative? Add more diverse examples.
Skill Loads Slowly or Times Out
Symptoms: Delay when agent activates the skill.
Checks:
- Size: Is SKILL.md under 5000 tokens?
- References: Are referenced files large? Consider summarizing.
- Scripts: Do scripts run slowly? Optimize or document expected duration.
Skill Composition and Chaining
Skills can build on each other. A spec-writer skill's output can feed a plan-generator skill. Consider:
Sequential Chaining
User: "Write a spec for X, then create an implementation plan."
- Agent activates spec-writer, produces spec
- Agent activates plan-generator (or equivalent), uses spec as input
- Output: spec + plan
Conditional Chaining
User: "Review this code. If it passes, suggest improvements. If it fails, list fixes."
- Agent activates code-reviewer
- Based on findings, agent either suggests improvements or lists fixes
Shared References
Multiple skills can reference the same project documents (constitution, constraints). Ensure consistency: if the constitution changes, all skills that reference it stay aligned.
Try With AI
Prompt 1: Skill Discovery
"List the skills available in this project. For each, summarize the name and description. Which would you apply if I asked you to 'write a specification for user login'? Explain your reasoning."
Prompt 2: Skill Creation
"I need a skill for [describe task]. Create a SKILL.md with: (1) YAML frontmatter with name and description, (2) when-to-use section, (3) process steps, (4) output format or template. Keep it under 200 lines. What reference files would you add?"
Prompt 3: Skill vs Rule
"I want to enforce [describe convention or task]. Should this be a Skill, a Rule, or AGENTS.md content? Use the decision framework: project-wide? file-triggered? task-specific? Explain your reasoning and draft the appropriate artifact."
Prompt 4: Skill Improvement
"Review this skill: [paste SKILL.md]. Evaluate: (1) Is the description specific enough for discovery? (2) Is it under 5000 tokens? (3) Does it use progressive disclosure? (4) Are there concrete examples? Suggest specific improvements."
Practice Exercises
Exercise 1: Spec-Writer Skill Extension
Take the spec-writer skill from the tutorial. Add a references/component-checklist.md that lists a pre-output checklist: "Before finalizing the spec, verify: [ ] All 10 components present, [ ] No [NEEDS CLARIFICATION] unresolved, [ ] Every AC is Given/When/Then, [ ] Edge cases cover boundaries and errors." Update SKILL.md to reference this checklist in the process. Test with a new spec request.
Expected outcome: The agent uses the checklist before producing the spec, resulting in more complete output.
Exercise 2: Domain-Specific Skill
Create a skill for a domain you work in: e.g., "API design", "database migration", "E2E test generation". Include: frontmatter, when-to-use, process, and at least one reference file. Test it with a relevant prompt.
Expected outcome: A working skill that the agent activates and applies correctly for your domain.
Exercise 3: Skill Audit
Audit an existing skill (yours or from the community). Check: token estimate (use ~4 chars per token), description quality, progressive disclosure, examples. Write a one-page audit report with specific recommendations.
Expected outcome: An audit document that could guide skill improvement.
Key Takeaways
-
Skills are packaged, on-demand capabilities that extend AI agents. They are task-specific and reusable across projects.
-
Skills packaging conventions improve portability across Cursor, Claude Code, Codex, Gemini CLI, and VS Code, but practical adaptation is often required.
-
SKILL.md anatomy: YAML frontmatter (name, description required) + markdown body (instructions, when-to-use, process, examples).
-
Skill directory structure: SKILL.md + references/ + scripts/ + assets/. Use references for detailed content; keep SKILL.md under 5000 tokens.
-
Discovery order: .agents/skills/ → .cursor/skills/ → ~/.cursor/skills/ → .claude/skills/ → .codex/skills/.
-
Progressive loading: Discovery (name+description) → Activation (full SKILL.md) → Execution (follow instructions).
-
Skill vs Rule: Skills for task-specific, substantial, on-demand capabilities. Rules for file-scoped, concise, conditional conventions.
-
Best practices: Concise descriptions with trigger terms, third person, reference files over inlining, one concern per skill.
Chapter Quiz
-
What is a Skill, and how does it differ from a Rule and AGENTS.md in terms of loading and purpose?
-
What are the required fields in SKILL.md frontmatter? Why is the description especially critical?
-
Describe the skill directory structure. What goes in references/ vs scripts/ vs assets/?
-
List the skill discovery directories in priority order. What is the difference between project and user skills?
-
Explain progressive loading. What happens in Discovery, Activation, and Execution? Why does token count matter?
-
When should you create a Skill vs a Rule? Use the decision framework to explain.
-
What are three best practices for writing effective skills? Give a concrete example for each.
-
You want to add a skill that generates commit messages in your team's format. What would you include in the SKILL.md? What might go in a reference file?