This is a cross-post — the original (and any updates) live at
[broke2builtai.com].
The first time I watched Claude Code reach for a skill I hadn't told it to use — read a folder, run the script inside it, and hand back the finished thing — the difference from a slash command finally landed. A slash command waits for you to type it. A skill waits for the situation. Claude decides. That one shift is the whole feature, and building one takes about five minutes once you know where the file goes.
Here's the entire thing end to end, including the one gotcha that decides whether your skill ever actually fires.
A Skill is a folder with a SKILL.md
file inside it. The Markdown holds instructions; the YAML frontmatter at the top holds a name
and a description
. That description is doing the most important job in the whole file: Claude reads it to decide, on its own, whether the current task warrants invoking the skill. Nothing else you write matters if the description doesn't get you picked.
That's the mental model to hold onto: a custom slash command is a prompt you trigger by typing /name
; a skill is a procedure Claude triggers when the context matches. Same reusable-instructions idea, opposite trigger.
Two locations register, exactly like commands and subagents:
.claude/skills/<skill-name>/SKILL.md
inside the repo. Committed, so your whole team gets it.~/.claude/skills/<skill-name>/SKILL.md
in your home directory. Follows you across every project on your machine.Each skill is its own folder, and the folder name should match the name
in the frontmatter. A loose SKILL.md
sitting somewhere else won't be picked up.
Create the folder and the file:
.claude/skills/pytest-runner/SKILL.md
Then write the two-part file — frontmatter, then body:
---
name: pytest-runner
description: "Run, generate, or debug pytest tests for this project. Use when the user asks to run the test suite, add tests for a function, or figure out why a test is failing."
---
When invoked:
1. Run the suite with `python -m pytest -q` and read the output.
2. If tests fail, show the failing test names and the assertion, then propose the smallest fix.
3. When asked to add tests, match the existing style in `tests/` — same fixtures, same naming.
4. Never mark work done until the suite is green; paste the passing summary line.
That's a working skill. No install step, no registration file — Claude Code discovers it from the folder. Next time you ask something that matches the description, Claude reaches for it.
If your skill never fires, the description is almost always why. Claude selects a skill by matching the task against the description text, so a vague description: helps with tests
competes badly against everything else in context and usually loses.
Write the description like a trigger list, not a summary. Name the concrete situations, the verbs, and the file types:
description: Testing helper.
description: Run, generate, or debug pytest tests. Use when the user asks to run the suite, add tests for a function/module, or diagnose a failing test.
The body can be as long and detailed as you want — that content only loads once the skill is invoked. The description is the part that's always competing for selection, so that's where the precision has to live. This is the same discipline behind writing a good system prompt for an agent: be explicit about when, not just what.
The reason a skill beats a slash command for real workflows is that the folder can hold more than instructions. Anything you drop in the skill directory is available to Claude when the skill runs:
.claude/skills/release-notes/
├── SKILL.md
├── template.md # the format to fill in
└── changelog-parse.py # a helper the skill runs
Reference them from SKILL.md
by relative path — "fill in template.md
", "run changelog-parse.py
on the git log" — and Claude reads or executes them as part of following the skill. That's how a skill packages an entire procedure (a format + a script + the rules for using them), not just a paragraph of prompt. If the script needs a tool that prompts for permission, the same permission and hooks rules apply as anywhere else in Claude Code.
Three ways to give Claude Code reusable instructions, and they're not interchangeable:
/review
, /deploy
).The practical rule: standing context goes in CLAUDE.md; a procedure you invoke yourself is a slash command; a procedure Claude should invoke when it sees the trigger is a skill. Getting that split right is what keeps your everyday context lean while still having deep procedures on tap.
Build the skill small, then watch whether it fires. Ask something that should trigger it and see if Claude reaches for it — if it doesn't, tighten the description and try again. That loop takes a couple of minutes and is the only real test that matters, because a skill that never gets invoked is just a Markdown file nobody reads.
This site runs its own automation on Claude Code and free-tier AI. If you're wiring up cheap models to do real work, we run everything on GLM's free tier through the z.ai Coding Plan (referral link — it funds our compute); a tight SKILL.md is exactly the kind of harness that keeps a cheaper model on rails.
Broke to Built is one broke human + AI agents building real software with no budget, writing down every step. This site's tools run on free GLM — z.ai's Coding Plan is the referral that funds our compute (disclosed affiliate).