Claude Code skills: SKILL.md, locations, frontmatter and install

Claude Code skills are folders with a SKILL.md file of instructions that Claude loads when a request matches the skill’s description, or that you run directly as /skill-name. Put personal skills in ~/.claude/skills/<name>/ and project skills in .claude/skills/<name>/.

Applies to: Claude Code 2.1.288 (changelog), docs as of October 3, 2026; the comparison with commands, subagents, MCP and hooks was added from the docs on October 10, 2026. Last checked: October 10, 2026.

On this page

What is a Claude Code skill?

Anthropic’s skills page describes a skill as a SKILL.md file that Claude adds to its toolkit. The docs suggest making one 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, a skill’s body loads only when it is used, so long reference material costs little until it is needed.

Custom commands have been merged into skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy, and existing command files keep working. Claude Code skills follow the Agent Skills open standard and add Claude Code-only features such as invocation control, subagent execution and dynamic context injection.

Claude Code also ships bundled skills, including /code-review, /batch, /debug, /loop and /claude-api. The disableBundledSkills setting turns them off (bundled skills).

How do I create a skill?

The docs’ first example summarizes uncommitted changes (create your first skill). Create the directory:

mkdir -p ~/.claude/skills/summarize-changes

Save this as ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

The YAML frontmatter tells Claude when to use the skill; the Markdown after it is what Claude follows. The directory name, or the frontmatter name when set, becomes the command. The !`git diff HEAD` line runs before Claude sees the skill and is replaced with its output. Start claude in a git project and either ask “What did I change?” or type /summarize-changes.

Where do skills load from?

Source: Choose where skills load. When names clash, enterprise beats personal and personal beats project; a skill beats a .claude/commands/ file of the same name; plugin skills never clash because they are namespaced. Claude Code watches skill directories and picks up added, edited or removed SKILL.md files without a restart. For a top-level skills directory created mid-session, run /reload-skills.

Cloud sessions and routines don’t read ~/.claude/skills/ on your machine. To use a personal skill there, enable it for your claude.ai account or commit it to the repository’s .claude/skills/ (Cowork and cloud sessions).

Which frontmatter fields matter most?

All fields are optional; description is the one Anthropic recommends, because Claude uses it to decide when to load the skill (frontmatter reference). Claude Code ignores unknown field names without reporting an error.

Only name, description, license, compatibility, metadata and allowed-tools are part of the Agent Skills spec. A claude.ai upload, the Skills API or package_skill.py from anthropics/skills fails with an Unexpected key(s) in SKILL.md frontmatter error if you include any other field.

Anthropic’s tip is to keep SKILL.md under 500 lines and move detailed reference material into supporting files in the same folder, linked from SKILL.md so Claude knows when to read them (supporting files).

Who invokes a skill: you or Claude?

The docs recommend disable-model-invocation: true for workflows with side effects, such as /commit or /deploy: “You don’t want Claude deciding to deploy because your code looks ready.” (control who invokes a skill).

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Once invoked, the rendered skill stays in the conversation across turns and is not re-read. After compaction Claude Code re-attaches the first 5,000 tokens of each recent skill within a shared 25,000-token budget, so put the most important instructions at the top (skill content lifecycle).

How do arguments work?

Text after the command fills placeholders: $ARGUMENTS is everything, $ARGUMENTS[0] or $0 the first argument, and names declared in arguments work as $name. Other substitutions include ${CLAUDE_SKILL_DIR}, ${CLAUDE_PROJECT_DIR} and ${CLAUDE_SESSION_ID} (string substitutions). With this skill, /migrate-component SearchBar JavaScript TypeScript fills all three positions:

---
name: migrate-component
description: Migrate a component from one language to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

If no placeholder receives your input, Claude Code appends ARGUMENTS: <value> to the skill content.

Skills vs commands, subagents, MCP and hooks

Anthropic’s extension overview separates the features that look alike:

The docs’ advice for each pair:

• Subagent: use one when a task reads many files or your context is filling up. The two combine: a subagent can preload skills with its skills: field, and a skill can run in a subagent with context: fork.
• MCP: the server handles the connection and authentication; a skill can carry your schema, query patterns or a /post-to-slack workflow for using it. See our Claude Code MCP guide.
• Hook: “Put guardrails in hooks.” A rule such as “never edit .env” in a skill is a request; a PreToolUse hook that blocks the edit is enforcement. Hooks cost no context unless they return output. See our Claude Code hooks guide.

Plugins are the packaging layer above all of these: one installable unit that can bundle skills, hooks, subagents and MCP servers.

How do I install skills other people publish?

Anthropic’s anthropics/skills repository works as a plugin marketplace. Its README gives these commands to run inside Claude Code:

/plugin marketplace add anthropics/skills

/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

After that, the README says you can name the skill in a request, for example “Use the PDF skill to extract the form fields from path/to/some-file.pdf”. Our Claude PDF skill guide covers that one. Plugin skills run as /plugin-name:skill-name and are removed with /plugin uninstall <plugin-name>@<marketplace-name>. The skills directory lists Anthropic’s skills and community collections with their install commands and licenses.

To share your own, commit .claude/skills/ to the repository, put a skills/ directory in a plugin, or deploy through managed settings (share skills).

Security: review skills before you run them

Warning

Anthropic’s docs note that workspace trust doesn’t gate allowed-tools: “Claude Code applies a project skill’s allowed-tools even in a -p run in a folder you’ve never trusted. A skill can grant itself broad tool access, so review the allowed-tools of skills checked into a repository before you run Claude Code there.” (pre-approve tools)

Safer controls the same page documents:

• Deny the Skill tool in /permissions to disable all skills, or allow and deny specific ones with rules such as Skill(commit) and Skill(deploy *) (restrict skill access).
• Turn off shell injection with "disableSkillShellExecution": true in settings; each !`command` is then replaced with [shell command execution disabled by policy] (inject dynamic context).
• Hide a skill without editing it through skillOverrides ("on", "name-only", "user-invocable-only" or "off"), which the /skills menu writes to .claude/settings.local.json (override visibility).
• Organizations can set allowManagedPermissionRulesOnly so allowed-tools in project and personal skills is ignored (v2.1.282 or later).

Injected commands never prompt while the skill renders: one matched by a deny rule, or outside auto mode one not allowed by a rule, aborts the invocation instead.

Troubleshooting

From Anthropic’s troubleshooting section:

• Skill not triggering: put words users actually say in the description, check it appears when you ask What skills are available?, or call it with /skill-name. Malformed YAML loads the body with empty metadata; run claude plugin validate .claude/skills (v2.1.233 or later) or start with --debug to see the parse error.
• Triggers too often: make the description more specific or add disable-model-invocation: true.
• Claude stops following it: move a rule that must always hold into a hook, which can live in the skill’s hooks frontmatter.
• Descriptions cut short: the listing budget is 1% of the context window. Raise it with skillListingBudgetFraction, set rarely used skills to "name-only", or run /skill-doctor (v2.1.252 or later) to find unused ones.