creating skills

the standard

related: official · tooling · frameworks · resources

skills follow the Agent Skills specification — adopted by Claude Code, Codex CLI, Cursor, Gemini CLI, GitHub Copilot, and VS Code. a skill is a directory with a SKILL.md file.

structure

my-skill/
├── SKILL.md          # required: YAML frontmatter + instructions
├── scripts/          # optional: helper scripts
├── templates/        # optional: document templates
└── resources/        # optional: reference files

template

---
name: my-skill-name
description: a clear description of what this skill does and when to use it.
---

# my skill name

detailed description.

## when to use this skill

- use case 1
- use case 2

## instructions

[instructions for Claude]

## examples

[real examples]

the description field is critical — it's what determines auto-triggering. Anthropic's skill-creator skill has a dedicated script to optimize trigger descriptions.

installation

Claude Code

# personal skills
mkdir -p ~/.claude/skills/
cp -r my-skill ~/.claude/skills/

# project skills
cp -r my-skill .claude/skills/

Claude.ai

click the skill icon (puzzle piece) in the chat interface.

API

import anthropic
client = anthropic.Anthropic(api_key="your-api-key")
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    skills=["skill-id-here"],
    messages=[{"role": "user", "content": "your prompt"}]
)

tools for building skills

skill-creator — Anthropic's official meta-skill. interactive Q&A, eval framework, description optimizer. see official.
Skill Seekers — auto-converts documentation websites into skills.
claude-code-skill-factory (685 stars) — production-ready skill toolkit.

the key insight from the manifesto

some agents/tools combinations are good where only the description of the skill is loaded and when the model uses it, then the entire thing gets loaded. other times its not as good and all the instructions on how to use every tool are dumped into the initial prompt. — vibe coding manifesto

write short, precise descriptions. keep instructions focused. a skill that adds 2000 tokens of context to every conversation but only triggers 5% of the time is a net negative.