Claude Skills: Reusable Playbooks for Your Coding Agent

Claude Code’s own category description on this site name-checks “custom skills” as one of the things worth covering in depth – and yet, despite the whole Harnesses series walking through a dozen different agent tools, nothing here has actually explained what Claude Skills are or how to build one. That’s worth fixing, because Skills are quietly becoming the mechanism that makes an agent reliable at a specific job, rather than just generally capable.

What a Skill actually is

A Skill is a folder with a SKILL.md file at its root, plus whatever scripts, templates or reference files it needs. The SKILL.md is mostly plain Markdown: a short YAML frontmatter block with a name and description, followed by instructions written for the model rather than for a human reader. Claude scans the descriptions of every installed Skill, and when a task matches one closely enough, it loads that Skill’s full instructions into context before acting – the rest of the time, the Skill just sits there costing nothing.

my-skill/
  SKILL.md          # frontmatter + instructions
  scripts/
    lint_check.py   # optional helper scripts a Skill can shell out to
  reference/
    style-guide.md  # optional reference material to read on demand

Why this beats a long system prompt

Stuffing every house rule into a system prompt or a giant CLAUDE.md means paying for all of it, on every single turn, whether it’s relevant or not. A Skill is the opposite: near-zero cost until its description actually matches what’s happening, at which point its full instructions – which can be far longer and more detailed than anything you’d want sitting in context permanently – get pulled in. That’s the whole trick: Skills let an agent carry dozens of deep, specific playbooks without dragging all of them along all the time.

A worked example: a PR-description Skill

Say a team wants every pull request description written the same way – a summary, a bulleted list of changes, and a test plan, in that order, with no exceptions. Rather than repeating that in every prompt, it becomes a Skill:

---
name: pr-description
description: Use when writing or updating a pull request description for this repo.
---

1. Summarize the change in 1-2 sentences at the top.
2. List every functional change as a bullet, oldest-file-first.
3. End with a "Test plan" section as a markdown checklist.
4. Never mention internal ticket numbers in the body - link them instead.

Any time Claude Code is about to write a PR description in that repository, its description matches, the instructions load, and the output follows house style automatically – without anyone having to remember to ask for it.

Skills vs. subagents vs. plain instructions

• A Skill is a reusable, on-demand playbook for a specific recurring task – it changes how a task gets done, not who does it.
• A subagent is a separate context/session doing a chunk of work and reporting back – useful for parallelism or isolation, not for teaching a repeatable procedure.
• A CLAUDE.md or system prompt is always-loaded context – right for house rules that genuinely apply to everything, wrong for anything niche enough that most turns don’t need it.

The part that matters beyond Claude Code

Skills are an open format, not a Claude-only trick – the same SKILL.md structure is already being picked up by other agent tools, including Cursor and VS Code’s agent mode. That’s why a real third-party ecosystem has sprung up around it in the last few months: marketplaces now list everything from PDF-handling Skills to full design-system Skills, most installable in one click. Writing a Skill once and having it work anywhere that speaks the format is a meaningfully different proposition from writing yet another tool-specific config file.

Getting the trigger description right

The single most common way a new Skill fails isn’t the instructions – it’s the description. If it’s too vague (“helps with code”), it either never fires or fires constantly for the wrong task. If it’s too narrow, it silently never matches. The reliable pattern is to describe the trigger condition concretely: what kind of request, in what context, should cause this to load – the same way the PR-description example above names the exact situation rather than just the general subject.

Worth building one this week

The lowest-effort place to start is whatever task gets re-explained most often in a given repo or workflow – a commit-message format, a specific test-writing convention, a deploy checklist. Turning that single recurring instruction into a Skill, rather than retyping it, is a genuinely small change that removes a genuinely recurring annoyance.