How to Create a Claude Code Skill (SKILL.md)

What is a Claude Code skill?

A Claude skill is a reusable capability you give an agent as a small folder containing a SKILL.md file (and optional scripts or reference files). Claude reads the skill's name and description up front, and loads the full instructions only when the current task matches — so skills scale without bloating the context window.

Claude Skills are Anthropic's implementation of the open Agent Skills standard (the same SKILL.md format works in Claude Code, the Claude apps, and other agents). If you're new to the concept, start with what agent skills are.

Claude skill vs command, subagent, plugin, and MCP

These primitives overlap, so pick the right one:

• Skill — reusable know-how ("how to review a PR"). Loaded on demand via SKILL.md. Best for repeatable workflows.
• Slash command — a manual shortcut you invoke explicitly. A skill triggers itself when relevant; a command doesn't.
• Subagent — a separate agent with its own context window for a delegated task. Heavier than a skill.
• Plugin — packages commands, skills, and hooks together for distribution.
• MCP server — connects the agent to external tools and data. MCP adds *tools*; a skill adds *instructions*. They're complementary.

Anatomy of a SKILL.md file

Every skill needs a SKILL.md with a YAML frontmatter block and a markdown body:

• name — lowercase, kebab-case, and it must match the folder name (max 64 chars).
• description — one or two sentences stating what the skill does and when it should trigger. This is the single most important field: Claude uses it to decide whether to load the skill.
• Body — the actual instructions, written as clear imperative steps. Keep it under ~500 lines; move long references into separate files the skill can point to.

How to create a Claude Code skill step by step

Follow these steps to build your first skill from scratch.

Installing your skill: the ~/.claude/skills folder

Claude Code discovers personal skills in ~/.claude/skills/ and project skills in .claude/skills/ inside a repo. Create a folder named after your skill and drop the SKILL.md inside:

mkdir -p ~/.claude/skills/code-reviewer
# add ~/.claude/skills/code-reviewer/SKILL.md

Restart Claude Code (or start a new session) and the skill is available — Claude invokes it automatically when a task matches the description. No manual "use this skill" needed.

A complete SKILL.md you can copy

Here is a minimal, working example. Copy it into ~/.claude/skills/code-reviewer/SKILL.md:

---
name: code-reviewer
description: Reviews a diff or pull request for correctness bugs, security issues, and style. Use when the user asks to review code, a diff, or a PR.
---

# Code Reviewer

When asked to review code:

1. Read the full diff before commenting.
2. Flag correctness bugs first, then security issues, then style.
3. Give concrete feedback with file:line references.
4. End with a short summary and a clear approve / request-changes call.

How to install a ready-made Claude skill

You don't have to write a skill from scratch — you can install an existing one. Three ways, no coding required:

1. Plugin marketplace (Anthropic's official method). From inside Claude Code, add a marketplace, then install a plugin (a plugin can bundle skills, commands, and hooks):

/plugin marketplace add anthropics/skills
/plugin install <plugin-name>@anthropic-agent-skills

The official marketplace is available on startup, so you can also install directly — e.g. /plugin install github@claude-plugins-official — then run /reload-plugins to activate without restarting.

2. The skills CLI (community tool). Install a raw SKILL.md skill from any GitHub repo:

npx skills add owner/repo --skill <skill-name> -a claude-code -g

-g installs globally to ~/.claude/skills; drop it to install into the current project (.claude/skills). This is the third-party skills.sh CLI, not an Anthropic command.

3. Manual. Copy any skill folder (the one containing SKILL.md) into ~/.claude/skills/ — Claude Code picks it up next session.

Or install any skill from the ProfessorGPT catalog in one command.

Let Claude scaffold it: skill-creator

Anthropic ships an official skill-creator skill that writes skills for you — it drafts the SKILL.md, helps add test cases, and tunes the description for reliable triggering. Install it like any skill (via the plugin marketplace above), then ask Claude in plain language: *"create a skill that reviews my PRs."* In Claude Code it auto-triggers from your request — there is no /skill-creator command. (In OpenAI Codex the same idea is a built-in $skill-creator command.)

Build a Claude skill without writing YAML

If you'd rather not hand-write frontmatter, the Skill Builder generates a clean, standard-compliant SKILL.md from a few inputs — pick a category, describe the job, and download or install the result. You can also browse ready-made skills and adapt one.