The complete guide to building skills for Claude

To create a Claude skill, make a folder named after the skill, add a SKILL.md file with a name and a description in YAML frontmatter, and write the instructions below it in Markdown. Save the folder in ~/.claude/skills/ for Claude Code, or zip it and upload it in Claude.ai. Then test it by asking for something that matches the description and by calling it directly with /skill-name.

A working skill is that small. A good one depends on four things: where the content comes from, how the description is written, what you move out of SKILL.md, and whether you tested it. The steps below follow the Claude Code docs and the Agent Skills specification, plus what we see across the skills we review.

Decide whether the task needs a skill

A skill pays off for a task you repeat, that has a procedure or house rules the model would not guess, and that you can check afterwards. Typical cases: a release checklist, a code review that follows your team’s conventions, a report in a fixed format, a workflow around an internal API.

It does not pay off when the agent already does the job well. The agentskills.io best practices put it as a question to ask of every paragraph: would the agent get this wrong without it? If not, cut it. A skill that restates what a PDF is, or how HTTP works, only uses up context.

Also decide the scope. One skill should cover one coherent unit of work. Too narrow, and several skills load for a single task. Too broad, and the description cannot be precise enough to trigger well.

Step 1: Start from real expertise, not a blank prompt

The most common way to produce a weak skill is to ask a model to write one from its general knowledge. The result reads fine and says things like “handle errors appropriately”. The official guidance describes two better sources:

• A task you just did with the agent. Work through a real task in conversation, correcting the agent as you go. Then turn the steps that worked, your corrections, the input and output formats, and the project facts you supplied into a skill.
• Existing project material. Runbooks, style guides, API schemas, code review comments, incident reports and version-control history all carry specifics that a generic article lacks.

If you only do one thing from this guide, do this: write down the corrections you make to the agent. Those corrections are the content.

Step 2: Create the folder and SKILL.md

Following the Claude Code docs, a personal skill lives at ~/.claude/skills/<skill-name>/SKILL.md. A project skill lives at .claude/skills/<skill-name>/SKILL.md and can be committed for your team.

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

---
name: summarize-changes
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: missing error handling, hardcoded values, tests that need updating.
If the diff is empty, say there are no uncommitted changes.

This is close to the example in the official docs. The line that starts with ! followed by a backtick-quoted command is dynamic context injection: Claude Code runs the command and puts its output into the skill before Claude reads it. If that command fails, the whole invocation aborts, so append || true to commands that may exit non-zero.

Claude Code watches the skills folders, so the new skill works without a restart. If you created a brand-new top-level skills folder in the middle of a session, run /reload-skills.

Frontmatter fields

The open specification defines these fields:

Field	Required	Rule
name	Yes	1-64 characters; lowercase letters, numbers and hyphens; no leading, trailing or double hyphens; must match the folder name
description	Yes	1-1024 characters; say what it does and when to use it
license	No	License name or bundled license file
compatibility	No	Up to 500 characters; environment requirements
metadata	No	String key-value pairs
allowed-tools	No	Space-separated pre-approved tools (experimental)

Claude Code adds its own fields. The ones you will use most: disable-model-invocation: true (only you can run the skill, right for deploys and commits), user-invocable: false (only Claude can), argument-hint, arguments, context: fork with agent (run in a subagent), model, effort, paths (limit activation to matching files) and hooks. Unknown fields are ignored, so a skill with Claude Code extras still loads in other agents, but the extras will not do anything there.

If you take arguments, use $ARGUMENTS, $0, $1 or a named placeholder. /migrate-component SearchBar JavaScript TypeScript fills $0, $1 and $2 in a body that says “Migrate the $0 component from $1 to $2.”

Step 3: Write a description that triggers

The description is the only thing the agent sees about your skill until it decides to load it, so it carries the whole burden of triggering. The description guide on agentskills.io gives four rules:

1. Write it as an instruction: “Use this skill when…” rather than “This skill does…”.
2. Describe the user’s intent, not the skill’s internals.
3. Be a little pushy: list the contexts where it applies, including ones where the user does not name the domain.
4. Keep it short; the hard limit is 1024 characters.

Compare:

# Weak
description: Process CSV files.

# Better
description: >
  Analyze CSV and tabular data files: compute summary statistics, add derived
  columns, generate charts, clean messy data. Use when the user has a CSV, TSV
  or Excel file and wants to explore, transform or visualize it, even if they
  don't say "CSV" or "analysis".

In Claude Code, description and when_to_use are combined and capped at 1,536 characters in the skill listing, and when you have many skills the listing may drop descriptions to fit a budget. Put the main use case first.

Step 4: Write the body so the agent follows it

Once the skill loads, the whole body sits in the context window next to everything else, so it has to earn its place. The best-practices guide suggests these patterns, and they match what we see in the strongest skills:

• Add what the agent lacks. Project conventions, non-obvious edge cases, which tool or API to use.
• Write a gotchas section. Concrete corrections: “The users table uses soft deletes, so queries need WHERE deleted_at IS NULL.” Whenever you correct the agent, add the correction here.
• Give defaults, not menus. “Use pdfplumber; for scanned PDFs use pdf2image with pytesseract” beats a list of four libraries.
• Teach a procedure. A method that works for any similar task generalizes; a single hard-coded answer does not.
• Provide output templates. Agents match concrete structures better than prose descriptions of a format.
• Add a validation loop. Do the work, run a check, fix, repeat. For risky batch operations, plan first, validate the plan, then execute.
• Match strictness to fragility. Give freedom where several approaches are fine; be exact where a command must run in a specific way.
• Explain why. “Do X because Y tends to cause Z” works better than a capitalized ALWAYS.

