How to Create a Claude Code Skill in 2026 (SKILL.md, Step by Step)

A Claude Code skill is the cleanest way to stop repeating yourself. Instead of pasting the same multi-step procedure into every session, you write it once as a skill, and Claude loads it automatically whenever the task matches. No plugin manager, no setup screen — just a folder with a SKILL.md file inside.

This is the exact format in 2026, where skills live, what makes a description actually fire, and the fastest way to production — from someone who generates these files for a living.

What a Claude Code Skill Actually Is

A skill is a directory that contains a single file called SKILL.md. That file has two parts: a short YAML frontmatter block at the top, with a name and description, and a markdown body underneath with the instructions Claude follows when the skill is triggered. Everything else — supporting scripts, templates, examples — is optional and lives in the same directory.

Here's how it behaves: when you send Claude a message, it reads the description of every skill it can see and compares it to your request. If one matches, Claude pulls that skill's full content into the conversation. If none match, no skill loads and you get default behavior. That one line means the description does the heavy lifting — it's the only thing Claude uses to decide whether your skill applies.

The format follows the open Agent Skills standard, so the same SKILL.md file works across Claude Code, Cursor, Codex CLI, OpenClaw, and other compatible agents. Claude Code extends the standard with extras like invocation control and subagent execution, but the core spec is identical.

The SKILL.md Format, With a Real Example

Create a directory, drop a SKILL.md inside, and write the frontmatter plus instructions:

---
name: conventional-commit
description: >
  Use this skill any time the user asks for a git commit or to
  write a commit message. It writes the message in Conventional
  Commit format.
---

When you create a git commit, follow these rules.
1. Start the subject line with one of: feat, fix, chore,
   docs, refactor, test, perf.
2. Add a colon and a space, then a short imperative summary.
3. Keep the subject under 70 characters.
4. Use the imperative, present tense ("add", not "added").

Where Skills Live

Put a skill in ~/.claude/skills/<skill-name>/SKILL.md to make it available globally everywhere Claude Code runs. Put it inside a project's .claude/skills/ to scope it to that repository. The directory name becomes the /skill-name command you can type to invoke it directly, and Claude discovers new skills at startup.

Write Descriptions That Actually Fire

Most skill problems are description problems. A vague description means the skill either fires when it shouldn't or never fires when it should. The winning pattern is one sentence on what the skill does, then a "Use when…" clause that names concrete triggers:

# Weak — too abstract, won't trigger reliably
description: Helps with migration work.

# Strong — names the trigger and the boundary
description: >
  How to write and review schema migrations in this repo.
  Use when creating a migration, editing anything under
  db/migrations/, or reviewing a PR that touches the schema.

Test three things before you trust a skill: invoke it directly with /skill-name to prove the body works; start a fresh session and ask the way a teammate would, without naming the skill, to confirm it fires automatically; and check that it doesn't misfire on adjacent tasks.

The Fastest Way to a Production Skill: Record It

Writing a SKILL.md by hand is fine for a small procedure, but it breaks down fast. For a 15-step browser workflow you'd need to perform the flow, decompose it into discrete steps, name every variable, define success conditions, and format it all correctly — an hour of careful work for a process that takes five minutes to run.

Claudia removes that step. Install the Chrome extension, click Record, run through the workflow normally, stop, and export. Claudia produces a SKILL.md file with the name, description, stepping logic, and input variables Claude Code will prompt for at runtime. Sensitive values like passwords are never hardcoded — they're marked as variables for Claude to ask about.

It's exactly the "show, don't write" model Anthropic's own Record a Skill in Claude Cowork uses — but local-first: everything is encrypted with AES-256 on your device, nothing uploads during recording, and you don't need a paid AI plan to capture browser workflows.

Skills vs. CLAUDE.md

A common mistake is stuffing a procedure straight into CLAUDE.md. That file's content is loaded into every session, so every line costs tokens even when it's irrelevant. A skill, by contrast, loads only when used — its body is invisible to Claude until the description matches. The rule of thumb: facts and project conventions belong in CLAUDE.md; repeatable multi-step procedures belong in skills.

Build a Skill Library, Not Just One Skill

Individual skills are useful. A library is transformative. Each recorded workflow you export is another skill Claude Code can reach for, and over time you're not using a generic coding assistant — you're using an agent that already knows your tools, your systems, and your exact way of doing things. The SKILL.md format is the bridge between the work your team does today and the automation Claude Code can deliver.

Getting started takes five minutes: create ~/.claude/skills/, write one skill, test it fires, then start recording the workflows you repeat every week. Record once, automate forever — that's the whole model.