Write Skills

Create Agent Skills that are spec-compliant, concise, and effective. A skill is a directory containing a SKILL.md file with YAML frontmatter and Markdown instructions that extend agent capabilities.

When to Use

• User asks to “create a skill”, “write a SKILL.md”, or “make this reusable”
• Packaging a workflow, domain expertise, or tool integration as a shareable skill
• Turning a successful task pattern into a repeatable capability
• Reviewing or improving an existing skill

Skill Creation Workflow

Step 1: Understand the Domain

Before writing, identify:

1. What capability does this skill provide?
2. When should an agent activate this skill? (trigger phrases, task types)
3. What does the agent NOT already know? (only add novel context)
4. What’s the failure mode without this skill? (guides what to include)

Step 2: Create the Directory

# Using the skills CLI
npx skills init my-skill-name

# Or manually
mkdir my-skill-name && touch my-skill-name/SKILL.md

Step 3: Write the SKILL.md

Every SKILL.md has two parts: YAML frontmatter and Markdown body.

Frontmatter Rules

---
name: my-skill-name
description: Does X and Y. Use when the user asks about Z or needs to accomplish W.
---

Required fields:

Optional fields:

Name conventions (prefer gerund form):

• processing-pdfs, analyzing-data, writing-tests
• Also acceptable: pdf-processing, data-analysis
• Avoid: helper, utils, tools, vague nouns

Description rules:

• ALWAYS third person (“Processes files…” not “I process files…” or “You can use this to…”)
• Include BOTH what it does AND when to activate
• Include specific trigger keywords agents use for discovery
• Be specific: “Generates commit messages by analyzing git diffs” not “Helps with git”

Body Content Rules

The Markdown body is loaded when the skill activates. Every token competes with conversation context.

Core principle: The agent is already smart. Only add what it doesn’t know.

Challenge every line:

• “Does the agent need this explanation?” (probably not for common knowledge)
• “Does this paragraph justify its token cost?” (cut if no)
• “Am I explaining what a PDF is?” (don’t)

Target: under 500 lines. If longer, split into reference files.

Step 4: Structure the Body

Use this skeleton, adapting sections to the skill’s domain:

# Skill Title

Brief one-line purpose statement.

## When to Use

Bullet list of activation triggers and scenarios.

## Instructions

Step-by-step workflow. Use numbered steps for sequential tasks,
bullets for parallel/unordered items.

## Examples (if needed)

Input/output pairs showing expected behavior.

## Common Pitfalls (if needed)

Known failure modes and how to avoid them.

Degrees of freedom – match specificity to fragility:

Step 5: Add Reference Files (If Needed)

When SKILL.md exceeds ~300 lines, split into progressive disclosure:

my-skill/
├── SKILL.md              # Overview + navigation (<500 lines)
├── references/
│   ├── api-reference.md  # Loaded on demand
│   └── examples.md       # Loaded on demand
└── scripts/
    └── validate.py       # Executed, not loaded into context

Rules for references:

• Keep references ONE level deep from SKILL.md (no nested chains)
• Link explicitly: See [API Reference](references/api-reference.md) for details
• Files >100 lines should have a table of contents at top
• Use forward slashes in paths (even on Windows)

Step 6: Validate

Check the skill against these criteria before shipping:

Validation Checklist:
- [ ] name: lowercase, hyphens, 1-64 chars, matches directory
- [ ] description: third person, includes triggers, <1024 chars
- [ ] Body: under 500 lines
- [ ] No time-sensitive information (dates, "current version")
- [ ] Consistent terminology throughout
- [ ] No unnecessary explanations of common knowledge
- [ ] References are one level deep (no nested chains)
- [ ] All file paths use forward slashes
- [ ] Scripts handle errors explicitly (no punting to agent)

If the skills-ref CLI is available:

skills-ref validate ./my-skill

Quality Patterns

Effective Descriptions (Examples)

# Good - specific, includes triggers
description: Generates release notes from git history using conventional commits. Use when asked to create a changelog, write release notes, or summarize changes between versions.

# Good - clear capability + activation
description: Reviews React components for performance anti-patterns and suggests optimizations. Use when writing, reviewing, or refactoring React/Next.js code.

# Bad - vague
description: Helps with code.

# Bad - first person
description: I can help you write better code.

Workflow Pattern

For multi-step tasks, provide a copyable checklist:

## Workflow

Copy this checklist and track progress:

- [ ] Step 1: Analyze input
- [ ] Step 2: Generate plan
- [ ] Step 3: Validate plan
- [ ] Step 4: Execute
- [ ] Step 5: Verify output

Feedback Loop Pattern

For tasks requiring validation:

1. Generate output
2. Run validation: `python scripts/validate.py output.json`
3. If validation fails:
   - Review error messages
   - Fix issues
   - Re-validate
4. Only proceed when validation passes

Template Pattern

Provide output templates when format consistency matters:

## Output Format

Use this structure:

```markdown
# [Title]

## Summary
[One paragraph]

## Details
[Structured content]
```

Conditional Workflow Pattern

Guide through decision points:

## Choose Your Path

1. Determine the task type:
   - **Creating from scratch?** -> Follow "Creation" section
   - **Modifying existing?** -> Follow "Editing" section

Anti-Patterns to Avoid

Publishing

Once the skill is ready, publish it so others can install it:

1. Push the skill directory to a GitHub repository
2. Users install with: npx skills add owner/repo
3. The skill appears on the skills.sh leaderboard via anonymous telemetry when installed
4. To list without installing: npx skills add owner/repo --list

For multi-skill repos, place skills under a skills/ directory:

my-repo/
└── skills/
    ├── skill-one/
    │   └── SKILL.md
    └── skill-two/
        └── SKILL.md

Quick Reference: Spec Constraints