The Skills System

1. What Are Skills?

A skill is a named, reusable prompt workflow that Claude Code can discover and execute. Skills are stored as SKILL.md Markdown files with a YAML frontmatter header, or compiled directly into the CLI binary as bundled skills.

From the user's perspective, a skill is a slash command: /commit, /simplify, or /review-pr. From Claude's perspective, invoking a skill calls the Skill tool (Skill), which loads the full prompt, substitutes any arguments, optionally executes inline shell blocks, then injects the result into the conversation.

2. Skill Lifecycle

Every skill travels through six stages from the moment Claude Code starts to the moment Claude acts on it.

Discovery

At startup getSkillDirCommands() walks four locations in parallel and also loads legacy .claude/commands/ directories. Symlinks are resolved via realpath() so duplicate files (same content, different paths) are deduplicated before any skill reaches Claude.

Load

Each skill-name/SKILL.md file is read. Token count is estimated from frontmatter only (name + description + whenToUse) — the full body is not tokenised at startup. This keeps the skill listing fast even with hundreds of skills. The listing itself is budget-capped at 1% of the context window.

Parse

The frontmatter is parsed into a Command object. All fields (description, allowed tools, argument hints, model override, hooks, paths, effort, shell) are validated here. Skills with a paths field become conditional skills — they are stored but not surfaced to Claude until the user opens a matching file.

Substitute

When invoked, the skill body undergoes argument substitution in this order:

1. Named args: $foo, $bar (mapped by position from arguments frontmatter)
2. Indexed args: $ARGUMENTS[0], $0, $1
3. Full arg string: $ARGUMENTS
4. If no placeholder was found and args exist, they are appended as ARGUMENTS: ...
5. Shell injection: !`command` or ```! blocks (local skills only — MCP skills are blocked)
6. Special vars: ${CLAUDE_SKILL_DIR}, ${CLAUDE_SESSION_ID}

Execute

Skills run in one of two modes determined by context: fork in frontmatter:

• Inline (default): The expanded prompt is injected into the current conversation as a user message. Claude processes it in the same context window.
• Forked: The skill runs in an isolated sub-agent (runAgent()) with its own token budget. The parent conversation receives only the final text output. Ideal for self-contained tasks.

Inject

The Skill tool returns a ToolResult. For inline skills: the result carries allowedTools and an optional model override that apply to subsequent tool calls in this turn. For forked skills: a Done byline is displayed and the sub-agent's output feeds back as context.

3. Four Skill Sources & Priority

Skills can originate from four distinct sources. When two sources define a skill with the same name, the first one loaded wins (managed > user > project > bundled). Deduplication is by resolved file path, not by name, so a symlinked skill can shadow a real one.

A fifth source: MCP skills

When an MCP server exposes skills (detected by loadedFrom === 'mcp'), they are fetched at connection time and added to the command registry. MCP skills follow the same frontmatter schema but shell injection is blocked — !backtick and ```! blocks are never executed for remote, untrusted content.

Legacy: .claude/commands/

The older /commands/ directory is still supported (loadedFrom: 'commands_DEPRECATED'). It accepts both single .md files and the skill-name/SKILL.md directory format. New work should use .claude/skills/.

Live reloading

The skillChangeDetector module watches skill directories with chokidar. When any SKILL.md changes, it debounces (300 ms), fires ConfigChange hooks, then clears all memoization caches so the next invocation sees fresh skills. On Bun, stat-polling is used instead of FSWatcher to avoid a known Bun deadlock bug.

4. SKILL.md Format & Frontmatter

A skill file is plain Markdown with an optional YAML frontmatter block delimited by ---. The file must live at <skill-name>/SKILL.md (the directory name becomes the slash command name).

Field reference

5. Advanced Skill Patterns

---
paths: src/payments/**
description: "Stripe refund workflow"
---

# Stripe Refund
Steps to issue a refund via the Stripe API...

// Registering a bundled skill
registerBundledSkill({
  name: 'simplify',
  description: 'Review changed code for reuse, quality, and efficiency.',
  userInvocable: true,
  async getPromptForCommand(args) {
    return [{ type: 'text', text: SIMPLIFY_PROMPT }]
  },
})

// How getAllCommands() merges MCP and local skills
const mcpSkills = context.getAppState().mcp.commands
  .filter(cmd => cmd.type === 'prompt' && cmd.loadedFrom === 'mcp')
const localCommands = await getCommands(getProjectRoot())
return uniqBy([...localCommands, ...mcpSkills], 'name')

/myskill "hello world" foo  →  ["hello world", "foo"]

6. Key Takeaways

• 📁 Skills live at <skill-name>/SKILL.md. The directory name is the slash command. YAML frontmatter controls all metadata; the Markdown body is the prompt.
• 🔍 Claude discovers skills from four sources in priority order: managed → user → project → bundled. MCP skills are merged separately at invocation time.
• ⚡ Skills run inline (default, same conversation context) or forked (context: fork, isolated sub-agent). Fork is better for self-contained tasks; inline is better when you need mid-process steering.
• 🔒 MCP skills never execute shell injection. Only local (managed/user/project/bundled) skills can run !backtick blocks. This is a hard security boundary in the source code.
• 🎯 paths frontmatter makes a skill conditional — invisible until a matching file is opened. Use this to surface domain-specific workflows only when they are relevant.
• 💡 The skill listing is budget-capped at 1% of the context window. Bundled skill descriptions are never truncated; custom skill descriptions may be shortened if the listing exceeds budget.
• 🔄 Skill files are watched live. Saving a SKILL.md triggers a debounced reload (300 ms). No restart needed.
• ✅ Simple skills (no allowed-tools, no model override) are auto-approved without any permission prompt. More powerful skills require explicit user allow rules.

7. Quiz