Claude Code skills: SKILL.md format, where they load, your first skill

Claude Code skills are folders with a SKILL.md file of instructions that Claude loads only when a task needs them, or when you type /skill-name. This guide covers the SKILL.md format, where skills live, how Claude decides to load one, how skills differ from CLAUDE.md, subagents and hooks, and how to write and test your first skill.

What are Claude Code skills?

Claude Code skills are reusable instruction packages: a folder containing a SKILL.md file, plus optional scripts, templates and reference docs. Claude reads a skill when your request matches its description, or when you type /skill-name. The official skills docs suggest creating one when you keep pasting the same checklist or procedure into chat, or when part of your CLAUDE.md has grown from a fact into a procedure.

The key property is progressive disclosure. Claude doesn't load every skill up front. Anthropic's Agent Skills overview describes three levels:

So you can keep a 2,000-line API reference in a skill folder and pay for it only on the day Claude needs it.

Two more facts help you place skills in Claude Code:

• Custom commands are now skills. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy. Old command files keep working; new work should use the skill folder, which can hold supporting files.
• Claude Code ships bundled skills. Commands such as /code-review, /debug, /batch, /loop and /claude-api are prompt-based skills that come with Claude Code. Our list of Claude Code commands shows which built-ins are skills.

What goes in a SKILL.md file?

A SKILL.md file has YAML frontmatter between --- lines that tells Claude when to use the skill, followed by Markdown instructions that Claude follows when it runs. In Claude Code every frontmatter field is optional, but you should always write a description, because that is what Claude matches your request against.

---name: release-notesdescription: Drafts release notes from the commits since the last git tag. Use when the user asks for release notes, a changelog entry, or "what shipped".argument-hint: "[version]"allowed-tools: Bash(git log *)---## Recent commits (tags shown in parentheses)!`git log --oneline --decorate -50`## InstructionsWrite release notes for version $ARGUMENTS from the commits above thatare newer than the most recent tag.Group them under Added, Changed and Fixed. Skip merge commits anddependency bumps. Keep each line under 15 words and link the PR number.

The fields you will use most:

Inside the body you get a few substitutions. $ARGUMENTS is everything typed after the command, $0, $1 and so on are single arguments, and ${CLAUDE_SKILL_DIR} is the skill's own folder, which you use to call bundled scripts. A line starting with !`command` runs that shell command before Claude sees the skill and pastes in the output, which is how the example above hands Claude the real commit list instead of asking it to guess.

Where do Claude Code skills live?

Where you save a skill decides who gets it. Personal skills go in your home directory, project skills go in the repository so your team gets them through git.

When two skills share a name, enterprise beats personal and personal beats project. A skill also beats a .claude/commands/ file of the same name, and a project skill named like a bundled skill replaces it.

Claude Code loads project skills from the directory you start in and every parent up to the repository root, so starting in packages/web/ still picks up root skills. Skills in a nested .claude/skills/ below your starting point load the first time Claude touches a file in that folder. Edits to SKILL.md files are picked up during a running session; if you create a brand new top-level skills directory, run /reload-skills.

One gotcha for remote and scheduled work: cloud sessions don't read ~/.claude/skills/ on your laptop. If a skill must be available to a cloud session, commit it to the repository's .claude/skills/ or enable it on your claude.ai account.

When does Claude load a skill?

Claude sees a listing of every available skill's name and description on each turn, and loads the full body when your request matches a description or when you type the skill's name. The description is the trigger, so write it like a routing rule.

Two frontmatter fields change who can start a skill:

Use disable-model-invocation: true for anything with side effects: deploys, commits, sending messages. In the docs' words, you don't want Claude deciding to deploy because your code looks ready. Use user-invocable: false for background knowledge, such as how a legacy billing system works, that isn't a sensible command.

A few limits from the docs explain most "Claude ignored my skill" reports:

When the listing runs over budget, Claude Code drops descriptions of the skills you invoke least, which removes the words Claude matches against. Run /skill-doctor to see each skill's context cost and how often it is used, and /skills to browse and toggle them.

Write descriptions that trigger

Anthropic's authoring best practices ask for descriptions in the third person that state both what the skill does and when to use it. Put the main use case first, since long descriptions are cut from the end.

Weak:   Helps with releases.Strong: Drafts release notes from the commits since the last        git tag. Use when the user asks for release notes, a changelog        entry, or what shipped this week.

Skills vs CLAUDE.md vs subagents vs hooks: which should you use?

Use CLAUDE.md for short facts Claude needs in every session, skills for procedures and reference material needed only sometimes, subagents for work that should run in a separate context, and hooks for rules that must hold every time. The memory docs draw the same line: if a CLAUDE.md entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule.

Skills and subagents also combine. A skill with context: fork and agent: Explore hands its instructions to a read-only Explore subagent, which works in a clean context and returns a summary. In the other direction, a subagent's skills field preloads full skill content when that subagent starts. Our guide to Claude Code subagents covers that side, and CLAUDE.md best practices covers what to keep in the always-loaded file.

If Claude keeps skipping a step that must never be skipped, a skill is the wrong tool. Move the rule into a Claude Code hook, which runs whether or not Claude remembers it.

How do you write your first Claude Code skill?

