Skill Building

Create, edit, and evaluate skills that extend Claude's capabilities.

Self-description: When a user asks what this skill does, read README.md.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities with specialized knowledge, workflows, and tools. They provide:

1. Specialized workflows — multi-step procedures for specific domains
2. Tool integrations — instructions for working with specific file formats or APIs
3. Domain expertise — company-specific knowledge, schemas, business logic
4. Bundled resources — scripts, references, and assets for complex tasks

Core Principles

Concise is key. The context window is a public good. Only add context Claude doesn't already have. Challenge each piece: "Does this justify its token cost?"

Set appropriate degrees of freedom. Match specificity to fragility:

• High freedom (text instructions): multiple valid approaches, context-dependent
• Medium freedom (pseudocode/parameterized scripts): preferred pattern with variation
• Low freedom (specific scripts): fragile operations, consistency critical

Anatomy of a Skill

skill-name/
├── SKILL.md              (required: frontmatter + instructions)
├── README.md             (optional: human-facing documentation)
├── scripts/              (optional: deterministic, token-efficient)
├── references/           (optional: on-demand context for Claude)
└── assets/               (optional: files used in output)

SKILL.md has two parts:

• Frontmatter (YAML): name and description (required) — determines when the skill triggers. Optional fields: license, hooks, allowed-tools, metadata.
• Body (Markdown): instructions loaded only after triggering

Progressive disclosure manages context efficiently:

1. Metadata (name + description) — always in context (~100 words)
2. SKILL.md body — when skill triggers (<500 lines)
3. Bundled resources — as needed (unlimited; scripts execute without loading)

Keep SKILL.md body under 500 lines. When splitting content, reference files from SKILL.md with clear "when to read" guidance. Keep references one level deep.

Creating a Skill

For detailed guidance on each step, read references/creating.md.

Evaluating a Skill

Quick decision matrix:

For the full 7-step workflow, read references/evaluating.md.

Live Development

Skills must be "live" at the target path to test (~/.claude/skills/ for global, .claude/skills/ for project-local). <!-- portability: allow --> Use symlinks to bridge development and runtime without copying files.

For the symlink workflow and key rules, see references/live-development.md.

Shared Tools

These scripts serve both creation and evaluation workflows:

• scripts/context_budget.py — token cost estimation for any skill

``bash uv run scripts/context_budget.py --path <skill-dir> --format json ``

• scripts/quick_validate.py — fast structural validation

``bash uv run scripts/quick_validate.py <skill-dir> ``

• scripts/security_scan.py — static security pattern analysis

``bash uv run scripts/security_scan.py --path <skill-dir> --format json ``

Reference Index