The Skill System provides a lightweight mechanism for extending Claude's behavior through markdown-based instruction files. Skills are context-injection templates that guide Claude to perform specialized tasks with domain-specific knowledge and patterns. Unlike commands (which trigger explicit actions) or hooks (which intercept lifecycle events), skills passively extend Claude's system prompt when relevant.
For information about the broader plugin architecture that can bundle skills, see Plugin System. For command definitions and slash commands, see CLI Commands & Interaction Modes.
Skills are defined using SKILL.md files with YAML frontmatter and markdown body content.
Required Fields:
name: Unique identifier for the skill (string, used in /skills menu and invocation)description: When and why Claude should use this skill (string, shown in context and UI)Optional Fields:
argument-hint: Template showing expected input format (string, must be coerced to string if using YAML syntax like [topic: foo | bar])license: Legal terms referencepermissions: List of permission patterns required for skill operationhooks: List of hook types this skill requiresThe markdown body contains instructions, guidelines, and examples that are injected into Claude's context when the skill is active:
The body content becomes part of Claude's system instructions, enabling specialized behavior without code execution.
Sources: plugins/frontend-design/skills/frontend-design/SKILL.md1-42 CHANGELOG.md61 CHANGELOG.md81
Skills are discovered from multiple locations in hierarchical order:
.claude/skills/ in the current working directory~/.claude/skills/ in the user's home directoryplugins/*/skills/ from enabled plugins.claude/skills/ in directories specified via --add-dir flagNested Discovery: Skills in subdirectories are automatically discovered when working with files in those subdirectories. For example, if you're editing src/frontend/components/Button.tsx, Claude will discover and load skills from src/frontend/.claude/skills/.
Skills provided by plugins are namespaced with the plugin name. When a plugin named frontend-design ships a skill named frontend-design, it's registered as frontend-design/frontend-design and displayed in the /skills menu with the plugin name for discoverability.
Skills support hot-reload during active sessions:
SKILL.md file is modified, it's re-parsed and updated in the registrySources: CHANGELOG.md226 CHANGELOG.md467 CHANGELOG.md208 CHANGELOG.md120
Skills compete for a limited character budget allocated from the context window:
Skills have special handling in multi-agent workflows:
Sources: CHANGELOG.md230 CHANGELOG.md118
Skills without additional permissions or hooks are automatically allowed without requiring user approval. This enables lightweight instruction-only skills to work seamlessly.
Skills that declare permissions or hooks in their frontmatter require explicit user approval before activation:
When Claude attempts to use such a skill, the user is prompted to approve it. This prevents skills from escalating privileges beyond the user's explicit consent.
Sources: CHANGELOG.md350
Numeric Values: The YAML parser may interpret bare numbers as integers. Always ensure name and description are coerced to strings:
Argument Hints: When using YAML sequence syntax in argument-hint, escape or quote properly:
The description field serves dual purposes:
/skills menu with plugin attributionWrite descriptions that clearly indicate:
Example from frontend-design:
Organize the markdown body into clear sections:
The frontend-design skill demonstrates this pattern with "Design Thinking" and "Frontend Aesthetics Guidelines" sections that provide structured decision-making frameworks.
Declare only the minimum required permissions:
Sources: plugins/frontend-design/skills/frontend-design/SKILL.md1-42 CHANGELOG.md61 CHANGELOG.md81
Plugins can bundle skills to extend Claude's capabilities without custom code:
plugins/
frontend-design/
plugin.json
README.md
skills/
frontend-design/
SKILL.md
When the frontend-design plugin is enabled, its skill becomes available as frontend-design/frontend-design in the skill registry.
Prior to version 2.1.46, skills provided by newly-installed plugins required a Claude Code restart. The hot-reload system now ensures plugin-provided skills are immediately available after installation without restart.
The plugin's plugin.json description field appears alongside skill descriptions in the UI:
This helps users understand both the plugin's purpose and the specific skills it provides.
Sources: plugins/frontend-design/README.md1-32 CHANGELOG.md120 CHANGELOG.md208
The /skills command displays all available skills with metadata:
Available Skills:
frontend-design/frontend-design (from frontend-design plugin)
Create distinctive, production-grade frontend interfaces with high
design quality. Use this skill when the user asks to build web
components, pages, or applications.
code-review/review-guidelines
Comprehensive code review checklist focusing on security, performance,
and maintainability issues.
Display Features:
--add-dir directories grouped by sourceThe character budget (2% of context) scales with the model's context window:
Users with larger context windows can see more complete skill descriptions without truncation.
Sources: CHANGELOG.md208 CHANGELOG.md230
| Extension Type | Purpose | Invocation | Context | Code Execution |
|---|---|---|---|---|
| Skills | Inject domain-specific instructions | Automatic based on relevance | System prompt augmentation | No |
| Commands | Trigger explicit actions | Slash command (/cmd) | User-initiated | Yes (via hooks) |
| Agents | Spawn specialized subagents | Task tool or slash command | Isolated subagent context | Yes (via tools) |
| Hooks | Intercept lifecycle events | Automatic at events | Hook-specific context | Yes (shell scripts) |
| MCP Servers | Provide external tools | Tool discovery | Tool input/output | Yes (external process) |
Skills are the lightest-weight extension mechanism, requiring no code and automatically integrating with Claude's reasoning process. They're ideal for providing guidelines, templates, and domain expertise that inform Claude's behavior without requiring custom tooling.
Sources: High-level system diagrams, CHANGELOG.md350
Refresh this wiki