Creating reusable Claude Code skills

If I type the same instructions three times, I turn them into a skill.

A skill can be a short saved prompt. You can invoke it with a command such as /review, or let Claude load it when the description matches your request. If the workflow grows, the same skill can include templates, examples, scripts, and references.

Claude Code still supports files in .claude/commands/. Existing commands do not need an urgent migration. For anything new, I would use .claude/skills/<name>/SKILL.md because it gives you more room without making the first version complicated.

Create one small skill

Start with a project review:

my-website/
  .claude/
    skills/
      review/
        SKILL.md
  index.html

Put this in SKILL.md:

---
name: review
description: Review the current project and list visible problems.
disable-model-invocation: true
---

Review the current state of the project.
Check for placeholder content, broken links, inconsistent styling, and unfinished work.
Give me a short list of what needs attention.

The folder name becomes the command. Type /review and Claude loads those instructions. Run /skills to see everything currently available.

Claude Code watches an existing skills directory, so edits to SKILL.md take effect in the current session. If the top-level skills directory did not exist when the session started, restart Claude Code once so it can watch the new directory. That makes the first few versions cheap to get wrong.

I set disable-model-invocation: true for a review I want to start myself. Remove that line when you want Claude to use the skill automatically after recognizing a matching request.

Pass an argument

Use $ARGUMENTS when the same workflow should accept a different file or topic each time.

Create .claude/skills/explain/SKILL.md:

---
name: explain
description: Explain a file or part of the project in plain English.
disable-model-invocation: true
argument-hint: "[file or topic]"
---

Explain what $ARGUMENTS does in plain English.
Assume I am not a programmer. Focus on what it does and what depends on it.

Now type:

/explain index.html

Claude receives index.html in place of $ARGUMENTS. The same skill can explain a stylesheet, navigation section, or build script.

Three useful starters

I would begin with one of these:

• /review: inspect the current changes and list visible or functional problems
• /explain [file]: explain what a file does and what could break if it changes
• /check-mobile: inspect the HTML and CSS for likely mobile problems, then test below 640px when a browser integration is available

That last boundary matters. A prompt cannot prove how a page renders by reading code alone. If Claude cannot open a browser, the skill should tell you what to check yourself.

For a writing project, a /proofread [file] skill can check spelling and awkward phrases. For file organization, /duplicates can find matching names and sizes, but it should report first and wait before deleting anything.

Save the checks and safety rules you do not want to remember each time. The short command is only the trigger.

Project or personal

Keep repository-specific skills inside the project:

.claude/skills/review/SKILL.md

Put it in your home configuration when it applies across projects:

~/.claude/skills/review/SKILL.md

Most of my website workflows now live as project skills. I keep review, bug fixing, and blog work separate because each needs different instructions and safety checks.

The core SKILL.md format follows the Agent Skills open standard, but Claude Code adds fields such as invocation controls. Check another tool's support before assuming the whole skill is portable. You can also package a set of skills as a plugin if you want to share them. Neither matters for your first one. Both matter once you have five you would rather not rewrite.

Do not begin by building a large library. Use the three-use rule. When you have typed the same detailed instruction for the third time, save it. If the workflow later needs a template or validation script, add it to the skill directory then.

Skills and CLAUDE.md do different jobs

CLAUDE.md holds concise project facts and instructions that should be available in each session. A skill holds a reusable action that loads when you or Claude invokes it.

Put “use pnpm for this project” in CLAUDE.md. Put the steps for reviewing a release in a skill.

Anthropic's current skills documentation covers supporting files, argument options, invocation controls, and the legacy command format.

Start with one repeated prompt. Save the decisions and checks, not just the sentence you are tired of typing.

Sources

• Extend Claude with skills, Anthropic. Supports skill structure, command naming, arguments, invocation controls, legacy commands, live change detection, and the restart caveat.
• Specification, Agent Skills. Defines the portable core format based on a skill directory, required SKILL.md, YAML frontmatter, and optional supporting resources.