Self-improving AI Employees for everyone
Claude Code skills reference (verbatim snapshot)
Source: code.claude.com/docs/en/skills Fetched: 2026-05-11 Why this lives in-repo: OpenCompany materialises connected skills into
<workspace_dir>/.claude/skills/<name>/SKILL.mdbefore the pool spawns claude, and claude finds them through--add-dir <workspace_dir>— seeclaude_code_interactive_mode.md→ Tools and skills andcli_agent_canonical_patterns_rfc.md§6 R1. This is the spec we materialise against.
Extend Claude with skills
Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom commands and bundled skills.
Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with /skill-name.
Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact. Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it.
Note: Custom commands have been merged into skills. A file at
.claude/commands/deploy.mdand a skill at.claude/skills/deploy/SKILL.mdboth create/deployand work the same way. Your existing.claude/commands/files keep working. Skills add optional features: a directory for supporting files, frontmatter to control whether you or Claude invokes them, and the ability for Claude to load them automatically when relevant.
Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like invocation control, subagent execution, and dynamic context injection.
Bundled skills
Claude Code includes a set of bundled skills that are available in every session, including /simplify, /batch, /debug, /loop, and /claude-api. Unlike most built-in commands, which execute fixed logic directly, bundled skills are prompt-based: they give Claude detailed instructions and let it orchestrate the work using its tools. You invoke them the same way as any other skill, by typing / followed by the skill name.
Where skills live
Where you store a skill determines who can use it:
| Location | Path | Applies to |
|---|---|---|
| Enterprise | See managed settings | All users in your organization |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md |
All your projects |
| Project | .claude/skills/<skill-name>/SKILL.md |
This project only |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md |
Where plugin is enabled |
When skills share the same name across levels, enterprise overrides personal, and personal overrides project. Plugin skills use a plugin-name:skill-name namespace, so they cannot conflict with other levels. If you have files in .claude/commands/, those work the same way, but if a skill and a command share the same name, the skill takes precedence.
Live change detection
Claude Code watches skill directories for file changes. Adding, editing, or removing a skill under ~/.claude/skills/, the project .claude/skills/, or a .claude/skills/ inside an --add-dir directory takes effect within the current session without restarting. Creating a top-level skills directory that did not exist when the session started requires restarting Claude Code so the new directory can be watched.
Automatic discovery from parent and nested directories
Project skills load from .claude/skills/ in your starting directory and in every parent directory up to the repository root, so starting Claude in a subdirectory still picks up skills defined at the root. When you work with files in subdirectories below your starting directory, Claude Code also discovers skills from nested .claude/skills/ directories on demand.
Skill directory layout
Each skill is a directory with SKILL.md as the entrypoint:
my-skill/
├── SKILL.md # Main instructions (required)
├── template.md # Template for Claude to fill in
├── examples/
│ └── sample.md # Example output showing expected format
└── scripts/
└── validate.sh # Script Claude can execute
Frontmatter reference
Beyond the markdown content, you can configure skill behavior using YAML frontmatter fields between --- markers at the top of your SKILL.md file:
---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---
Your skill instructions here...
All fields are optional. Only description is recommended so Claude knows when to use the skill.
| Field | Required | Description |
|---|---|---|
name |
No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). |
description |
Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. Put the key use case first: the combined description and when_to_use text is truncated at 1,536 characters in the skill listing to reduce context usage. |
when_to_use |
No | Additional context for when Claude should invoke the skill, such as trigger phrases or example requests. Appended to description in the skill listing and counts toward the 1,536-character cap. |
argument-hint |
No | Hint shown during autocomplete to indicate expected arguments. Example: [issue-number] or [filename] [format]. |
arguments |
No | Named positional arguments for $name substitution in the skill content. Accepts a space-separated string or a YAML list. Names map to argument positions in order. |
disable-model-invocation |
No | Set to true to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with /name. Also prevents the skill from being preloaded into subagents. Default: false. |
user-invocable |
No | Set to false to hide from the / menu. Use for background knowledge users shouldn't invoke directly. Default: true. |
allowed-tools |
No | Tools Claude can use without asking permission when this skill is active. Accepts a space-separated string or a YAML list. |
model |
No | Model to use when this skill is active. The override applies for the rest of the current turn and is not saved to settings; the session model resumes on your next prompt. Accepts the same values as /model, or inherit to keep the active model. |
effort |
No | Effort level when this skill is active. Overrides the session effort level. Default: inherits from session. Options: low, medium, high, xhigh, max; available levels depend on the model. |
context |
No | Set to fork to run in a forked subagent context. |
agent |
No | Which subagent type to use when context: fork is set. |
hooks |
No | Hooks scoped to this skill's lifecycle. |
paths |
No | Glob patterns that limit when this skill is activated. Accepts a comma-separated string or a YAML list. When set, Claude loads the skill automatically only when working with files matching the patterns. |
shell |
No | Shell to use for !`command` and ```! blocks in this skill. Accepts bash (default) or powershell. Setting powershell runs inline shell commands via PowerShell on Windows. Requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1. |
Available string substitutions
Skills support string substitution for dynamic values in the skill content:
| Variable | Description |
|---|---|
$ARGUMENTS |
All arguments passed when invoking the skill. If $ARGUMENTS is not present in the content, arguments are appended as ARGUMENTS: <value>. |
$ARGUMENTS[N] |
Access a specific argument by 0-based index, such as $ARGUMENTS[0] for the first argument. |
$N |
Shorthand for $ARGUMENTS[N], such as $0 for the first argument or $1 for the second. |
$name |
Named argument declared in the arguments frontmatter list. Names map to positions in order, so with arguments: [issue, branch] the placeholder $issue expands to the first argument and $branch to the second. |
${CLAUDE_SESSION_ID} |
The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |
${CLAUDE_EFFORT} |
The current effort level: low, medium, high, xhigh, or max. Use this to adapt skill instructions to the active effort setting. |
${CLAUDE_SKILL_DIR} |
The directory containing the skill's SKILL.md file. For plugin skills, this is the skill's subdirectory within the plugin, not the plugin root. Use this in bash injection commands to reference scripts or files bundled with the skill, regardless of the current working directory. |
Skill content lifecycle
When you or Claude invoke a skill, the rendered SKILL.md content enters the conversation as a single message and stays there for the rest of the session. Claude Code does not re-read the skill file on later turns, so write guidance that should apply throughout a task as standing instructions rather than one-time steps.
Auto-compaction carries invoked skills forward within a token budget. When the conversation is summarized to free context, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens. Claude Code fills this budget starting from the most recently invoked skill, so older skills can be dropped entirely after compaction if you have invoked many in one session.
Inject dynamic context
The !`<command>` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself.
This skill summarizes a pull request by fetching live PR data with the GitHub CLI:
---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`
## Your task
Summarize this pull request...
When this skill runs:
- Each
!`<command>`executes immediately (before Claude sees anything) - The output replaces the placeholder in the skill content
- Claude receives the fully-rendered prompt with actual PR data
This is preprocessing, not something Claude executes. Claude only sees the final result.
For multi-line commands, use a fenced code block opened with ```! instead of the inline form.
Run skills in a subagent
Add context: fork to your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives the subagent. It won't have access to your conversation history.
Warning:
context: forkonly makes sense for skills with explicit instructions. If your skill contains guidelines like "use these API conventions" without a task, the subagent receives the guidelines but no actionable prompt, and returns without meaningful output.
Skills and subagents work together in two directions:
| Approach | System prompt | Task | Also loads |
|---|---|---|---|
Skill with context: fork |
From agent type (Explore, Plan, etc.) |
SKILL.md content | CLAUDE.md |
Subagent with skills field |
Subagent's markdown body | Claude's delegation message | Preloaded skills + CLAUDE.md |
Restrict Claude's skill access
By default, Claude can invoke any skill that doesn't have disable-model-invocation: true set. Skills that define allowed-tools grant Claude access to those tools without per-use approval when the skill is active. Your permission settings still govern baseline approval behavior for all other tools.
Three ways to control which skills Claude can invoke:
Disable all skills by denying the Skill tool in /permissions:
# Add to deny rules:
Skill
Allow or deny specific skills using permission rules:
# Allow only specific skills
Skill(commit)
Skill(review-pr *)
# Deny specific skills
Skill(deploy *)
Permission syntax: Skill(name) for exact match, Skill(name *) for prefix match with any arguments.
Hide individual skills by adding disable-model-invocation: true to their frontmatter. This removes the skill from Claude's context entirely.
Troubleshooting
Skill not triggering
If Claude doesn't use your skill when expected:
- Check the description includes keywords users would naturally say
- Verify the skill appears in
What skills are available? - Try rephrasing your request to match the description more closely
- Invoke it directly with
/skill-nameif the skill is user-invocable
Skill triggers too often
If Claude uses your skill when you don't want it:
- Make the description more specific
- Add
disable-model-invocation: trueif you only want manual invocation
Skill descriptions are cut short
Skill descriptions are loaded into context so Claude knows what's available. All skill names are always included, but if you have many skills, descriptions are shortened to fit the character budget, which can strip the keywords Claude needs to match your request. The budget scales at 1 % of the model's context window. When it overflows, descriptions for the skills you invoke least are dropped first, so the skills you actually use keep their full text. Run /doctor to see whether the budget is overflowing and which skills are affected.
To raise the budget, set the skillListingBudgetFraction setting (e.g. 0.02 = 2 %) or the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable to a fixed character count. To free budget for other skills, set low-priority entries to "name-only" in skillOverrides so they list without a description. You can also trim the description and when_to_use text at the source: put the key use case first, since each entry's combined text is capped at 1,536 characters regardless of budget. The cap is configurable with maxSkillDescriptionChars.
Related resources
- Debug your configuration: diagnose why a skill isn't appearing or triggering
- Subagents: delegate tasks to specialized agents
- Plugins: package and distribute skills with other extensions
- Hooks: automate workflows around tool events
- Memory: manage CLAUDE.md files for persistent context
- Commands: reference for built-in commands and bundled skills
- Permissions: control tool and skill access
How OpenCompany materialises skills for claude_code_agent
materialise_skills in
nodes/agent/claude_code_agent/_skills.py
walks connected_skill_names (collected by edge_walker from the
agent's input-skill handle) and writes each connected skill to
<workspace_dir>/.claude/skills/<name>/SKILL.md, where
<workspace_dir> is the workflow's workspace, passed to claude with
--add-dir. ClaudeSessionPool._spawn calls it before a cold spawn and
_prepare_warm_reuse calls it on every warm reuse with the previous
set, so only the difference is written or removed:
- Filesystem-origin skills:
shutil.copytree(skill.metadata.path, dest, dirs_exist_ok=True)— preservesSKILL.md+ supportingscripts/,references/,templates/, etc. - DB-origin user skills: synthesise the
SKILL.mdfromSkill.metadata(name,description,allowed-tools,metadata) +Skill.instructions(the body) usingyaml.safe_dumpfor the frontmatter.
The cwd is a git worktree under the workspace (<workspace>/<node>/wt_session
for bound runs, one per task otherwise), never the repo root, so
skills never land in the user's repository.
Per Live change detection above, claude picks the skills up
mid-session without a restart. The pool relies on that: a warm process
is reused across runs, and the warm-reuse diff adds or removes skill
folders under it. (Whether the Skill tool itself is pre-approved is
fixed at spawn; see
claude_code_interactive_mode.md → Known gaps.)
allowed-tools in OpenCompany-shipped SKILL.md files uses the same
syntax as upstream (Bash(git diff *) Read etc.) and is honoured by
claude verbatim — see server/skills/coding_agent/file-modify-skill/SKILL.md
for a reference.