Skills System
Skills are Markdown files with YAML frontmatter that inject specialized prompts into conversations. Claude Code ships with 17 bundled skills and supports custom skills at project and user level.
/skill-name (like slash commands)
but they work differently: they inject a prompt into the conversation rather than running local
code. The model can also auto-invoke skills when it detects a relevant task.
Architecture
The Skills system has 7 core components that work together to load, discover, surface, and execute skills.
| Component | File | Purpose |
|---|---|---|
| SkillTool | src/tools/SkillTool/ | Tool the model invokes to execute skills |
| Bundled Skills | src/skills/bundled/ | Skills compiled into the CLI binary |
| Skill Loader | src/skills/loadSkillsDir.ts | Loads skills from disk directories |
| Skill Discovery | src/utils/skills/skillChangeDetector.ts | Dynamic detection of new skills at runtime |
| Skill Listing | src/utils/attachments.ts | Injects skill list into system-reminder each turn |
| Usage Tracking | src/utils/suggestions/skillUsageTracking.ts | Exponential decay tracking for ranking suggestions |
| Skill Improvement | src/utils/hooks/skillImprovement.ts | Post-sampling hook that auto-improves skill prompts |
Load sources (priority order)
Skills are loaded from 9 different sources. Higher priority sources override lower ones when names conflict.
| # | Source | Path | Scope |
|---|---|---|---|
| 1 | Managed (policy) | <managed_path>/.claude/skills/ | Corporate / org-wide |
| 2 | User | ~/.claude/skills/ | Personal, all repos |
| 3 | Project | .claude/skills/ (and parents up to home) | Project, shared with team |
| 4 | Additional dirs | --add-dir <path>/.claude/skills/ | Session-specific |
| 5 | Legacy commands | ~/.claude/commands/ and .claude/commands/ | Deprecated format |
| 6 | Bundled | Compiled into the binary | Built-in |
| 7 | Plugin | Installed via marketplace | Plugin-scoped |
| 8 | MCP | From connected MCP servers | Server-scoped |
| 9 | Dynamic | Discovered at runtime when files are touched | Path-conditional |
Skill file format
Skills live in .claude/skills/<name>/SKILL.md.
The directory name becomes the skill name. A legacy single-file format (<name>.md) is deprecated.
Key frontmatter fields
| Field | Type | Description |
|---|---|---|
| name | string | Display name (defaults to directory name) |
| description | string | Short description shown in skill listing |
| allowed-tools | string[] | Whitelist of tools the skill can use (e.g. Bash(npm:*), Read) |
| when_to_use | string | When the model should auto-invoke this skill |
| argument-hint | string | Hint text for arguments shown in typeahead |
| model | sonnet|opus|haiku|inherit | Override the model for this skill |
| effort | low|medium|high|max | Override the effort/thinking level |
| context | inline|fork | inline: expand in current conversation; fork: run in isolated sub-agent |
| user-invocable | boolean | Whether user can call it with /name |
| disable-model-invocation | boolean | Prevent the model from auto-invoking this skill |
| paths | string[] | Glob patterns for conditional activation when files are touched |
| hooks | object | Session-scoped lifecycle hooks (PreToolUse, PostToolUse) |
| skills | string | Comma-separated list of skills to preload when this runs |
Content variables
| Variable | Description |
|---|---|
| $ARGUMENTS or $1, $2 | Arguments passed by the user when invoking the skill |
| ${CLAUDE_SKILL_DIR} | Base directory of the skill file |
| ${CLAUDE_SESSION_ID} | Current session ID |
| !`command` | Inline shell execution: output is injected into the prompt at load time |
Bundled skills
17 skills are compiled into the binary. 10 are available to all users, 5 are Anthropic-internal only, and 2 are gated by feature flags.
Public skills (10)
Writes settings.json changes. Contains the complete settings schema, hook patterns, permissions syntax, and a 7-step hook verification flow.
Reference for editing keybindings.json. Auto-invoked when user asks about keybindings. Not user-invocable.
Reads the tail of the debug log and runs a 5-step investigation process. Suggests launching the claude-code-guide subagent.
Runs a 3-phase code review: identify changes, launch 3 parallel review agents (code reuse, code quality, efficiency), then fix issues.
Large-scale change orchestrator. Decomposes work into 5-30 units, spawns one background agent per unit with worktree isolation, tracks progress.
Schedules a recurring task via CronCreate. Converts plain English intervals to cron expressions and runs the task immediately.
Schedules remote agents via RemoteTrigger. Interactive wizard for creating, listing, and running scheduled agent tasks.
Loads 247KB of bundled API documentation. Auto-detects project language and provides task-specific routing for Claude API/SDK usage.
Activates Chrome browser automation tools. Only enabled when Chrome extension is detected.
Generates an analytical report of your Claude Code usage sessions. Lazy-loaded.
Anthropic-internal skills (5)
Verifies a code change works by actually running the application. Reference files provide examples for CLI and server verification patterns.
Generates random filler text from verified 1-token English words. Default 10,000 tokens, max 500,000. Used for long-context testing.
4-step process to capture a repeatable workflow as a SKILL.md. Interviews the user in 4 rounds via AskUserQuestion, then generates the file.
4-step memory review: gather all memory layers, classify each entry by destination (CLAUDE.md, local, team, auto), identify cleanup opportunities, present proposals.
Diagnoses frozen or slow Claude Code sessions by inspecting processes, CPU samples, and debug logs. Reports via Slack MCP. Never kills processes.
Feature-gated skills (2)
Consolidates daily logs into structured MEMORY.md entries. Runs overnight in KAIROS autonomous mode.
Bug hunting and review artifact skill.
Discovery system
Automatic surfacing
Skills are listed in system-reminder messages each turn. Budget: 1% of context window. Bundled skills are never truncated.
Path-based activation
Skills with paths: in frontmatter only activate when the model touches files matching those glob patterns.
Dynamic discovery
When reading/writing files, Claude walks parent directories looking for .claude/skills/ directories. Enables nested skill hierarchies per package.
File watcher
chokidar monitors skill directories and auto-reloads when files change. You can edit skills live during a session.
Usage tracking
Exponential decay with 7-day half-life. More recently and frequently used skills rank higher in suggestions.
Experimental search
A remote search system (EXPERIMENTAL_SKILL_SEARCH) can discover canonical skills from a backend. Cached locally with _canonical_ prefix.
Creating custom skills
Drop a SKILL.md file into any of these directories.
The directory name becomes the slash command name.
| Location | Scope | When discovered |
|---|---|---|
| ~/.claude/skills/<name>/SKILL.md | Personal, all repos | Startup |
| .claude/skills/<name>/SKILL.md | Project, shared with team | Startup + dynamic |
| <subdir>/.claude/skills/ | Nested, per-package | When files in subdir are touched |
| ~/.claude/commands/<name>.md | Personal (legacy, deprecated) | Startup |
| .claude/commands/<name>.md | Project (legacy, deprecated) | Startup |
Minimal skill
---
description: Run tests and fix failures
user-invocable: true
---
Run the test suite. If tests fail, fix them.Fork context example
Skills with context: fork run in an isolated sub-agent.
The output doesn't pollute the main context, it can use a different model, and it has its own token budget.
---
name: Security Audit
description: Run a security audit in an isolated agent
context: fork
agent: general-purpose
model: opus
effort: high
user-invocable: true
---
Perform a thorough security audit of the current codebase.
Check for OWASP top 10, hardcoded secrets, and insecure dependencies.