196 lines
7.2 KiB
Markdown
196 lines
7.2 KiB
Markdown
---
|
|
title: "Claude Code Skills"
|
|
aliases: [skills, custom-skills, slash-commands, claude-skills]
|
|
tags: [claude-code, skills, customization, automation, slash-commands]
|
|
sources: [raw/Extend Claude with skills.md]
|
|
created: 2026-04-17
|
|
updated: 2026-04-17
|
|
---
|
|
|
|
# Claude Code Skills
|
|
|
|
Skills extend Claude's capabilities via a `SKILL.md` file. Claude loads them automatically when relevant, or you invoke directly with `/skill-name`. They supersede the old `.claude/commands/` system — commands still work, but skills add more features.
|
|
|
|
## When to Create a Skill
|
|
|
|
- You keep pasting the same playbook or checklist into chat
|
|
- A section of `CLAUDE.md` has grown into a procedure rather than a fact
|
|
- Skill body only loads when used → long reference material costs nothing at rest
|
|
|
|
## Where Skills Live
|
|
|
|
| Scope | Path | Applies to |
|
|
|-------|------|------------|
|
|
| Enterprise | Managed settings | All org users |
|
|
| 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 plugin is enabled |
|
|
|
|
- Priority order: **enterprise > personal > project**; plugin skills use `plugin-name:skill-name` namespace
|
|
- Live reload: edits take effect within the session (no restart needed unless adding a brand-new directory)
|
|
- Monorepo: nested `.claude/skills/` in subdirectories are auto-discovered
|
|
|
|
## File Structure
|
|
|
|
```
|
|
my-skill/
|
|
├── SKILL.md # Main instructions (required, keep < 500 lines)
|
|
├── template.md # Template for Claude to fill in
|
|
├── examples/
|
|
│ └── sample.md # Example output
|
|
└── scripts/
|
|
└── helper.py # Script Claude can execute
|
|
```
|
|
|
|
Reference supporting files from `SKILL.md` so Claude knows when to load them.
|
|
|
|
## Frontmatter Reference
|
|
|
|
All fields optional; `description` is strongly recommended.
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| `name` | Display name (lowercase, hyphens, max 64 chars). Defaults to directory name. |
|
|
| `description` | What the skill does; Claude uses this to decide when to apply it. Front-load key use case. |
|
|
| `when_to_use` | Extra trigger phrases; appended to `description` in skill listing. |
|
|
| `argument-hint` | Autocomplete hint, e.g. `[issue-number]`. |
|
|
| `disable-model-invocation` | `true` = only you can invoke (not auto-triggered by Claude). |
|
|
| `user-invocable` | `false` = hidden from `/` menu; Claude-only. |
|
|
| `allowed-tools` | Tools pre-approved for this skill (no per-use prompt). Space-separated or YAML list. |
|
|
| `model` | Override model for this skill. |
|
|
| `effort` | Override effort level: `low`, `medium`, `high`, `xhigh`, `max`. |
|
|
| `context` | `fork` = run in isolated subagent. |
|
|
| `agent` | Which subagent to use when `context: fork` (e.g. `Explore`, `Plan`, `general-purpose`). |
|
|
| `hooks` | Lifecycle hooks scoped to this skill. |
|
|
| `paths` | Glob patterns; skill auto-activates only when working with matching files. |
|
|
| `shell` | Shell for inline `!` commands: `bash` (default) or `powershell`. |
|
|
|
|
## Invocation Control
|
|
|
|
| Frontmatter | You invoke | Claude invokes | In context |
|
|
|-------------|-----------|----------------|------------|
|
|
| (default) | Yes | Yes | Description always; full body on invoke |
|
|
| `disable-model-invocation: true` | Yes | No | Not in context; full body on your invoke |
|
|
| `user-invocable: false` | No | Yes | Description always; full body on invoke |
|
|
|
|
Use `disable-model-invocation: true` for side-effect workflows (`/deploy`, `/commit`, `/send-slack-message`).
|
|
|
|
## Passing Arguments
|
|
|
|
- `$ARGUMENTS` — full argument string
|
|
- `$ARGUMENTS[N]` or `$N` — positional (0-based); wrap multi-word in quotes
|
|
- If `$ARGUMENTS` absent in content, appended as `ARGUMENTS: <value>`
|
|
|
|
```yaml
|
|
---
|
|
name: fix-issue
|
|
disable-model-invocation: true
|
|
---
|
|
Fix GitHub issue $ARGUMENTS following our coding standards.
|
|
```
|
|
|
|
## Dynamic Context Injection
|
|
|
|
`` !`command` `` runs shell commands *before* Claude sees the prompt — output replaces the placeholder.
|
|
|
|
```yaml
|
|
---
|
|
name: pr-summary
|
|
context: fork
|
|
agent: Explore
|
|
allowed-tools: Bash(gh *)
|
|
---
|
|
- PR diff: !`gh pr diff`
|
|
- Changed files: !`gh pr diff --name-only`
|
|
```
|
|
|
|
Multi-line variant: fenced block opened with ` ```! `.
|
|
|
|
Disable globally: `"disableSkillShellExecution": true` in settings.
|
|
|
|
## Running in a Subagent
|
|
|
|
`context: fork` isolates the skill in a subagent — no access to conversation history.
|
|
|
|
```yaml
|
|
---
|
|
name: deep-research
|
|
context: fork
|
|
agent: Explore
|
|
---
|
|
Research $ARGUMENTS thoroughly...
|
|
```
|
|
|
|
| Approach | System prompt | Task |
|
|
|----------|--------------|------|
|
|
| Skill + `context: fork` | From agent type | SKILL.md content |
|
|
| Subagent + `skills` field | Subagent markdown | Claude's delegation message |
|
|
|
|
## Bundled Skills
|
|
|
|
Available in every session: `/simplify`, `/batch`, `/debug`, `/loop`, `/claude-api`. Prompt-based (not fixed logic). Invoke with `/skill-name`.
|
|
|
|
## Skill Content Lifecycle
|
|
|
|
- On invocation: rendered `SKILL.md` enters conversation as a message, persists for the session
|
|
- Auto-compaction: most recent invocation re-attached after summary (first 5,000 tokens per skill, 25,000 combined budget across all skills)
|
|
- If a skill stops influencing behavior → re-invoke after compaction, or strengthen `description`
|
|
|
|
## Pre-Approving Tools
|
|
|
|
```yaml
|
|
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
|
|
```
|
|
|
|
This grants those tools without per-use approval. It does NOT restrict other tools.
|
|
|
|
## Controlling Claude's Skill Access
|
|
|
|
```
|
|
# Deny all skills
|
|
Skill
|
|
|
|
# Allow specific skills
|
|
Skill(commit)
|
|
Skill(review-pr *)
|
|
|
|
# Deny specific skill
|
|
Skill(deploy *)
|
|
```
|
|
|
|
Syntax: `Skill(name)` exact match, `Skill(name *)` prefix match.
|
|
|
|
## Sharing Skills
|
|
|
|
- **Project**: commit `.claude/skills/` to version control
|
|
- **Plugin**: add `skills/` directory in your [[wiki/claude-code/create-plugins|plugin]]
|
|
- **Org-wide**: deploy via managed settings
|
|
|
|
## Troubleshooting
|
|
|
|
| Problem | Fix |
|
|
|---------|-----|
|
|
| Skill not triggering | Check description keywords; verify with "What skills are available?"; invoke directly |
|
|
| Skill triggers too often | Make description more specific; add `disable-model-invocation: true` |
|
|
| Description cut short | Trim `description`/`when_to_use`; front-load key use case; or set `SLASH_COMMAND_TOOL_CHAR_BUDGET` |
|
|
|
|
## Key Takeaways
|
|
|
|
- Skills = lazy-loaded playbooks that cost nothing until invoked
|
|
- Store globally (`~/.claude/skills/`) or per-project (`.claude/skills/`)
|
|
- `disable-model-invocation: true` for side-effect commands you want to control manually
|
|
- `user-invocable: false` for background knowledge Claude should load automatically
|
|
- `context: fork` to run skill in an isolated subagent with its own context
|
|
- Dynamic shell injection (`` !`cmd` ``) pre-populates prompts with live data before Claude sees them
|
|
- `allowed-tools` pre-approves specific tools so Claude doesn't prompt during the skill
|
|
- After auto-compaction, re-invoke large skills to restore full content
|
|
|
|
## Related
|
|
|
|
- [[wiki/claude-code/custom-subagents|Custom Subagents]] — delegate tasks to specialized agents
|
|
- [[wiki/claude-code/create-plugins|Create Plugins]] — package and distribute skills
|
|
- [[wiki/claude-code/overview|Claude Code Overview]] — full product overview
|
|
|
|
## Sources
|
|
|
|
- `raw/Extend Claude with skills.md` — official Claude Code skills documentation
|