Claude Code Skills: A Practical Guide (2026)

A skill in Claude Code is a markdown file with YAML frontmatter the agent reads on demand. The frontmatter declares a description; the agent compares user prompts against that description and fires the skill when the prompt matches. The body is the instructions the agent follows once the skill fires -- typically a checklist, a sequence, or a recipe.

Skills are the right tool when the same workflow recurs often enough that re-explaining it each time wastes turns -- but light enough that defining a custom subagent would be overkill.

Where skills live

• User skills: ~/.claude/skills/<name>/SKILL.md. Personal, follow you across machines via your dotfiles.
• Project skills: <project>/.claude/skills/<name>/SKILL.md. Live in the repo so the whole team gets them.
• Bundled skills: shipped via Yaw Mode or another overlay. Loaded when the overlay is active.

All three sources concatenate into the available-skills list. Conflicts resolve in load order; the agent picks the first matching description it finds.

The description IS the firing predicate

This is the part most people get wrong. The skill body can be brilliant, but if the description doesn't match how users actually phrase the request, the skill never fires. A skill called release with the description "Cuts a release" will not fire when the user says "let's ship 1.4.0" -- the agent did not see "release" in the prompt.

Write the description as a list of trigger phrases the user actually uses:

The agent now fires the skill on any of those shapes. The body of the skill defines what happens when it does.

Skills vs slash commands

A slash command is an explicit invocation: the user types /release, the skill fires. A skill with phrase-based triggers fires implicitly when the user phrases a request the right way. Most production skills support both: an explicit slash command for the user who knows the skill exists, and trigger phrases for the user who phrases it naturally.

When to write a skill

• The workflow recurs. If you've explained the same sequence three times, write it down.
• The order matters. A skill enforces a checklist; ad-hoc instructions skip steps.
• The user-shape varies. Different team members phrase the same request differently. The skill's trigger-phrase list catches all of them.

When NOT to write a skill

• You'd invoke it once. An ad-hoc prompt beats a skill you forget you wrote.
• The workflow needs cross-tool composition the agent will pick the wrong sequence for. A subagent with a tight prompt is better.
• The "skill" is really a rule. "Always run lint:fix before committing" is a rule, not a skill -- put it in CLAUDE.md or a hook.

The Yaw skill family

Yaw Mode ships ~20 skills as concrete examples: /yaw-ship-ready (audit a branch for shippability), /yaw-pre-pr (lint + typecheck + test before opening a PR), /yaw-review (review the most recent changes for bugs), /yaw-implement (execute an agreed plan end to end). Each one is a 20-50 line SKILL.md with a tight description and an opinionated body. They are good shape references if you're writing your own.

Skill vs subagent vs hook -- choosing

• Skill: repeatable workflow the agent runs inside the host session. Best when the agent benefits from doing it inline.
• Subagent: work that should run with isolated context (so it doesn't pollute the host) or in parallel. Best when you want a different framing or concurrency. See the subagent guide.
• Hook: policy enforcement at the tool-call boundary. Best when the agent might quietly skip the rule. See the hooks guide.

Want the patterns?

Claude Code in Production Chapter 4 covers the description-as-firing-predicate in depth, the skills-vs-slash-vs-subagent decision tree, and the patterns that distinguish a skill the team uses from one that sits in the directory unused.

Published by Yaw Labs.

Related

• Claude Code in Production -- the book.
• Claude Code Subagents: A Practical Guide
• Claude Code Hooks: A Practical Guide
• CLAUDE.md: The Practical Guide