title: "Skills" description: "Extend Claude Code with reusable SKILL.md modules — the evolution of custom commands" section: "Core" readTime: "10 min" badge: "NEW"

Skills: Extending Claude Code

Skills are reusable instruction modules that extend what Claude can do. Create a SKILL.md file and Claude adds it to its toolkit — invoking it automatically when relevant, or when you call it directly with /skill-name.

Skills follow the open AgentSkills.io standard, so they work across Claude Code and other compatible AI tools.

Where Skills Live

Skill directories are watched live — adding or editing a SKILL.md takes effect without restarting the session.

In monorepos, skills in nested .claude/skills/ directories are discovered automatically when Claude works with files in that subdirectory.

Anatomy of a Skill

Every skill is a directory with SKILL.md as its entry point:

my-skill/
├── SKILL.md           # Required: instructions + frontmatter
├── reference.md       # Optional: detailed docs loaded on demand
├── examples.md        # Optional: example outputs
└── scripts/
    └── helper.py      # Optional: scripts Claude can run

Minimal example

---
description: Summarize uncommitted changes and flag anything risky. Use when the user asks what changed or wants a commit message.
---
 
## Current changes
 
!`git diff HEAD`
 
## Instructions
 
Summarize the changes above in 2-3 bullets, then list any risks — missing error handling, hardcoded values, tests that need updating. If the diff is empty, say there are no uncommitted changes.

Save to ~/.claude/skills/summarize-changes/SKILL.md, then ask "What did I change?" — Claude invokes it automatically.

Frontmatter Reference

All fields are optional. Only description is strongly recommended.

Dynamic Context Injection

The ! syntax runs shell commands before Claude sees the skill content. The output replaces the placeholder inline:

## Git status
!`git status --short`
 
## Last 5 commits
!`git log -5 --oneline`

Multi-line commands use a fenced block:

## Environment
```!
node --version
npm --version
git branch --show-current

This is preprocessing — Claude only sees the final rendered result, not the commands themselves.

---

## String Substitutions

| Placeholder | Value |
|---|---|
| `$ARGUMENTS` | Everything typed after the skill name |
| `$ARGUMENTS[0]` or `$0` | First argument |
| `$ARGUMENTS[1]` or `$1` | Second argument |
| `$name` | Named argument (declared in `arguments` frontmatter) |
| `${CLAUDE_SESSION_ID}` | Current session UUID |
| `${CLAUDE_SKILL_DIR}` | Directory containing this `SKILL.md` |
| `${CLAUDE_EFFORT}` | Current effort level |

```markdown
---
name: fix-issue
description: Fix a GitHub issue by number
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements  
3. Implement the fix
4. Write tests
5. Create a commit

Run with: /fix-issue 347

Invocation Control

Run Skills in a Subagent

Add context: fork to run the skill in an isolated context that doesn't have access to your conversation history:

---
name: pr-summary
description: Summarize a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
 
## Pull request context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`
 
## Task
Summarize this pull request: what changed, why, and what risks exist.

Built-in agent types: Explore, Plan, general-purpose, or any custom agent from .claude/agents/.

Bundled Skills

Claude Code ships with built-in skills available in every session:

Pre-Approve Tools

allowed-tools grants Claude permission to use specific tools without asking when the skill runs:

---
name: commit
description: Stage and commit changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Troubleshooting

Skill not triggering: Check that description includes keywords the user would naturally say. Run /skills to verify it's listed. Invoke directly with /skill-name to test.

Skill triggers too often: Add disable-model-invocation: true for manual-only workflows, or make the description more specific.

Skill descriptions cut short: Run /doctor to check if the skill listing budget is overflowing. Trim description text or set low-priority skills to "name-only" in skillOverrides.

Related

• Auto Memory — Claude's persistent learning system
• Hooks — Deterministic lifecycle automation
• Subagents — Parallel and isolated execution
• Plugins — Package and distribute skills