Pick one procedure you have explained to Claude more than twice, write it as a skill in the project, and test it both ways: by asking naturally and by typing the command. This walkthrough builds a pre-commit review skill.

1. Create the folder. In the repository root, run mkdir -p .claude/skills/pre-commit-review.
2. Write the frontmatter. Give it a description that names the task and the phrases you use for it.
3. Pull in live context. Use !`git diff --cached` so Claude reviews the real staged changes.
4. Write the steps as standing instructions. Short, numbered, specific to your project.
5. Test it twice. Start claude, stage a change, then ask "is this ready to commit?" and see whether Claude picks the skill. Then run /pre-commit-review directly.
6. Check it loaded. Run /skills and look for it. If the frontmatter fails to parse, run claude --debug to see the error.
7. Commit the folder so your team gets the same skill.

---description: Reviews staged changes before a commit and lists blocking problems. Use when the user asks if changes are ready to commit, wants a quick review, or says "check before I commit".allowed-tools: Bash(git diff *) Bash(npm run lint *) Bash(npm test *)---## Staged changes!`git diff --cached`## Review steps1. If the diff above is empty, say nothing is staged and stop.2. Run `npm run lint` and `npm test` and report failures first.3. Flag debug logging, commented-out code, hardcoded secrets or URLs,   and new functions without tests.4. Reply with "Blocking" and "Nice to have" lists, each item naming   the file and line. Do not edit files.

Once the skill works on a few realistic prompts, compare a fresh session with and without it. The docs recommend this baseline check, and Anthropic's skill-creator plugin automates it with test cases and a with/without benchmark (/plugin install skill-creator@claude-plugins-official).

Do Claude Code skills work in Codex and other tools?

Yes, within limits. Claude Code skills follow the open Agent Skills specification, and OpenAI's Codex skills docs say Codex builds on the same standard. A skill that sticks to the standard's fields moves between tools; Claude Code extensions do not.

For portable skills, follow the spec's stricter rules: name and description are both required, the name uses lowercase letters, numbers and hyphens, is at most 64 characters, and must match the folder name; the description is at most 1,024 characters. Codex reads repository skills from .agents/skills folders and personal skills from ~/.agents/skills, and you invoke one there with $skill-name or /skills, so a shared skill needs to be copied or symlinked into both trees. Our Codex CLI guide covers the rest of that setup.

Uploading to claude.ai or the Skills API is stricter still: any frontmatter key outside the six spec fields fails with an "Unexpected key(s)" error, and ! command injection doesn't run there.

Are Claude Code skills safe?

A skill is code you run with your own permissions, so treat one from the internet like a package from an unknown author. Anthropic's overview warns that a malicious skill can direct Claude to call tools or run code in ways that don't match its stated purpose, including leaking data.

Three Claude Code behaviors make this concrete:

• allowed-tools skips prompts. The docs note that a project skill's allowed-tools applies even in a claude -p run in a folder you never trusted. Review it in every cloned repository.
• ! lines run before Claude reads anything. Set "disableSkillShellExecution": true in settings to turn them off for user, project and plugin skills.
• You can switch skills off without editing them. skillOverrides in settings sets any skill to "on", "name-only", "user-invocable-only" or "off", and a Skill(deploy *) deny rule in permissions blocks Claude from invoking one.

Skills pay off most when nobody is watching the session. If you run agents unattended on a server, the project's .claude/skills/ folder travels with the repository, so the same release, review and test procedures apply there as on your laptop. Orkio runs Claude Code on an always-on, isolated cloud box that clones your repositories, so committed skills come along; for scripted runs, see Claude Code headless mode.

Why isn't my Claude Code skill working?

Most skill problems come from the description, the frontmatter or context compaction. Work through these checks in order.

• Claude never picks the skill. Ask "What skills are available?" to confirm it is listed, then add the words you actually type to the description. If you have many skills, its description may have been dropped from the listing; check /skill-doctor.
• /name isn't recognized. The frontmatter must start on the first line of the file. Malformed YAML loads the body with no fields, so /name may work while automatic matching fails. Run claude --debug to see the parse error.
• Claude uses it too often. Narrow the description, or add disable-model-invocation: true.
• Claude follows it at first, then drifts. Claude Code adds the skill once and doesn't re-read the file. After compaction it keeps only the first 5,000 tokens of each recent skill, within a 25,000-token total, so put the important rules at the top and invoke the skill again after a long session.
• A ! command breaks the skill. A failing command aborts the whole invocation. Append || true to commands that exit non-zero on purpose.
• A context: fork skill returns nothing. Forked skills need an actual task. A skill that only lists conventions gives the subagent nothing to do.

How to start with skills today

Start small and let real repetition tell you what to write next:

1. Run /skills to see what is already installed, including bundled skills.
2. Find the longest procedure in your CLAUDE.md and move it into .claude/skills/<name>/SKILL.md with a clear description.
3. Write one user-invoked skill with disable-model-invocation: true for a task with side effects, such as releases.
4. Test each skill in a fresh session, by natural request and by /name.
5. Commit .claude/skills/ and review it in pull requests like any other code.
6. Once a month, run /skill-doctor and turn off what nobody uses.

Frequently asked questions