How to Create Claude Code Skills: A SKILL.md Guide with a Worked Example

A skill is a folder of instructions, and optionally scripts and reference files, that a coding agent loads when a task calls for it. Claude Code supports skills, and its skills follow the Agent Skills open format, so a well-formed skill can also be used by other tools that adopt the format.

This guide builds a code-review skill step by step, starting from a real SKILL.md in HyperPrompt's own skill catalog and improving it. The steps follow the behavior documented by Claude Code and the Agent Skills specification as of 2026-11-05; they are not results from an installation test we ran. Check the linked docs if your version behaves differently.

What a skill is

The Agent Skills specification (checked 2026-11-05) defines a skill as "a directory containing, at minimum, a SKILL.md file." That file holds YAML frontmatter followed by Markdown instructions. Optional folders such as scripts/, references/ and assets/ hold executable code, longer documentation and templates.

Skills are designed for progressive disclosure. According to the specification, an agent loads only each skill's name and description at startup, loads the full SKILL.md body when it activates the skill, and reads files in scripts/, references/ or assets/ only when they are needed. That is why the description matters so much: it is the only part the agent sees when deciding whether a skill applies.

Claude Code's documentation states that its skills "follow the Agent Skills open standard, which works across multiple AI tools," and that Claude Code extends it with features such as invocation control and subagent execution (Claude Code skills docs, checked 2026-11-05).

Skills vs MCP servers

Skills and MCP servers are often mentioned together, but they solve different problems.

The Model Context Protocol architecture (checked 2026-11-05) describes a client-server protocol: an MCP host such as Claude Code creates one MCP client per MCP server, and each server is "a program that provides context to MCP clients." Servers expose tools ("executable functions that AI applications can invoke"), resources (data sources) and prompts (reusable templates) over JSON-RPC, using stdio for local servers or Streamable HTTP for remote ones.

A skill is not a running program and does not speak a protocol. It is files on disk that become instructions in the agent's context, plus scripts the agent can run with the tools it already has.

	Agent Skill	MCP server
What it is	A folder with SKILL.md and optional files	A program that implements the MCP protocol
What it adds	Know-how: procedures, checklists, conventions, helper scripts	Capabilities: tools, resources and prompts from an external system
How it runs	Loaded into the agent's context; scripts run through the agent's own tools	A separate process or remote service the host connects to
Typical example	"How we review code in this repo"	"Query our Postgres database" or "create a GitHub issue"
Setup	Copy a folder into a skills directory	Configure the host to start or connect to the server

They work well together: an MCP server can give the agent access to your issue tracker, and a skill can tell it how your team writes and triages issues. Browse MCP servers in the MCP directory, and see What are MCP skills? for more background on MCP.

Step 1: Choose where the skill lives

Claude Code looks for skills in several places. From the Claude Code skills docs (checked 2026-11-05):

Scope	Path	Applies to
Personal	~/.claude/skills/<skill-name>/SKILL.md	All your projects on this machine
Project	.claude/skills/<skill-name>/SKILL.md	Sessions in this repository; commit it to share with your team
Nested	<subdir>/.claude/skills/<skill-name>/SKILL.md	Sessions started in or below that subdirectory
Plugin	<plugin>/skills/<skill-name>/SKILL.md	Wherever the plugin is installed, invoked as /plugin-name:skill-name
Enterprise	.claude/skills/ in the managed settings directory	Users on machines where your organization deploys it

When names collide, the docs say enterprise wins over personal, and personal over project. A skill also takes precedence over a legacy .claude/commands/ file with the same name. Custom commands have been merged into skills; existing command files keep working, but the docs recommend skills for new work.

For a code-review skill your team should share, use the project location: .claude/skills/code-review/. Before settling on a name, ask Claude Code which skills are already available; if a personal, plugin or bundled skill already uses the same name, pick a distinct one (for example team-code-review, with the directory renamed to match) so you know which skill runs.

Step 2: Lay out the directory

.claude/skills/code-review/
├── SKILL.md              # required: frontmatter + instructions
├── references/
│   └── checklist.md      # detailed checklist, read when needed
└── scripts/
    └── collect-diff.sh   # helper that prints the diff to review

The specification recommends keeping SKILL.md under 500 lines and moving detailed material into referenced files, kept "one level deep" from SKILL.md.

Step 3: Write the frontmatter

The Agent Skills specification requires two fields:

• name: 1 to 64 characters; lowercase letters, numbers and hyphens only; must not start or end with a hyphen or contain consecutive hyphens; must match the parent directory name.
• description: 1 to 1,024 characters; should describe both what the skill does and when to use it, with keywords that help the agent recognize relevant tasks.

Optional fields in the specification are license, compatibility, metadata (a map of string keys to string values for anything else) and allowed-tools (experimental).

Claude Code is more lenient than the specification. Its docs say name defaults to the directory name, only description is recommended, and unrecognized fields are ignored silently. They also note that outside Claude Code only the specification's fields are accepted, and other fields can cause a hard error. If you want a skill that travels between tools, stick to the specification's fields and put everything else under metadata.

Two Claude Code details are worth knowing: 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; and the frontmatter must start on the first line of the file.

Worked example: improving a real SKILL.md

HyperPrompt's skill catalog includes this catalog/skills/code-review/SKILL.md (frontmatter shown):

---
name: code-review
description: 'Automated code review with focus on best practices, security, and performance.'
version: 2.0.0
category: development
tags:
  - code-review
  - security
  - performance
  - best-practices
---

Its body lists what to check (code quality, security, performance) and an output format (severity, location, description, suggested fix). Measured against the specification, three things can be improved:

