Extend Claude with skills — Claude Code Docs
by Anthropic
The full frontmatter reference for Claude Code skills — including the fields that only work in Claude Code, and the six that survive an upload to claude.ai.
Overview
This is the reference page for skills in Claude Code, and it goes considerably deeper than the conceptual overview because it documents the layer of Claude Code-specific behaviour built on top of the agentskills.io open standard. It opens with a usable decision rule for when to write one — you keep pasting the same checklist into chat, or a section of CLAUDE.md has grown from a fact into a procedure — and notes that unlike CLAUDE.md content, a skill's body only loads when used. It then walks through creating a first skill end to end, with a working example that inlines the output of git diff HEAD via dynamic context injection, so the instructions reach Claude with the real working tree already attached. A precedence table sets out the four storage locations (enterprise, personal under ~/.claude/skills/, project under .claude/skills/, and plugin skills namespaced as plugin:skill) and exactly how name collisions resolve between them, including nested monorepo skills that surface under directory-qualified names such as apps/web:deploy. The frontmatter reference is the section worth bookmarking: beyond name and description it documents when_to_use, allowed-tools and disallowed-tools, disable-model-invocation and user-invocable for controlling who may trigger a skill, context: fork for running one in a subagent, plus model, effort, hooks, paths and shell. A companion table marks which six fields are portable to claude.ai uploads and the Skills API and which are Claude Code extensions that hard-fail on upload. String substitutions, live change detection, and the bundled skills shipping with the CLI round it out.
At a Glance
- Topic
- Skills
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~30-40 min first read; ongoing reference
- Provider
- Anthropic
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Decide when a procedure belongs in a skill rather than in CLAUDE.md or a pasted prompt
- ✓Author a working skill with YAML frontmatter and test both automatic and slash-command invocation
- ✓Place skills correctly across enterprise, personal, project and plugin locations for the intended audience
- ✓Predict which skill wins when names collide across levels, plugins and nested directories
- ✓Configure every frontmatter field, including allowed-tools, disable-model-invocation and context: fork
- ✓Inject live command output into a skill body so instructions arrive already grounded in current state
- ✓Use string substitutions like $ARGUMENTS and CLAUDE_SKILL_DIR to write portable, script-bundling skills
- ✓Know which six frontmatter fields survive packaging for claude.ai and the Skills API
Highlights
- •The only complete frontmatter table anywhere — roughly twenty fields, each with its behaviour and version requirements
- •Explicitly separates the open Agent Skills standard from Claude Code's extensions, so you know what is portable before you ship it
- •Documents the collision and precedence rules in detail, which is where multi-level skill setups actually break
- •Dynamic context injection with backtick-bang commands is a genuinely distinctive capability and is documented with a runnable example
- •Actively maintained against CLI releases, with per-feature minimum versions called out inline rather than left implicit
Who It’s For
Best For
- ✓Claude Code users authoring their first project or personal skill
- ✓Teams standardising engineering workflows into shareable, committed project skills
- ✓Plugin authors packaging skills for distribution and needing the namespacing rules
- ✓Anyone migrating existing .claude/commands/ files to the skills format
Prerequisites
- •Claude Code installed, and comfort with YAML frontmatter and Markdown
- •Basic command-line familiarity, including creating directories under a dotfolder
- •Helpful but not required: having read Anthropic's Agent Skills overview first
FAQ
What is Extend Claude with skills — Claude Code Docs?
Anthropic's reference page for skills in Claude Code. It covers when to write a skill instead of adding to CLAUDE.md, a working first-skill walkthrough, the four storage locations and how name collisions resolve, the complete YAML frontmatter table, string substitutions, dynamic context injection, and which fields are portable outside Claude Code. This is the page you keep open while authoring.
Is Extend Claude with skills — Claude Code Docs free?
Extend Claude with skills — Claude Code Docs is free to access.
What level is Extend Claude with skills — Claude Code Docs for?
Extend Claude with skills — Claude Code Docs is aimed at a intermediate audience. Recommended background: Claude Code installed, and comfort with YAML frontmatter and Markdown, Basic command-line familiarity, including creating directories under a dotfolder, Helpful but not required: having read Anthropic's Agent Skills overview first.
How long does Extend Claude with skills — Claude Code Docs take?
Expect roughly ~30-40 min first read; ongoing reference. Most learners work through it at their own pace.
What will I learn from Extend Claude with skills — Claude Code Docs?
You'll learn: Decide when a procedure belongs in a skill rather than in CLAUDE.md or a pasted prompt; Author a working skill with YAML frontmatter and test both automatic and slash-command invocation; Place skills correctly across enterprise, personal, project and plugin locations for the intended audience; Predict which skill wins when names collide across levels, plugins and nested directories; Configure every frontmatter field, including allowed-tools, disable-model-invocation and context: fork; Inject live command output into a skill body so instructions arrive already grounded in current state; Use string substitutions like $ARGUMENTS and CLAUDE_SKILL_DIR to write portable, script-bundling skills; Know which six frontmatter fields survive packaging for claude.ai and the Skills API.
Topics
Sources
This page was written from 3 sources, 2 on domains other than code.claude.com.