Build a Claude Skill Three Ways: Write It, Capture It, or Install It

Anthropic's docs put a price tag on each half of a skill, and the numbers should change how you build one. The metadata — name plus description — is loaded into the system prompt at startup and costs roughly 100 tokens per skill. The body costs nothing until the skill triggers, and under 5k tokens when it does. Install fifty skills and you pay for fifty descriptions, not fifty procedures.

So the instructions are the cheap, easy half. The expensive half is one field. That's the lens for choosing between the three ways to build a skill: they all end in the same file, but they are not equally good at producing a description that matches how you actually ask for the work.

The file, first

Every path converges on this shape. Minimal, valid, and portable across Claude Code, claude.ai and the API:

---
name: writing-status-updates
description: Turns a week of commits, tickets and threads into the async written update a distributed team reads. Use when the user asks for a weekly update, a status write-up, or what to tell their manager.
---

## Steps
1. Gather the raw material: `git log --author=me --since='7 days ago'`, tickets closed, decisions made.
2. Write three sections — Shipped, Blocked, Next. Three bullets each, maximum.
3. Every bullet names an outcome, not an activity: "checkout p95 down to 180ms", never "worked on checkout performance".
4. For each blocker, state the decision that unblocks it and propose a default.

## Rules
- No adjectives, no "great progress".
- A bullet with no number and no name in it is not finished. Rewrite it.
- 150 words total, hard cap.

Save it to ~/.claude/skills/writing-status-updates/SKILL.md (yours, in every project) or .claude/skills/… (this repo only, and it goes in git). The directory name becomes the command you type, so that file gives you /writing-status-updates. Claude Code watches those directories, so a new skill is live within the same session — no restart.

Three limits to know before naming it: name is capped at 64 characters and accepts only lowercase, digits and hyphens; "claude" and "anthropic" are reserved words, so claude-status-updates is rejected outright. description caps at 1,024 characters. And in Claude Code, description plus the optional when_to_use field get truncated at 1,536 characters combined in the skill listing, so front-load the trigger.

Path 1 — Write it by hand

Use when the procedure already exists in prose somewhere: a runbook, a CONTRIBUTING section, a checklist in your notes. You're not authoring knowledge, you're relocating it into a file Claude loads on its own.

Cheapest path, and the one where you control the description word by word. The docs are strict about one thing: write it in third person, because it lands inside the system prompt. "Generates commit messages by analyzing git diffs" works; "I can help you write commit messages" causes discovery problems.

Path 2 — Do the work once, then have Claude capture it

Use when the procedure lives in your hands and nowhere else — you can do the job but you'd forget half the judgment calls if you sat down to write them out.

This is the path Anthropic's own authoring guide recommends, and it's a loop, not a prompt: work through a real task with normal prompting, notice the context you keep re-supplying, then ask Claude to turn that into a skill. The docs are explicit that no special setup is needed — Claude understands the skill format natively, so "write this up as a skill" is enough. Then two steps people skip: strip out the explanations Claude added for things it already knows, and test with a fresh instance that has the skill loaded and none of your conversation.

Same path, different input: you can hand it an existing document instead of a session. That deserves its own guide.

Why this path wins the field that matters: the triggers in the resulting description come from sentences you actually typed, not from the ones you imagined typing at authoring time.

Path 3 — Install someone else's

Use when the job is generic and well-trodden — formatting, conversion, a standard review pass. Someone has already tuned it, and a good skill for a universal task transfers cleanly.

Two distribution mechanics matter here. Commit it to the repo's .claude/skills/ and every teammate inherits it on clone. Ship it in a plugin and it's namespaced plugin-name:skill-name, so it can't collide with anything. Precedence runs enterprise → personal → project, and a skill at any level overrides a bundled one with the same name — drop a code-review skill in your project and it replaces Claude Code's built-in /code-review.

The cost is context. A stranger's skill knows nothing about your stack, your clients, or the exception you make for one legacy service. And audit it before you trust it: Anthropic's guidance is to treat a skill like installing software, since a project skill's allowed-tools can hand Claude tools without prompting you once you've trusted the workspace.

Two things that bite after it works

Keep the body under 500 lines — that's the docs' number, and past it you should be splitting reference material into sibling files the skill links to, one level deep. Second: once a skill is invoked, its rendered content stays in the conversation for the rest of the session, and Claude Code doesn't re-read the file on later turns. So write standing rules that hold for the whole task, not one-shot steps that only make sense at the moment of invocation.

The EM angle

For a Brazilian dev working with a distributed US or EU team, a committed .claude/skills/ folder is leverage that shows up in review. It's how your team's standard for a status update, a migration, or a PR description stops being tribal knowledge you had to be in the right timezone to absorb.

Today: take the last task you did well with Claude, run Path 2 on it — ask for a skill built from that session — then rewrite only the description, in third person, using the exact phrase you'd type to ask for it again. Fire it once with that phrase to confirm it triggers.

Sources

• Claude Code docs — Extend Claude with skills
• Claude Docs — Agent Skills overview
• Claude Docs — Skill authoring best practices