Authoring Skills

general

Guides users through creating effective Agent Skills. Use when the user wants to create, write, or author a new skill, or asks about skill structure, best practices, or SKILL.md format.

Authoring Agent Skills

This skill teaches you how to create and maintain skills in .skills/.

Before you begin: Always confirm with the user. Ask:

  • What workflow or codebase area needs a skill?
  • Is this truly reusable knowledge (not a one-off task)?
  • Does an existing skill already cover this?

When to Create a Skill

Create a skill when:

  • A developer workflow has specific patterns that repeat
  • Core codebase architecture requires specialized knowledge
  • Common mistakes keep happening that documentation could prevent
  • Multi-step processes need consistent execution

Do NOT create a skill for:

  • One-off tasks
  • Simple operations Claude already knows
  • Information that changes frequently

Skill Structure

.skills/
└── skill-name/
    ├── SKILL.md           # Required - main instructions
    ├── references/        # Optional - detailed docs loaded on-demand
    │   ├── GUIDE.md
    │   └── EXAMPLES.md
    ├── scripts/           # Optional - executable utilities
    │   └── validate.py
    └── assets/            # Optional - templates, schemas
        └── template.json

SKILL.md Format

Required Frontmatter

---
name: skill-name
description: Third-person description of what this does. Use when [specific triggers]. Max 1024 chars.
---

Name rules:

  • Max 64 characters
  • Lowercase letters, numbers, hyphens only
  • No consecutive hyphens (--)
  • Cannot start/end with hyphen
  • Must match directory name
  • Use gerund form: managing-database, creating-api-routes

Description rules:

  • Write in third person ("Manages..." not "I manage..." or "You can...")
  • Include what it does AND when to use it
  • Include keywords that help discovery
  • Max 1024 characters

Body Content

Keep under 500 lines. Structure for progressive disclosure:

---
name: example-skill
description: Does X and Y. Use when working with Z or when user mentions A, B, C.
---

# Title

Brief overview (2-3 sentences max).

## Quick Start

Most common operation with minimal code example.

## Core Patterns

Essential patterns, one section each.

## Common Pitfalls

What goes wrong and how to avoid it.

## Advanced Topics

For complex cases, create reference files under `references/` (and link them here). Keep references one level deep (no chains).

Progressive Disclosure

Skills load in stages to conserve context:

  1. Metadata (~100 tokens): name + description loaded at startup for ALL skills
  2. Instructions (<5000 tokens): Full SKILL.md loaded when skill activates
  3. Resources (as needed): Reference files loaded only when required

This means:

  • Put essential info in SKILL.md
  • Move detailed/lengthy content to references/
  • Keep file references ONE level deep (no chains)

Conciseness Principle

Every token competes with conversation history. Ask:

  • Does Claude already know this?
  • Does this paragraph justify its token cost?
  • Can I show an example instead of explaining?

Good (~50 tokens):

## Extract PDF text

Use pdfplumber:
\`\`\`python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
\`\`\`

Bad (~150 tokens):

## Extract PDF text

PDF files are a common format containing text and images. To extract
text, you need a library. We recommend pdfplumber because it handles
most cases well. First install it with pip...

Cross-Skill References

Reference other skills by name, not file path:

For database changes, load the `managing-database` skill.
For deployment, load the `deploying-to-vercel` skill.

Workflow Pattern

For multi-step processes, provide checklists:

## Database Migration Workflow

Copy and track progress:

\`\`\`

- [ ] Step 1: Update schema in packages/database/src/schema.ts
- [ ] Step 2: Run `bun db:generate`
- [ ] Step 3: Review generated migration
- [ ] Step 4: Commit schema + migration (CI runs `bun db:migrate`)
- [ ] Step 5: Update queries if needed
      \`\`\`

Validation Checklist

Before finalizing a skill:

  • name matches directory name
  • description is third-person with triggers
  • SKILL.md under 500 lines
  • No time-sensitive information
  • Consistent terminology
  • Reference files one level deep
  • Examples are concrete, not abstract
  • Tested by reading through as an agent would

External References

For deeper understanding, fetch these docs:

Only fetch if you need clarification on edge cases.

Example: Creating a New Skill

User asks: "We need a skill for our new payment retry system"

  1. Confirm scope: "I'll create a retrying-payments skill to document the retry patterns and failure handling. Should I proceed?"

  2. Create directory: mkdir -p .skills/retrying-payments

  3. Draft SKILL.md with frontmatter + essential patterns

  4. Move lengthy content (API reference, error codes) to references/

  5. Verify: Read through as if you're an agent encountering it fresh

  6. Update AGENTS.md: Add to the Available Skills table

Danger Zone