1. The description says what, not when. Nothing tells the agent which requests should trigger it.
2. version, category and tags are not specification fields. Claude Code ignores them; other tools may reject them. They belong under metadata as strings.
3. There is no procedure or failure handling. The body lists topics but not how to find the code to review or what to do when that fails.

Illustrative revision — written for this guide, not taken from a tested installation:

---
name: code-review
description: Reviews code changes for correctness, security and performance problems and reports findings by severity with a suggested fix. Use when the user asks for a code review, a PR review, or to check a diff or file before merging.
metadata:
  version: "2.1.0"
  category: "development"
  tags: "code-review,security,performance,best-practices"
---

# Code review

## Procedure
1. Decide the scope. If the user named files, review those files. Otherwise run
   `bash scripts/collect-diff.sh` from this skill's directory to print the diff
   against the default branch (pass a different base branch as the first argument).
2. If the script exits with an error, show the user its message and ask what to
   review. Do not guess at the scope.
3. Read references/checklist.md and apply each section to the code in scope.
4. Report findings using the output format below, most severe first.
   If you find nothing, say so and list what you checked.

## Output format
For each finding: severity (Critical / Warning / Info), file and line,
what is wrong, and a suggested fix.

Step 4: Add supporting files and scripts

references/checklist.md holds the long checklist (readability, naming, input validation, injection risks, algorithmic cost, database queries) so SKILL.md stays short. The agent reads it only when the skill runs.

scripts/collect-diff.sh is an illustrative helper. The specification asks that scripts "include helpful error messages" and "handle edge cases gracefully," so it exits with a clear message instead of printing nothing:

#!/usr/bin/env bash
set -euo pipefail
if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  echo "collect-diff: not inside a git repository" >&2
  exit 2
fi
base="${1:-main}"
if ! git rev-parse --verify --quiet "$base" >/dev/null; then
  echo "collect-diff: base branch '$base' not found; pass it as the first argument" >&2
  exit 3
fi
diff="$(git diff "$base"...HEAD)"
if [ -z "$diff" ]; then
  echo "collect-diff: no changes between $base and HEAD" >&2
  exit 4
fi
printf '%s\n' "$diff"

Path handling differs by tool. The specification says to reference files with relative paths from the skill root. Claude Code also provides a ${CLAUDE_SKILL_DIR} variable so a script path resolves "regardless of the current working directory," for example bash ${CLAUDE_SKILL_DIR}/scripts/collect-diff.sh. Use the variable if the skill is Claude Code only; use relative paths if you want portability.

Claude Code also supports allowed-tools to pre-approve specific commands while a skill is active. The specification marks this field experimental and notes support varies between agents.

Step 5: Invoke the skill

According to the Claude Code docs, there are two ways a skill runs:

• Automatically. Claude uses a skill when your request matches its description. This is why the revised description names "code review," "PR review" and "check a diff."
• Directly. Type /code-review at the start of a message. If the name appears after other text, the docs say nothing runs directly.

Two frontmatter switches control this in Claude Code: disable-model-invocation: true stops Claude from loading the skill automatically (useful for anything with side effects, such as deploys), and user-invocable: false hides it from manual invocation so only Claude can use it.

Once invoked, the skill's content stays in the conversation; Claude Code does not re-read the file on later turns. After the conversation is compacted, the docs say only the start of an invoked skill may be kept, so put the most important instructions near the top.

Step 6: Check that it loads and triggers

These checks come from the Claude Code troubleshooting docs:

1. Ask Claude "What skills are available?" and confirm code-review is listed.
2. Run /code-review directly. If the frontmatter YAML is malformed, the docs say the skill still loads with empty metadata, so the slash command works but automatic matching does not. Start Claude Code with --debug to see the parse error.
3. Validate frontmatter with claude plugin validate .claude/skills (the docs list Claude Code v2.1.233 or later), or with the specification's reference validator: skills-ref validate ./code-review.
4. Compare behavior in a fresh session with the skill enabled and again with it turned off, using the same request.

Failure handling

Plan for two kinds of failure.

The skill does not behave as a skill should:

• Not triggering: add the words users actually say to the description, rephrase the request, or invoke it directly. If many skills are installed, Claude Code may drop some descriptions from the listing to fit its budget; /skill-doctor and /doctor report what the listing costs.
• Triggering too often: make the description more specific, or set disable-model-invocation: true.
• Claude stops following it later in a session: reword guidance so it applies to the whole task, invoke the skill again after compaction, and move rules that must hold every time into a hook, which Claude Code runs on every matching event.

The task inside the skill fails:

• Scripts should fail loudly with a non-zero exit code and a message that says what to do next, as collect-diff.sh does.
• SKILL.md should tell the agent what to do on failure. In the example, step 2 says to show the error and ask the user, rather than guessing which code to review.
• Keep side effects out of automatically triggered skills. A review skill only reads; a skill that pushes, deploys or deletes should require direct invocation.

Share and discover skills

Claude Code's docs describe three ways to distribute a skill: commit .claude/skills/ to version control, ship it in a plugin's skills/ directory, or deploy it organization-wide through managed settings. For ideas and ready-made examples, browse the skills directory, including development skills and automation skills.

Quick reference

• One folder per skill; the folder name and name field match.
• Write the description as "what it does" plus "use when…", key use case first.
• Keep SKILL.md short; move detail into references/ and code into scripts/.
• Put non-specification fields under metadata if you want portability.
• Tell the agent what to do when a step fails.
• Require direct invocation for anything with side effects.