skill-management

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:
1. Run tests
2. Build
3. 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.