Claude Code skill.md Guide: YAML Frontmatter, allowed-tools & Real Examples (2026)

A Claude Code skill is a directory containing a `SKILL.md` file with YAML frontmatter and markdown instructions. Claude loads skills automatically when their description matches what you are asking for, or you can invoke them by name with /skill-name. The description helps Claude decide when the skill applies. Start by describing the task it should handle, then write the procedure. Test both a matching request and a request where the skill should stay out of the way.

Last updated: May 2026 · Covers Claude Code v2 skills + plugin system · Verified against official Anthropic docs

• A skill is a directory with a SKILL.md file. Frontmatter on top, markdown instructions below
• Skill descriptions participate in discovery; the full instructions are loaded when used. Keep specialised procedures in skills rather than repeating them in CLAUDE.md.
• The description field is the trigger — write it as "Use when…" and lead with verbs users naturally type
• Project skills go in .claude/skills/, personal skills in ~/.claude/skills/, plugin skills are namespaced and shared via the marketplace
• For dangerous skills (deploy, send email, commit), set disable-model-invocation: true so Claude cannot fire them autonomously

What is a Claude Code skill?

Two types of skill, one shared format.

Anthropic's official guidance distinguishes two kinds of skill:

Capability uplift — teaches Claude an ability it does not have natively. Examples: running your specific deploy script with the right environment variables, generating an interactive HTML visualisation of test coverage data, fetching live data from your internal API.

Encoded preference — Claude already knows the underlying task, but the skill captures your team's specific way of doing it. Examples: your commit-message format, your NDA review checklist, your incident-response process, your brand-voice rules for marketing copy.

Both types share the same structure. Both live in a directory. Both are described by a SKILL.md file with YAML frontmatter on top and instructions below. The only meaningful difference is whether the skill teaches Claude something new or codifies how you want something done.

The official heuristic from Anthropic: "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."

If you find yourself starting sessions with "remember, when you write commits in this repo…" — that is a skill waiting to be written.

Skill anatomy — the file you actually write

Illustrative skill example:

yaml---
description: Summarises 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

Summarise the changes above in two or three bullet points, then list any risks…

This example has two body sections and one frontmatter field. Claude can discover it from a matching request. Where shell execution is enabled for that skill source, Claude Code runs the command before the skill reaches the model. Test discovery and execution separately.

The directory structure can be more elaborate when needed:

textmy-skill/
├── SKILL.md           # Required — the entry point
├── template.md        # Optional — a template Claude fills in
├── examples/
│   └── sample.md      # Optional — expected output format
└── scripts/
    └── validate.sh    # Optional — executable Claude can run

Use the documented filename SKILL.md exactly, so the skill works across operating systems. The directory name supplies the slash command unless a supported name override applies (my-skill/ → /my-skill).

Frontmatter fields that matter

The full reference is long; these are the ones you will actually use:

Dynamic context injection — the underexplained feature

Command-injection syntax runs a shell command and replaces the placeholder with its output before Claude sees the prompt. This is preprocessing — Claude is not running the command — and it is the cleanest way to inject live data into a skill.

yaml---
description: Reviews open PRs for staleness. Use when the user asks about open PRs, wants a triage, or mentions PR backlog.
---

## Open pull requests

!`gh pr list --state open --json number,title,createdAt,labels --limit 50`

## Instructions

Review the PRs above. Group by staleness (under 7 days, 7-30 days, 30+ days)…

When this injection runs successfully, Claude receives the actual gh pr list output. The command still needs authentication, permission and failure handling; measure its cost and reliability rather than assuming it improves both.

For a multi-line shell command, open a fenced code block with three backticks followed by an exclamation mark. See the official dynamic-context examples for the exact syntax and restrictions on synced skills. Variables include ${CLAUDE_SESSION_ID}, ${CLAUDE_SKILL_DIR}, ${CLAUDE_EFFORT}, $ARGUMENTS and $ARGUMENTS[0].

How to write your first Claude Code skill

Eight steps from "I keep typing the same thing" to "the skill is doing the work."

1. Identify the trigger pattern

You have a skill waiting to be written when:

• You start sessions with the same context-setting block
• You paste the same checklist into multiple conversations
• A section of your CLAUDE.md has grown from a fact ("we use Convex") into a procedure ("when adding a new mutation, do X then Y then Z")
• You explain the same workflow to new team members repeatedly

2. Pick the directory location

The directory name becomes the slash command. Lowercase with hyphens (open-pr-triage, not OpenPRTriage).

3. Write the description first

This is the most important sentence in the entire skill. Lead with verbs users naturally type. Use "Use when…" framing. Include negative examples if needed.

Bad: "A skill for git diffs." Better: "Summarises uncommitted changes." Best: "Summarises uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff. Do not use for committing — use /commit instead."

4. Write the body concisely

Use imperative instructions ("Run X. Then Y."), not documentation prose. Anthropic's official guidance: keep `SKILL.md` under 500 lines. Every line is a recurring token cost once loaded.

