How to Use Skills in Claude Code (2026)

That is the skill model in Claude Code: write once, invoke with a slash command, share with the team by committing .claude/skills/ to git.

If you are still choosing between assistants, Claude vs ChatGPT in 2026 covers product positioning; this page is only about Claude Code’s skill mechanism.

What is a skill?

A skill is a directory whose entry point is SKILL.md. At the top of that file, Anthropic expects YAML frontmatter (between --- lines) with at least a clear description so Claude can decide when the skill is relevant; the rest of the file is the instruction body Claude follows when the skill is active.

Compared to stuffing everything into CLAUDE.md, the win is lazy loading: long reference material does not sit in every turn until it is needed — Anthropic describes the skill body as loading when the skill is used.

Pattern: Without a skill you retype: “Review this PR for SQLi, missing auth, and logging gaps.” With a skill you type: /security-review and the same checklist, table format, and severity rubric apply every time.

Slash commands: folders and files

The name field in frontmatter becomes the /slash-command (lowercase, hyphens). If you omit name, Claude Code falls back to the directory name of the skill folder.

Minimal layout on disk:

.claude/skills/api-review/
└── SKILL.md

That produces /api-review for everyone who has this project (or your personal skills path) on their machine.

Example SKILL.md body (after frontmatter): Review the given FastAPI route for production readiness. ## Checks — Auth: JWT on protected routes; Logging: request id, latency, status; Contract: response matches OpenAPI fragment; Security: Pydantic validation on inputs. ## Output — table columns: Severity | File:Line | Issue | Suggested fix.

Optional siblings next to SKILL.md — templates, sample outputs, small scripts — stay referenced from the main file so Claude knows when to read them.

Commands folder vs skills (merged)

Anthropic’s current Claude Code documentation states that custom commands have been merged into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both register /deploy and behave the same way for invocation.

Practical rule: if the names collide, the skill wins. New work should prefer .claude/skills/<name>/SKILL.md because skills support supporting files, richer frontmatter (for example who may auto-invoke the skill), and the same argument placeholders as command-era Markdown.

For parameters, skill Markdown supports $ARGUMENTS, indexed $0 / $ARGUMENTS[0], and named placeholders tied to an arguments: list in frontmatter — see Anthropic’s “Available string substitutions” section in the skills doc.

Where skills live: scope and precedence

Claude Code loads skills from several tiers. When the same command name exists in more than one place, higher-priority locations override lower ones (enterprise above personal above project; plugin skills use a namespace so they do not accidentally mask your local /name).

Monorepos: Anthropic documents automatic discovery of nested .claude/skills/ directories (for example under packages/frontend/) when you work in those subtrees — useful when only one package owns a workflow.

Live edits: Changes under watched skill directories can apply in-session; creating a brand-new top-level skills directory may require restarting Claude Code so the watcher attaches.

How Claude discovers and runs a skill

1. You type /api-review (or Claude matches your task to a skill description).
2. Claude Code resolves the skill file and injects its instructions into the session context for that turn.
3. Claude executes the workflow with normal tools (read, grep, edit, etc.) subject to your permissions and any allowed-tools limits in frontmatter.

There is no separate proprietary “skill runtime” — it is Markdown plus the same agent loop you already use.

GitHub: anthropics/skills and the plugin marketplace

Anthropic maintains a public repository of example and production-style skills: https://github.com/anthropics/skills. The README states the repo implements Anthropic’s skills system, points to the Agent Skills open standard at agentskills.io, and ships categories from document skills to developer workflows.

For Claude Code, the README documents registering that repo as a plugin marketplace, then installing bundles such as document-skills or example-skills:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

After install, you invoke behaviour by mentioning the skill in natural language (for example asking Claude to use the PDF skill on a path) or via slash commands where those plugins expose them — treat the README of each plugin bundle as the source of truth for exact names.

The repository also contains a spec/ folder tied to the Agent Skills specification and a template/ folder for scaffolding — useful when you want your private SKILL.md files to match Anthropic’s layout expectations.

Design habits that survive real repos

• Tight descriptions. Anthropic’s frontmatter reference notes that the combined description and when_to_use text is truncated for the skill listing to control context size — front-load the trigger phrases a human (and Claude) would grep for.
• Match freedom to risk. High-level prose for reviews; stricter steps for migrations; scripts only when you accept maintenance cost.
• Progressive disclosure. Keep SKILL.md focused; move long references one level deep (REFERENCE.md, examples dir) and link them explicitly.
• Do not teach the basics. If every token repeats documentation Claude already knows, you pay context without gaining behaviour.
• Disable auto-invoke when needed. For dangerous or rare workflows, Anthropic supports disable-model-invocation: true so only deliberate /name runs load the body.

Built-in app commands such as /help still control the Claude Code client itself; custom skills control how Claude tackles your repeatable tasks — see the separate commands reference linked from Anthropic’s skills page for the bundled list.

Frequently asked questions

Ship one thin skill this week (/weekly-status or /pr-risk-scan). Prove the loop, then grow supporting files only where reuse proves it.