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 scripts
Keep 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 formats
Task skill (user-triggered action):
name: deploy description: Deploy to production disable-model-invocation: true context: fork
Deploy $ARGUMENTS:
- Run tests
- Build
- Push to deployment target
Read-only skill (restricted tools):
name: safe-reader description: Explore without modifying allowed-tools: Read, Grep, Glob
Permissions
Restrict in /permissions :
-
Skill
-
deny all skills
-
Skill(name)
-
exact match
-
Skill(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_BUDGET to override.