A common mistake is writing the skill like a tutorial. The skill is for Claude, not for a human reader. Claude does not need preamble, motivation, or context-setting. Skip to the procedure.

5. Decide invocation control

For skills with side effects, set disable-model-invocation: true so Claude cannot trigger them autonomously:

yaml---
description: Deploys the production application. Use only when the user explicitly asks to deploy.
disable-model-invocation: true
---

For background-knowledge skills the user should not invoke directly, set user-invocable: false. The skill stays available to Claude but does not appear in the / menu.

6. Add dynamic context if needed

For inline injection, put an exclamation mark immediately before a command enclosed in backticks. These are example commands to place inside that syntax:

• git diff HEAD — current uncommitted changes
• gh pr list --state open — open PRs
• cat package.json | jq .scripts — available npm scripts
• npm test 2>&1 | tail -50 — recent test output

7. Test two ways

Current Claude Code watches skill files; plugin changes may need /reload-plugins. Check the installed version and source location if changes do not appear. Then:

• Ask Claude something matching the description. Check whether the skill is discovered. If not, inspect its location, invocation settings and description before changing the wording.
• Type `/my-skill` directly. Confirm it runs. Check /skills to confirm it appears in the listing.

8. Pre-approve tools if appropriate

If your skill always uses certain tools, pre-approve them via allowed-tools to avoid the per-use approval dialog:

yaml---
description: Runs the test suite and summarises failures.
allowed-tools:
  - Bash(npm test*)
  - Bash(npx vitest*)
---

This makes the skill flow without interruption while keeping unrelated tool use under approval.

Skill vs CLAUDE.md — the line you should hold

`CLAUDE.md` is for always-on facts. Skills are for triggered procedures.

Most teams put too much in CLAUDE.md. The reason matters: CLAUDE.md loads on every session. A 200-line deployment checklist in CLAUDE.md costs tokens on every turn, even when you are asking Claude to rename a variable. Skills load only when their description matches your prompt — their descriptions can consume context before the full instructions are invoked.

The right split:

When a section of CLAUDE.md grows from a fact into a procedure, move it to a skill. Your CLAUDE.md should stay thin. Your skills folder can grow to dozens.

Sharing skills across a team

Four sharing routes, with different scope and precedence. For same-name skills, current Claude Code gives enterprise precedence over personal, then project skills. Plugin skills use namespaces. Check the official reference when names overlap.

1. Project skills (.claude/skills/ committed to git)

The primary team-sharing pattern. Commit your .claude/skills/ directory to version control. Every developer cloning the repo gets the skills automatically. New skills appear with the next pull.

Security note: project skills can grant broad tool access via allowed-tools. Review the skills before trusting a repo. Claude Code prompts for workspace trust the first time you open a repo with skills — accept only if you trust the source.

2. Personal skills (~/.claude/skills/)

Your skills, your machine, all projects. Useful for cross-project workflows you have developed personally — commit message conventions you use everywhere, code-review patterns, debugging approaches.

3. Plugin-distributed skills

The right answer for sharing across multiple projects, multiple repos, or with the wider community.

Plugin structure:

textmy-plugin/
├── .claude-plugin/
│   └── plugin.json     # Manifest: name, description, version, author
└── skills/
    └── my-skill/
        └── SKILL.md

Plugin skills are always namespaced (my-plugin:my-skill), so they never conflict with skills from other plugins.

Plugins distribute via marketplaces — host in a private git repo for internal team plugins, or submit to Anthropic's official marketplace at claude.ai/settings/plugins/submit for public distribution.

For UK SMEs running multi-team or multi-client work, the plugin pattern is what makes skills sustainable. A versioned private plugin can distribute reviewed changes across approved repositories. Teams still need to test the update and know which version they are using.

4. Enterprise managed deployment

For organisations that need centralised governance — compliance teams enforcing review checklists, security teams enforcing scan procedures — Claude Code supports enterprise managed settings that deploy skills organisation-wide. Enterprise-level skills cannot be overridden by users.

This is rarely needed for SMEs but matters for regulated UK industries (financial services, healthcare, legal) where standardisation is a compliance requirement.

Monorepo discovery — the detail that saves real time

Claude Code automatically discovers skills from `.claude/skills/` in the starting directory and every parent up to the repo root. When editing files in a subdirectory, it also looks in nested .claude/skills/ (e.g. packages/frontend/.claude/skills/).

For a monorepo, this means:

• apps/marketing-site/.claude/skills/ — skills only relevant to the marketing site
• packages/ui/.claude/skills/ — skills only relevant when working in the shared UI package
• .claude/skills/ (repo root) — skills available everywhere

No configuration. No setup. Just put skills in the right folder and the right ones load when working in the right place.

The seven anti-patterns (and how to avoid each)

Bad skills are easy to write. Diagnostic patterns to look out for.

1. Vague description that never triggers

