Claude Skills
Overview
Claude Skills are the primary mechanism for extending the capabilities of Claude Code. They are structured, task-specific instructions that enable Claude to perform complex, multi-step workflows autonomously.
The Architecture of a Skill
A skill is more than just a prompt; it is a encapsulated “mini-agent” defined by:
SKILL.md: Contains the logic and metadata.- YAML Frontmatter: Used for Dynamic Discovery.
- On-Demand Loading: Implements Progressive Disclosure to minimize token usage.
Types of Skills
- Built-in Skills: Native capabilities (file system, terminal).
- Global Skills (
~/.claude/skills/): Personal expertise available across all projects. - Project Skills (
.claude/skills/): Repository-specific workflows, shared via Git. - Nested Skills: Localized expertise within sub-modules.
Best Practices
- Explicit Metadata: The
descriptionin YAML must accurately reflect the task to enable Dynamic Discovery. - Progressive Disclosure: Keep
SKILL.mdfocused; use associatedassets/ortemplates/folders for large resources. - Skill Injection: Use skills to enforce Spec-Driven Development patterns by creating skills for “Planning” or “Validation.”
- SubAgent Delegation inside Skills: For heavy sub-tasks within a skill, dispatch SubAgents to keep the skill’s own context window lean. The skill acts as the orchestrator; subagents handle bounded work.
Relationship with Slash Commands
While Custom Slash Commands were the initial way to create prompt shortcuts, Skills represent the evolved, agentic version. Skills provide the same manual invocation (/skill-name) but add the layer of autonomous selection by the AI.
Integration
- Claude Code: The host environment for skill execution.
- Custom Slash Commands: The manual-invocation precursor to Skills.
- MCP: Skills act as the logic layer orchestrating multiple MCP servers.
- Memory Systems: Skills use the context from
claude.mdto ground their actions.
Skills vs. Custom Subagents
| Skills | Custom Subagents | |
|---|---|---|
| Execution context | Runs in the parent conversation | Isolated context window |
| State access | Full parent context available | Only what the subagent prompt specifies |
| Tool restriction | Uses parent tools | Configurable per-agent allowlist/denylist |
| Model | Inherits parent model | Configurable (haiku, sonnet, opus) |
| Persistent memory | Via CLAUDE.md | Via memory: frontmatter field |
| Use when | Workflow needs parent context | Side task produces verbose output or needs isolation |
A Skill can internally dispatch a SubAgent for heavy sub-tasks, keeping the skill’s own context lean. A custom subagent can have skills preloaded via its skills: frontmatter field, injecting domain knowledge at startup.