Claude Code Guide — Part 3: Skills

What a Skill is

A line in CLAUDE.md is advice that rides every turn. A Skill is a markdown file at .claude/skills/<name>/SKILL.md that stays dormant until something pulls it in — either Claude reaching for it because the description matches, or you typing /<name> to run it directly. Same .claude/ directory, different shape: the briefing is always loaded, the Skill is loaded on demand.

The file has two parts. YAML frontmatter tells Claude what the Skill is for. The markdown body holds the procedure itself.

Skills live alongside the rules folder and CLAUDE.md in the same .claude/ directory you toured in Part 2. Three locations matter:

• Project: .claude/skills/<name>/SKILL.md — applies in this repo only. Commit it.
• Personal: ~/.claude/skills/<name>/SKILL.md — applies across all your projects.
• Bundled: ships with Claude Code. /simplify, /loop, /init and others are Skills, not built-in commands.

Custom slash commands have been merged into Skills. Files under .claude/commands/ still work, but new procedures should land in .claude/skills/. Skills support directories of supporting files, optional path scoping, and the option to fire automatically — commands/ does not.

The two ways a Skill fires

Same file, same shape. The only thing that changes is one frontmatter field.

Default — Claude invokes it. With no special frontmatter, both you and Claude can invoke the Skill. Claude reads the description field and reaches for the Skill on its own when what you're asking matches. House style, naming conventions, glossaries, voice rules for prose, anything you want Claude to apply without you naming it. The docs call this kind of content reference content.

disable-model-invocation: true — only you invoke it. Add that line to the frontmatter and Claude only runs the Skill when you type /<name> in a session. Use this for procedures with side effects: /commit reads the diff and runs git commit. /deploy pushes to production. /review checks out a PR branch and runs checks. The slash makes the action deliberate — you don't want Claude deciding to deploy because the code "looks ready." The docs call this kind of content task content.

Both flavours are the same primitive. You'll author one of each in this part, then verify both fire the way you expect.

Why the description field is load-bearing

The full schema — every frontmatter field, every option — lives in the docs (see Skills in the official docs). The prompts in the sidebar walk you through the relevant fields one at a time, so you don't need to memorize the list before starting.

One field is worth flagging up front. description is what Claude matches against to decide an auto-fire Skill applies, and a vague description silently fails to fire. The Skill is on disk, the file is valid, the description is in context — and nothing happens. No error, no warning, just dormant. Procedures with side effects also lean on allowed-tools, which is the permission boundary the Skill runs inside; everything else in the schema is matching on the description.

The verify step at the end of this part is the check for that gotcha.

Author your first Skill

The first prompt in the sidebar walks you through a Skill that fires automatically. Claude asks you one frontmatter question at a time — name, description, paths, allowed tools, body — then writes the file to .claude/skills/<name>/SKILL.md. The directory gets created for you if it doesn't exist.

Pick something real. House style for a project. Naming conventions for variables or files. A short glossary of project-specific terms. Voice rules for prose work. Anything you'd otherwise paste into chat every time. The Skill captures it once and Claude reaches for it from then on.

Open the prompts panel (right side on desktop, the floating button on mobile), copy Prompt 1, and paste it into your Claude Code session.

Author a slash command

The second prompt has the same shape with the configuration flipped: disable-model-invocation: true so the Skill only fires when you type the slash. Claude walks the same kind of frontmatter interview, plus the optional arguments field for slash commands that take input after the name (/review 1234).

Pick a procedure with side effects. The classic ones are /commit (stages changes, drafts a message, runs git commit) and /review (checks out a PR branch, runs the checks). Anything you want to be deliberate about. The Skill is the procedure on disk; the slash is your way of telling Claude to run it now.

Copy Prompt 2 from the sidebar when you're ready.

Verify both fire

Authoring a Skill doesn't guarantee it fires. The auto-fire flavour has the sharp edge: if the description is too vague, Claude doesn't reach for the Skill even when the situation obviously calls for it. The Skill is on disk, the description is in context, and nothing happens.

The third prompt is the check. For the auto-fire Skill, Claude drafts a real test prompt that should obviously match the description, you paste it in a fresh session, and you watch whether Claude reaches for the Skill on its own. If it doesn't, the description needs tightening — Claude helps you fix it and re-save. For the slash-command Skill, you run /<name> and confirm the body did what you wrote.

Copy Prompt 3 from the sidebar when both Skills are saved.

What's next

Part 4 covers subagents — separate sessions Claude Code can spawn for a focused task in a clean context, with their own tool permissions and their own Skills. Continue at Part 4 — Subagents.