"A skill for code reviews" gives Claude nothing to match against. Rewrite as a trigger sentence: "Use when reviewing pull requests, checking code quality, or the user asks for feedback on their implementation."

2. The mega-skill trap

Bundling commits, PR creation, branch naming, and changelog generation into one SKILL.md. Mega-skills load late, fire less reliably, and confuse Claude when sections conflict. One responsibility per skill.

3. Long procedures in CLAUDE.md instead of skills

A 200-line deployment checklist in CLAUDE.md costs tokens on every turn. Move it to a skill. CLAUDE.md stays thin.

4. Over-scripting

Shipping complex shell or Python scripts when plain imperative markdown instructions would work. Keep judgement steps in clear instructions. Use small tested scripts where fixed calculations, validation or repeatable data handling need deterministic behaviour.

5. Wrong folder for the intended scope

Putting a personal cross-project skill in .claude/skills/ (project only) or committing a project-specific skill to ~/.claude/skills/ (global). Silent failures with no error message.

6. Ignoring invocation control for dangerous skills

A /deploy skill without disable-model-invocation: true means Claude can decide to deploy because the code "looks ready." Catastrophic. High-stakes actions must be user-only.

7. Exceeding token budget silently

Skill descriptions have a context budget. When a large library exceeds it, some skills can be harder to discover. Inspect the installed version's diagnostics and the current skill visibility guidance before changing budget or visibility settings.

A maintainable team skill library

Separate reusable team conventions, technology-specific procedures and project-specific instructions. Keep the owner, version and review date clear. A skill with a side effect needs an explicit permission boundary; a Markdown instruction alone is not an access control.

Start with one repeated workflow and test both when the skill should run and when it should stay out of the way.

Frequently asked questions

What is a Claude Code skill and how is it different from a custom command?

A skill is a directory containing a SKILL.md file with YAML frontmatter and markdown instructions. It can include supporting files (templates, examples, scripts). Custom commands (.claude/commands/foo.md) were the older format and are now considered a subset of skills. Skills win when both define the same name. New work should use skills.

Where do I put skills in Claude Code?

Personal skills (across all your projects): ~/.claude/skills/my-skill/. Project skills (this repo only): .claude/skills/my-skill/. Plugin skills (distributed across teams): inside a plugin directory at my-plugin/skills/my-skill/.

How does Claude know when to use a skill automatically?

By matching your prompt against each skill's description field. The description is a fuzzy-match trigger, not documentation — write it as a "Use when…" sentence with the verbs users naturally type. Combined description and when_to_use are truncated at 1,536 characters in the skill listing.

Can I share Claude Code skills with my team?

Yes. The simplest pattern is to commit .claude/skills/ to your repo — every developer who clones gets the skills. For sharing across multiple projects or with the wider community, package as a plugin and distribute via a marketplace.

What goes in the SKILL.md frontmatter?

At minimum: description (the auto-trigger sentence). Optionally: when_to_use, disable-model-invocation, user-invocable, allowed-tools, paths, model, effort, context: fork. The full reference is in the official Anthropic docs.

What is the difference between skills and CLAUDE.md?

CLAUDE.md is for always-on facts that load every session (architecture decisions, tech stack, code style). Skills are for triggered procedures that load only when their description matches your prompt. Long procedures in CLAUDE.md bloat the main context and waste tokens.

How do I stop Claude from triggering a skill automatically?

Add disable-model-invocation: true to the frontmatter. The skill becomes user-only — you can still invoke it with /skill-name, but Claude cannot trigger it autonomously. Mandatory for any skill with side effects (deploy, send, commit, write to production).

How many skills should I have active at once?

There is no universal ideal count. Keep descriptions specific, remove duplicates and check the current documentation for description-budget behaviour.

Can Claude Code skills run scripts and shell commands?

Yes. Where the skill source and policy permit shell injection, Claude Code can run a command before passing its output to the model. Skills can also reference helper scripts through ${CLAUDE_SKILL_DIR}/scripts/foo.sh. Neither route bypasses the applicable tool permissions.

Related reading

• Claude Code Skills Benchmark 2026 (v1): What 5 Production Skills Tell Us
• ↑ What is Claude Code? A UK Business Guide — the foundational pillar
• ↔ How to Install Claude Code — UK Business Guide — the install guide where the skills folder gets created
• ↔ Claude Code MCP Servers — 7 Worth Installing — the other big extensibility lever beyond skills
• ↔ Claude Code Pricing 2026 — including the agent-team and MCP token-cost traps that interact with skills
• ↔ Hermes Agent Skills — Build Custom Extensions — the parallel concept on the Hermes side, for operational-automation skills

What should you do next?

Skills become valuable around the moment your team writes the second one — when you stop thinking of skills as a curiosity and start thinking of them as the team's institutional memory. The first three skills are the hardest because you do not yet have the patterns. We can help with that.

Bring a repeated workflow and the rules it needs to follow. We can discuss the appropriate next step.