← Writing

Claude Code Skills: the Complete Working Guide

I run two companies and about a dozen codebases, and almost every working session I have with Claude Code leans on skills. Not in the demo-video sense — in the "this is how the machine knows my product's pricing, my deploy runbook, and my brand voice without me repeating it" sense. This is the guide I wish existed when I started: what skills are, when they actually fire, and which ones are worth building first.

What is a skill in Claude Code?

A Claude Code skill is a folder containing a SKILL.md file — instructions, references, and assets that Claude loads on demand when a task matches the skill's description. Skills let you package domain knowledge (a product's pricing, a deploy runbook, a brand voice) once and have every session use it consistently, instead of re-explaining context in every conversation.

The anatomy is deliberately boring:

my-skill/
├── SKILL.md          # frontmatter (name, description) + the instructions
├── references/       # deeper documents loaded when needed
└── assets/           # files the skill uses (logos, templates, images)

The description in the frontmatter is the load-bearing part. It's how Claude decides whether this skill is relevant to what you just asked. Write it like you're describing when a colleague should be pulled into a meeting — specific triggers, not vibes.

Do skills work in Claude Code — and when do they fire?

Yes, and the firing rule is the thing most people get wrong at first. Skills load on demand, by description match — they are not always-on context. That's the difference between a skill and your CLAUDE.md/AGENTS.md file:

  • AGENTS.md / CLAUDE.md — always loaded. How to work in this repo: commands, conventions, danger zones. Keep it short; it's a tax on every session.
  • Skills — loaded when relevant. Deep knowledge that would bloat every conversation if it were always present: your product's full pricing table, your design tokens rationale, the 600-line brand guide.

In practice this means a session about fixing a CSS bug never pays the cost of your email marketing playbook, but the moment you say "draft the launch email," the right skill walks into the room already briefed.

Anatomy of a skill that actually gets used

Here's a real pattern from my setup — a product-facts skill:

---
name: rcp
description: Detailed product specifications for Radio Content Pro —
  pricing, format kits, content structure, operations. Use when you need
  specific RCP product information or brand guidelines.
---

# Radio Content Pro

## Pricing
(the actual table — one source of truth)

## Format kits
(the real list, not a sample)

Three things make it fire reliably: the description names the product and the kinds of questions it answers; the body contains facts stated once, with sources; and deeper material lives in references/ so the initial load stays cheap.

The failure mode I see most: skills written like documentation instead of like briefings. Documentation describes; a briefing says what to do and what not to touch.

The best skills to build first

If you're starting from zero, build these four — in this order:

  1. Product facts. Pricing, plans, URLs, the canonical names of things. This kills the most common AI failure in business content: confidently wrong facts. Mine literally carries a line about which pricing source is authoritative, because two of my own documents once disagreed by $400/year — and an agent caught it by loading the skill.
  2. Deploy/ops runbook. What deploys where, what's live automation, what must never be touched casually. The first time an agent declines to edit a live pipeline because the skill told it not to, this skill has paid for itself.
  3. Brand voice. Words you use, words you ban, real samples. Voice drift is death by a thousand posts.
  4. House code style. Not a linter replacement — the judgment calls linters can't encode.

Generic skills ("be a great marketer") underperform specific ones ("RCP's approved CTAs are X, Y; never promise Z") by a wide margin. Specificity is the entire game.

Skills vs. agents vs. commands

The three get conflated constantly. The division that's held up across my repos:

  • Skills = knowledge. What's true, what the rules are. Loaded by relevance.
  • Commands (slash commands) = workflows you invoke deliberately: /research-keyword, /optimize-post. They use skills.
  • Agents (subagents) = workers with a role and tool access, for delegated or parallel work: a code reviewer, an SEO strategist running a full audit.

Choosing wrong looks like: a 400-line "agent" that's really just facts (should be a skill), or a skill that ends with "now go do the deploy" (should be a command). If it knows, it's a skill; if it does on request, it's a command; if it works independently, it's an agent.

Running skills across a whole portfolio

This is where it gets interesting — and where I have scars. Eleven of my repos share one central skills library, symlinked into ~/.claude so every session on every machine gets the same brains. Two lessons from running this in production:

Decide the source of truth, then enforce it. For months I had product skills duplicated in two places, each claiming to be canonical. A pricing correction landed in one copy and not the other, and an agent later quoted the stale number. The fix wasn't clever tooling — it was one README sentence ("edit HERE; the other is a mirror") plus a scheduled job that diffs the copies and flags drift.

Repo-specific facts don't belong in shared skills. The pattern that works: shared skills carry the method (how to research keywords, how to write briefs), and each repo carries a small context file with its facts. The skill reads the repo's file when it arrives. One brain, many bodies.

I wrote up the day we standardized all of this across the portfolio in Standardizing eleven repos in a day — the skills architecture above is a direct product of that work.

FAQ

Do skills work in Claude Code? Yes — they're a first-class feature. Skills load automatically when a task matches their description, and you can invoke them explicitly. The reliability comes from writing specific descriptions, not from hoping.

What is a skill in Claude Code? A folder with a SKILL.md file — frontmatter naming it and describing when it applies, plus instructions and optional references/assets. Think "packaged briefing," not "plugin."

What are the best skills for Claude Code? The boring ones: your product's facts, your deploy runbook, your brand voice, your code style. Specific beats clever every time.

How is Claude Code so good at coding? Partly the model, partly the harness — but in day-to-day use, the gap between a mediocre and a great setup is context: skills, a tight AGENTS.md, and repo facts it can trust. Give it what a new senior hire would need on day one, and it performs like one.

More field notes like this: subscribe to the RSS feed, or start with what I'm building.