Skills Quick Reference
Full docs: https://code.claude.com/docs/en/skills.md
Skill Locations
| Location | Path | Scope |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | All your projects |
| Project | .claude/skills/<name>/SKILL.md | This project only |
| Plugin | <plugin>/skills/<name>/SKILL.md | Where enabled |
| Enterprise | Managed settings | All org users |
Priority: enterprise > personal > project. Plugin skills use plugin:skill namespace.
Directory Structure
my-skill/
├── SKILL.md # Required - main instructions
├── reference.md # Optional - detailed docs (loaded on demand)
├── examples/ # Optional - example outputs
└── scripts/ # Optional - executable scriptsKeep SKILL.md under 500 lines; move detailed reference to separate files.
Frontmatter Reference
---
name: skill-name # Display name (defaults to directory name)
description: What it does # RECOMMENDED - helps Claude decide when to use
argument-hint: [issue-number] # Shown in autocomplete
disable-model-invocation: true # Only user can invoke via /name
user-invocable: false # Only Claude can invoke (hidden from / menu)
allowed-tools: Read, Grep, Glob # Restrict tool access
model: opus # Model override (sonnet, opus, haiku)
context: fork # Run in isolated subagent
agent: Explore # Subagent type when context: fork
hooks: ... # Skill-scoped hooks
---All fields optional. Only description is recommended.
String Substitutions
Formatting purposes: all times it would be! I have written ❗️.
| Variable | Description |
|---|---|
$ARGUMENTS | All arguments passed to skill |
$ARGUMENTS[N] / $N | Specific argument (0-indexed) |
${CLAUDE_SESSION_ID} | Current session ID |
` ❗️command ` | Dynamic injection - runs before sending |
If $ARGUMENTS not in content, args appended as ARGUMENTS: <value>.
Invocation Control
| Setting | User invokes | Claude invokes | In context |
|---|---|---|---|
| (default) | Yes | Yes | Description |
disable-model-invocation: true | Yes | No | Not loaded |
user-invocable: false | No | Yes | Description |
Subagent Execution
Add context: fork to run in isolation. Skill content becomes the subagent's task.
---
name: deep-research
context: fork
agent: Explore # or Plan, general-purpose, or custom agent name
---
Research $ARGUMENTS thoroughly...Built-in agents: Explore, Plan, general-purpose. Custom agents from .claude/agents/.
Dynamic Context Injection
Shell commands run BEFORE content sent to Claude:
---
name: pr-summary
---
PR diff: ❗️`gh pr diff`
PR comments: ❗️`gh pr view --comments`
Summarize this PR...Extended Thinking
Include "ultrathink" anywhere in skill content to enable extended thinking.
Common Patterns
Reference skill (conventions/guidelines):
---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming
- Return consistent error formatsTask skill (user-triggered action):
---
name: deploy
description: Deploy to production
disable-model-invocation: true
context: fork
---
Deploy $ARGUMENTS:
1. Run tests
2. Build
3. Push to deployment targetRead-only skill (restricted tools):
---
name: safe-reader
description: Explore without modifying
allowed-tools: Read, Grep, Glob
---Permissions
Restrict in /permissions:
Skill- deny all skillsSkill(name)- exact matchSkill(name *)- prefix match with args
Troubleshooting
- Skill not triggering: Check description keywords, verify with "What skills are available?"
- Triggers too often: Make description more specific or add
disable-model-invocation: true - Missing skills: Budget is 2% of context window. Set
SLASH_COMMAND_TOOL_CHAR_BUDGETto override.