Skills Development

Create skills that follow the Agent Skills specification—an open format supported by Claude Code, Cursor, VS Code, GitHub Copilot, Codex, and other agent products.

Workflow

1. Discovery — Understand what the skill should do
2. Archetype Selection — Choose the best pattern
3. Initialization — Create skill structure
4. Customization — Tailor to specific needs
5. Validation — Verify quality before committing

Stage 1: Discovery

Ask about the skill:

• What problem does this skill solve?
• What are the main capabilities?
• What triggers should invoke it? (phrases users would say)
• Where should it live? (personal, project, or plugin)
• Is it for use within a Claude plugin? If so, load the /claude-craft and /claude-plugins skills.

Stage 2: Archetype Selection

Stage 3: Directory Structure

skill-name/
├── SKILL.md           # Required: instructions + metadata
├── scripts/           # Optional: executable code
├── references/        # Optional: documentation
└── assets/            # Optional: templates, resources

Stage 4: Frontmatter Schema

---
name: skill-name
description: "What it does and when to use it. Include trigger keywords."
version: 1.0.0                         # optional, recommended
license: Apache-2.0                    # optional
compatibility: Requires git and jq     # optional
metadata:                              # optional
  author: your-org
  category: development
  tags: [testing, automation]
---

Important:

• Always wrap description in double quotes — values containing colons, commas, or special characters can break YAML parsing otherwise.
• Platform-specific fields (e.g., Claude's allowed-tools, user-invocable) should be added per-platform. Load the /claude-craft skill for Claude-specific fields.

Custom Frontmatter

Custom fields must be nested under metadata:

---
name: my-skill
description: "..."
metadata:
  author: your-org
  version: "1.0"
  category: development
  tags: [typescript, testing]
---

Top-level custom fields are not allowed and may cause parsing errors.

Description Formula

[WHAT] + [WHEN] + [TRIGGERS]

description: "Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or document extraction."

Checklist:

• Explains WHAT (capabilities)
• States WHEN (trigger conditions)
• Includes 3-5 trigger KEYWORDS
• Uses third-person voice
• Under 200 words

Stage 5: Validation

Validation Checklist

A. YAML Frontmatter

• Opens with --- on line 1, closes with ---
• name and description present (required)
• description wrapped in double quotes
• Uses spaces, not tabs
• Special characters quoted

B. Naming

• Lowercase, numbers, hyphens only (1-64 chars)
• Matches parent directory name
• No --, leading/trailing hyphens
• No anthropic or claude in name
• Does not collide with a built-in slash command

C. Description Quality

• WHAT: Explains capabilities
• WHEN: States "Use when..." conditions
• TRIGGERS: 3-5 keywords users would say
• Third-person voice (not "I can" or "you can")

D. Structure

• SKILL.md under 500 lines
• All referenced files exist
• No TODO/placeholder markers
• Progressive disclosure (details in references/)
• No <bang>`command` preprocessing patterns (use <bang> instead of literal !)

Report Format

# Skill Check: {skill-name}

**Status**: PASS | WARNINGS | FAIL
**Issues**: {critical} critical, {warnings} warnings

## Critical (must fix)
1. {issue with fix}

## Warnings (should fix)
1. {issue with fix}

## Strengths
- {what's done well}

Core Principles

Concise is key

Context window is shared. Only include what the agent doesn't already know. Challenge each paragraph—does it justify its token cost?

Third-person descriptions

Descriptions inject into system prompt:

• "Extracts text from PDFs"
• "I can help you extract text from PDFs"

Progressive disclosure

Keep SKILL.md under 500 lines. Move details to:

• references/ - Detailed docs, API references
• scripts/ - Executable utilities (code never enters context)
• assets/ - Templates, data files

Preprocessing safety

SKILL.md files are preprocessed by Claude Code — <bang>`command` syntax executes at load time, even inside code fences. When documenting this syntax in SKILL.md, use <bang> as a stand-in for !. Reference files and EXAMPLES.md are not preprocessed, so literal ! is safe there.

Skills that intentionally preprocess should declare metadata.preprocess: true. Run /skillcheck to lint for unintentional preprocessing patterns.

Token loading:

1. Metadata (~100 tokens): name + description at startup
2. Instructions (<5000 tokens): SKILL.md body when activated
3. Resources (as needed): files loaded only when referenced

Degrees of freedom

Match instruction specificity to task requirements:

• High freedom (text): Multiple valid approaches, use judgment
• Medium freedom (pseudocode): Preferred pattern with variation allowed
• Low freedom (scripts): Exact sequence required, no deviation

See patterns.md for detailed examples.

Naming Requirements

• Lowercase letters, numbers, hyphens only
• Cannot start/end with hyphen or contain --
• Must match parent directory name
• Cannot contain anthropic or claude
• Must not collide with built-in slash commands (/help, /status, /config, /compact, /review, /model, /init, /login, /logout, /doctor, /clear, /mcp, /memory, /permissions, /terminal-setup, /vim, /cost, /bug). Built-in commands take precedence — a skill with a colliding name will be unreachable via slash invocation.

Recommended: Gerund form (processing-pdfs, reviewing-code)

Platform-Specific Guidance

Skills are cross-platform, but each tool has specific implementation details:

• Claude Code: Load the /claude-craft skill for Claude-specific skill authoring
• Codex CLI: See codex.md for discovery paths, $skill-name invocation

See implementations.md for storage paths and invocations.md for activation patterns.

References

• steps-pattern.md - Composable skill workflows with dependencies
• patterns.md - Degrees of freedom, script design, variant organization
• best-practices.md - Community patterns, testing strategies
• quick-reference.md - Fast checklist and one-liners
• implementations.md - Per-tool storage paths
• invocations.md - How tools activate skills
• compatibility.md - Path compatibility matrix

External Resources

• Agent Skills Specification
• Best Practices Guide
• skills-ref Validation Library