Keep SKILL.md under 500 lines, and the specification recommends under about 5,000 tokens. Put the most important rules at the top: after context compaction, Claude Code re-attaches only the first 5,000 tokens of each invoked skill.

Step 5: Add references, scripts and assets

A folder with only a SKILL.md is a prompt with a name. The skills people rely on ship more. The specification names three optional directories:

• references/ for documentation the agent reads when needed, such as an API schema or a domain guide. Keep each file focused so a read costs little context.
• scripts/ for code the agent runs. Scripts should be self-contained, document their dependencies, and print useful error messages. If you see the agent rewriting the same helper in every test run, that logic belongs in a tested script.
• assets/ for templates, images and data files.

Reference them from SKILL.md and say when to read them. “Read references/api-errors.md if the API returns a non-200 response” works; “see references/ for details” does not. Keep references one level deep. Inside a Claude Code skill, use ${CLAUDE_SKILL_DIR} for script paths so they resolve whether the skill is personal, project or in a plugin:

Run: python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .

This is progressive disclosure. The agent loads about a hundred tokens of metadata per skill at startup, the full body when the skill is chosen, and the files only on demand. One skill can therefore hold more than fits in a single prompt.

Step 6: Test it

Start with two manual checks: ask something that matches the description (does it trigger?), then run /skill-name (does it work?). If neither works, the Claude Code troubleshooting list starts with the description wording and the first line of the file, because the opening --- must be line 1 or the metadata is read as empty. claude --debug shows parse errors.

To catch frontmatter problems in bulk, run claude plugin validate .claude/skills (needs Claude Code v2.1.233 or later), or skills-ref validate ./my-skill from the specification’s reference library.

Step 7: Evaluate and iterate

A skill that worked once is not a tested one. The agentskills.io guide on evaluating skill output describes a loop you can run by hand:

1. Write two or three realistic prompts with an expected result each and save them in evals/evals.json.
2. Run every prompt twice from a clean context: once with the skill, once without it (or with the previous version of the skill).
3. Add assertions you can check, such as “the output is valid JSON” or “the chart has labeled axes”. Skip vague ones like “the output is good”.
4. Grade the runs, record time and tokens, and compare. A skill that adds 13 seconds and lifts the pass rate by 50 points is worth it; one that doubles token use for two points is not.
5. Read the transcripts. If the agent wasted steps, your instructions were vague or irrelevant. Revise and rerun in a new iteration-N folder.

For triggering, build about 20 queries, half that should trigger the skill and half near-misses that should not, and run each about three times. Split them roughly 60/40 into train and validation sets so you do not overfit the wording, and stop after around five description revisions.

The Claude skill creator: Anthropic’s skill-creator

You do not have to run that loop yourself. Anthropic publishes a skill for building skills, skill-creator, in the anthropics/skills repository. The docs describe it as the tool that runs evals, grades assertions, aggregates benchmarks, does blind A/B comparison of two versions, tunes descriptions against should-trigger and should-not-trigger prompts, and opens an HTML viewer for your feedback.

Our skill-creator review gives it depth 5 out of 5 and the verdict “install”; it has 418,037 recorded installs. It is a 33 KB SKILL.md with 10 Python scripts, grader and comparator prompts, a review viewer and a train/test description loop. To install it, add the marketplace with /plugin marketplace add anthropics/skills and install example-skills@anthropic-agent-skills, or run npx skills add anthropics/skills --skill skill-creator. Our install guide covers both routes.

Know what it runs. Its scripts start claude -p subprocesses using your Claude Code login, serve the review page on a local port, can end a process already using that port, and write a temporary command file under your project’s .claude folder during trigger evals. Our review found no hidden endpoints, and the viewer page loads Google Fonts and a pinned SheetJS script in the browser. We mark its security status “review”, not “no issues”: use it in a project you control.

What makes a skill deep

Our directory scores every skill from 1 to 5 for depth, described in how we review. A 1 is a short prompt. A 3 has references, templates or helper scripts. A 5 has references, scripts and tests or evals, something you can leave running unattended. The pattern is the same as the steps above: real references instead of general advice, scripts for the deterministic parts, and evals that show the skill beats no skill.

Of the 195 repositories we track, 65 include eval files and 121 ship a plugin manifest. Anthropic’s skills repository has 20 skills, 77 scripts and 14 tests. A short skill can still be excellent at its job: depth tells you what you are getting, not whether it is good.

Share and publish your skill

• For your team: commit .claude/skills/ to the repository.
• As a plugin: put the skill in a skills/ directory inside a plugin. Plugin skills run as /plugin-name:skill-name. See Claude Code plugins.
• In Claude.ai: zip the folder and use Customize, then Skills, then “Upload a skill”. Anthropic’s support article lists common failures: an oversized ZIP, a folder name that does not match the skill name, a missing skill file, and invalid characters in the name or description.
• For other agents: the same folder works wherever the open format is supported, including Codex. Check each agent’s path on our platforms pages.

If you publish, read your own skill the way a stranger would. Whoever installs it runs its scripts with their permissions, so keep network calls and tool pre-approvals to what the job needs, and say plainly in the README what the skill reads, writes and sends. Our security checklist lists what reviewers look for.

Common mistakes

• A description that says what the skill is, not when to use it.
• A 900-line SKILL.md that belongs in references/.
• Rules that must hold every time, written as prose. Anthropic’s guidance for those is a hook, which runs whether or not the model follows the skill.
• Shipping without a baseline run, so you cannot tell whether the skill helps.
• Unpinned downloads (npx some-tool with no version) inside scripts.

When you want examples to learn from, browse the reviewed skills and sort by depth; the 4 and 5 scores show how far a skill can go beyond a prompt.