Claude Code skills: the SKILL.md reference guide

Claude Code skills explained: where they live, SKILL.md frontmatter, invocation control, supporting files, and how to debug a skill that does not trigger.

10 October 2026 · Updated 10 October 2026

Claude Code skills package instructions, reference material and scripts so Claude can use them when a task calls for them. This guide covers what a skill is, where it lives, which SKILL.md frontmatter fields matter, and how to control and debug it. It is based on the Claude Code skills documentation and Anthropic’s post Equipping agents for the real world with Agent Skills. Docs checked on 2026-10-10; version-specific behavior is noted where the docs state it, so confirm against the current page.

What Claude Code skills are

The documentation puts it simply: “Create a SKILL.md file with instructions, and Claude adds it to its toolkit.” Claude uses a skill when it is relevant, and you can run one directly by typing /skill-name (docs).

Skills follow the Agent Skills open standard. Claude Code adds its own extensions, such as invocation control, running a skill in a subagent, and injecting shell command output into the skill before Claude reads it (dynamic context injection).

Anthropic describes skills as built on progressive disclosure, in three levels (engineering post):

1. Metadata. Name and description give Claude “just enough information” to know when to use the skill.
2. The SKILL.md body. Read in full only when the skill looks relevant.
3. Linked files. Opened only when needed.

Skills vs CLAUDE.md, hooks and slash commands

• CLAUDE.md is for facts and conventions that apply in every session. The skills docs say a skill’s body, unlike CLAUDE.md content, loads only when used (docs).
• Skills are for procedures and reference material that matter for specific tasks.
• Hooks run your command every time an event fires. The skills docs recommend moving a rule that must hold every time into a hook, because Claude may not follow skill text on later turns. See our Claude Code hooks examples.
• Slash 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 (docs). Prefer a skill for new work, since only skills support supporting files.

Claude Code also ships bundled skills such as /doctor, /code-review, /batch, /debug, /loop and /claude-api (bundled skills). They are prompt-based and are listed in the commands reference. A skill of yours with the same name replaces the bundled one; to turn them all off, the docs name the disableBundledSkills setting.

Where skills live and who gets them

The location decides who gets the skill (docs):

Two details that surprise people, both from the same page:

• If two of enterprise, personal and project share a name, enterprise wins over personal, and personal wins over project.
• Cloud sessions and routines do not read ~/.claude/skills/ on your machine. To use a skill there, commit it to the repository’s .claude/skills/ or package it as a plugin.

Anatomy of SKILL.md and frontmatter fields

A SKILL.md has YAML frontmatter between --- markers, then Markdown instructions. Claude Code reads the frontmatter only when the opening --- is the first line of the file (frontmatter reference). All fields are optional, and only description is recommended. A field name must match exactly: Claude Code ignores an unrecognized field without reporting an error.

The docs list more fields (argument-hint, arguments, model, agent, background and others); this table covers the ones you reach for first. The combined description and when_to_use text is truncated at 1,536 characters in the skill listing, so put the key use case first.

Portability: for claude.ai skill uploads and the Skills API, the docs say only name, description, license, compatibility, metadata and allowed-tools are accepted, and other keys such as argument-hint produce an error (docs).

Write your first skill

This follows the docs’ own first-skill example, which summarizes uncommitted changes. Create the folder:

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 !`git diff HEAD` line is dynamic context injection: Claude Code runs the command and replaces the line with its output before Claude sees the skill, so the instructions arrive with the live diff. The description names both what the skill does and when to use it, and the instructions say what to do when there is nothing to report.

Test it two ways, as the docs describe: ask “What did I change?” and let Claude invoke it, or type /summarize-changes.

Control when a skill runs

By default both you and Claude can invoke a skill. Two frontmatter fields restrict that (docs):

Use disable-model-invocation: true for workflows with side effects, such as /deploy or /commit, where you do not want Claude deciding the timing. Use user-invocable: false for background knowledge that is not meaningful as a command.

allowed-tools pre-approves tools only for the turn that invokes the skill; the grant clears when you send your next message, and it does not restrict which tools are available (docs). The docs also warn that Claude Code applies a project skill’s allowed-tools even in a -p run in a folder you have never trusted, so review that field in skills checked into a repository before running Claude Code there.

A related behavior: once invoked, the rendered SKILL.md stays in the conversation, and Claude Code does not re-read the file on later turns (skill content lifecycle). Write guidance as standing instructions, for example “run the tests after every edit” instead of “run the tests”.

Add supporting files and keep SKILL.md short

The docs recommend keeping SKILL.md under 500 lines and moving detail into files it references (docs):

my-skill/
├── SKILL.md        (overview and navigation)
├── reference.md    (loaded when needed)
├── examples.md     (loaded when needed)
└── scripts/
    └── helper.py   (executed, not loaded)

Mention each file from SKILL.md so Claude knows what it contains and when to open it. Anthropic’s post adds that skills can bundle code “for Claude to execute as tools at its discretion”, which suits steps that must be deterministic. In a skill body, ${CLAUDE_SKILL_DIR} expands to the skill’s directory, so a bundled script can be referenced regardless of the working directory (string substitutions).

Test and debug a skill that does not trigger

Claude Code watches skill directories, so adding or editing a skill takes effect in the current session without a restart (live change detection). If a skill does not behave, the troubleshooting section suggests, in order:

1. Check the description includes keywords users would naturally say.
2. Verify the skill appears when you ask “What skills are available?”
3. Rephrase your request to match the description more closely.
4. Invoke it directly with /skill-name if it is user-invocable.

If the YAML is malformed, the skill loads with empty metadata: /skill-name still works, but Claude cannot match your description. Run with --debug to see the parse error, or run claude plugin validate .claude/skills (requires v2.1.233 or later per the docs).

Other cases from the same page:

• Triggers too often: make the description more specific, or add disable-model-invocation: true.
• Stops following the skill: after compaction, invoke it again, and put the most important instructions near the top.
• Descriptions cut short: with many skills, Claude Code drops descriptions to fit a listing budget. /doctor estimates the listing’s cost.

Share skills safely

Project skills are shared by committing .claude/skills/ to version control. Plugins carry a skills/ directory, and managed settings deploy skills organization-wide (docs). On the receiving side, Anthropic’s advice is to install skills only from trusted sources and to audit bundled files, dependencies and any instructions that reach external networks before use (engineering post).

What to change in your setup

Recommendations below are our own reading of the docs, not official guidance.

1. Move any CLAUDE.md section that reads like a procedure into a skill (see “Skills vs CLAUDE.md”).
2. Rewrite each description to say what the skill does and when to use it, key use case first.
3. Add disable-model-invocation: true to every skill with side effects, such as deploys or commits.
4. Commit team skills to .claude/skills/; put personal ones in ~/.claude/skills/, and remember cloud sessions do not read the latter.
5. Review allowed-tools in any repository skill before running Claude Code there.
6. Keep SKILL.md short and push detail into supporting files.
7. Move rules that must hold every time into a hook.
8. When a skill misbehaves, test with /skill-name, then --debug.