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:

Specialized workflows — multi-step procedures for specific domains
Tool integrations — instructions for working with specific file formats or APIs
Domain expertise — company-specific knowledge, schemas, business logic
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:

Metadata (name + description) — always in context (~100 words)
SKILL.md body — when skill triggers (<500 lines)
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

| Step | Action | Details | |------|--------|---------| | 1 | Understand with examples | Gather concrete usage examples from the user | | 2 | Plan reusable contents | Identify scripts, references, and assets needed | | 3 | Initialize | scripts/init_skill.py <name> --path <dir> | | 4 | Edit | Implement resources, write SKILL.md | | 5 | Validate | scripts/quick_validate.py <path> | | 6 | Package | scripts/package_skill.py <path> | | 7 | Iterate | Improve from real usage |

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

Evaluating a Skill

| Step | Action | Tool | |------|--------|------| | 1 | Resolve source | scripts/fetch_skill.py --source <url> --skill <name> | | 2 | Structural check | skills-manager validate or manual check | | 3 | Security audit | scripts/security_scan.py --path <dir> | | 4 | Quality assessment | Manual review against rubric | | 5 | Context budget | scripts/context_budget.py --path <dir> | | 6 | Value assessment | Overlap and unique contribution analysis | | 7 | Generate report | Save to reports/<name>-<YYYY-MM-DD>.md |

Quick decision matrix:

| Security | Quality | Value | Recommendation | |----------|---------|-------|----------------| | PASS | A-B | High-Medium | ADOPT | | WARN | A-B | High | ADOPT WITH MODIFICATIONS | | FAIL | Any | Any | SKIP | | Any | D | Any | SKIP |

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). 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

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

scripts/quick_validate.py — fast structural validation
```
uv run scripts/quick_validate.py <skill-dir>
```

scripts/security_scan.py — static security pattern analysis

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

Reference Index

| File | When to read | |------|-------------| | references/creating.md | Creating or editing a skill (6-step detailed guide) | | references/evaluating.md | Evaluating a third-party skill (7-step workflow) | | references/live-development.md | Symlink workflow for testing skills during development | | references/testing-methodology.md | Testing patterns, defensive writing, rationalization prevention | | references/workflows.md | Sequential workflow and conditional logic patterns | | references/output-patterns.md | Template and example output patterns | | references/report-template.md | Evaluation report template | | references/scoring-rubric.md | Security, quality, value rating criteria | | references/security-patterns.md | Expected vs suspicious security patterns |