If your feed looks like mine this week, it's a wall of "build agent skills from scratch" courses — Anthropic's, Andrew Ng's, everyone's. The concept is genuinely useful and the actual build is smaller than the hype suggests. Here's the whole thing, copy-paste ready, in the time it takes to watch the course intro.
The 30-second version: A Claude Agent Skill is a folder with one required file —SKILL.md. Write a two-field YAML header (name,description) and a Markdown body of instructions, drop it in.claude/skills/<name>/, and Claude loads it automatically when a task matches the description — or you run it with/<name>. The body costs zero tokens until it's used. That's the entire model.
Why a skill instead of pasting instructions#
You already have the thing a skill replaces: the block of instructions you keep re-pasting into chat, or the section of CLAUDE.md that quietly turned into a multi-step procedure. The difference is when it costs you. Everything in CLAUDE.md sits in context on every turn. A skill's body loads only when it's actually used — so a 300-line release checklist or a dense API reference costs almost nothing until the one moment you need it. That's the founder-relevant insight: skills are how you give the agent deep, specific know-how without paying for it on every unrelated request.
Step 1 — Make the folder#
A skill is a directory. The directory name becomes the command you'll type. Put it in your personal folder to use it across every project on your machine:
mkdir -p ~/.claude/skills/summarize-changesOr put it in a repo so your teammates — and cloud sessions and scheduled routines — get it too:
mkdir -p .claude/skills/summarize-changesThat location choice is the one decision that matters for reach; the table above lays out all four homes.
Step 2 — Write SKILL.md#
One file. Two required fields. A Markdown body. Save this to .../summarize-changes/SKILL.md:
---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
Summarize the current uncommitted changes:
1. Run `git status` and `git diff` to see what changed.
2. Group the changes by intent (feature, fix, refactor, docs).
3. Flag anything risky: deleted tests, secrets, large binary files,
or edits to migration/config files.
4. End with a one-line Conventional Commits message.
Keep it under 200 words. State what changed, not how git works.That's a working skill. Note two things doing the heavy lifting:
- The
descriptionis the whole game. Claude reads that one line to decide whether to load the skill. Vague descriptions ("helps with code") never trigger — Claude falls back to base knowledge. Name the exact task and the phrases a user would actually say. Explicit trigger phrases are the difference between a skill that fires and one that sits dead on disk. - Keep the body short. Once a skill loads, its content stays in context across the rest of the turn — every line is a recurring token cost. State what to do, not a narration of how or why.
Step 3 — Invoke it#
Two ways, and you want both to work:
# Let Claude decide — ask something that matches the description:
what changed in my working tree?
# Or invoke it directly by name:
/summarize-changesOpen a git project, make a small edit, start Claude Code with claude, and try both. If the direct call works but the automatic one doesn't, your description is too vague — go tighten it. Claude Code watches the skills directories live, so edits to SKILL.md take effect within the session without a restart.
The frontmatter that earns you control#
The two-field header gets you a skill. A handful of optional fields turn it into something you'd trust in production:
disable-model-invocation: true— Claude won't auto-load it; you run it manually with/name. Use this for anything with side effects: deploys, releases, anything you don't want fired on a guess. (As of recent versions it also stops a scheduled task from firing the skill unprompted.)allowed-tools: Read Grep— pre-approves those tools for the turn that invokes the skill, so a trusted read-only workflow runs without permission prompts. The grant clears on your next message.context: fork— runs the skill in its own subagent context, so a big, noisy task doesn't flood your main thread.model/effort— override the model or reasoning effort just while the skill is active.
Where it runs — the gotcha that bites founders#
A skill in ~/.claude/skills/ on your laptop is invisible to cloud sessions and routines, because each routine run starts as a fresh remote machine. If a scheduled task needs a skill, commit it to the repo's .claude/skills/ (or ship it in a repo-declared plugin). For the Claude web and desktop apps and Cowork, enable or upload the skill under Customize → Skills — the ZIP must contain the skill folder at its root, not a bare SKILL.md.
Skills follow the open Agent Skills standard, so the same folder is portable across Claude Code, the Claude apps, and any other tool that adopts it. If you want Claude to draft one for you, ask it to use its built-in skill-creator — describe the task in plain language and it packages the SKILL.md for you. But now you know what's inside the box, which is the part the courses take an hour to reach: it's a folder, a header, and a body — and the description is the switch. For a related build, see our take on inheriting an agent loop vs. owning the graph.
Once it works, keep it working#
Shipping the first version is the easy part; the trouble starts when you edit it. Because a skill is a prompt with no compiler, a bad change ships silently — so treat the skill like the production artifact it is. Two follow-ups close the loop: put it under version control and keep a one-minute rollback ready, and write a trigger eval that proves the skill still fires when it should — because the description you just tuned is the one line that decides whether Claude ever loads it, and it's the easiest thing to break without noticing.
