Every product team has at least one workflow that only works when a specific person runs it. The weekly release note that reads well because the same PM has written forty of them. The competitor teardown that follows an unwritten shape. The bug triage pass that applies rules nobody has ever typed out. Hand any of those to a new hire — or paste the request into a chat window — and you get back something that looks close and is subtly wrong in the places that matter.
Claude Skills are a way to write that tacit process down in a form both people and the model can execute. A skill is a folder containing a SKILL.md file. The YAML frontmatter carries a name and a one-line description; the body carries the instructions. Claude keeps only the name and description in context by default, and loads the full body when an incoming request looks like a match. That progressive loading is the whole design point: you can have a dozen skills installed without paying context cost for a dozen prompts on every turn.
What goes in a skill, and what stays out
The minimum viable skill is one file:
.claude/skills/release-notes/
SKILL.md
With frontmatter that looks like this:
---
name: release-notes
description: "Draft the weekly customer-facing release note from merged PRs. Use when someone asks for release notes, changelog copy, or a summary of what shipped this week."
---
The description is not documentation. It is the routing signal — the only text the model sees before deciding whether to open your skill at all. Write it for the dispatcher, not for a human browsing a folder. Name the artifact, and name the phrases a teammate would actually type. A description like Helps with release communications will lose every routing contest against a skill that spells out its triggers.
The body is where the process goes, and the useful structure is narrower than most first drafts. Four things earn their place: the ordered steps, the constraints, the negative rules, and one complete worked example. The negative rules matter more than teams expect. If your last three release notes got sent back because they led with internal refactor work, write that down as a prohibition. Positive instructions describe the target; negative rules encode the specific ways your team has already missed it.
A long SKILL.md defeats the mechanism. Once the body runs past a few hundred lines, you are back to a monolithic prompt that eats context every time it loads. Split it: keep the procedure in SKILL.md and push long reference material — tone guides, taxonomy tables, past examples — into sibling files that the skill tells Claude to read when a given step needs them.
That sibling-file pattern is also how you attach determinism. A skill folder can hold scripts, and the instructions can tell Claude to run one rather than reconstruct its logic in prose. If step one is always the same API call, ship it as a script. Prose is for judgment; code is for the parts that must not vary.
Packaging a workflow the whole team can run
The extraction process that works is uncomfortably manual, and it is worth doing properly once.
Sit with the person who owns the workflow and have them run it end to end while narrating. Do not ask them to describe it from memory — you will get the idealized version. Watch what they actually open, what they skip, and where they pause to make a call. The pauses are the interesting part; those are the decision points that need explicit rules.
Write the steps as imperatives, in order. Then go back through the last handful of real outputs and ask what went wrong with each. Every correction becomes a constraint. Finally, paste in one full example — real input, real finished output. A single concrete example does more for output shape than three paragraphs describing the desired tone.
Distribution is the step that turns a personal trick into a team asset. Claude Code reads skills from two locations: ~/.claude/skills/ for personal ones, and .claude/skills/ inside a project. Put team workflows in the project directory and commit them. Now the skill is in version control, changes arrive as pull requests, and someone reviews them. A skill that lives on one laptop has the same bus factor as the tacit process it replaced.
Worth packaging versus not:
| Workflow trait | Package it? |
|---|---|
| Run weekly or more, same shape each time | Yes |
| Output format matters more than novelty | Yes |
| Corrections are repetitive and predictable | Yes |
| Run once a quarter, context changes every time | No — just prompt it |
| The process itself is still being argued about | No — settle it first |
Skills also need somewhere stable to point. Most product workflows depend on context that lives outside the repo: positioning docs, ICP notes, the pricing rationale, last quarter's research. If that material is scattered across DMs and someone's desktop, your skill will keep asking for it. Consolidating it into one searchable workspace is the unglamorous prerequisite.
Where skills break down
They do not fix a bad process. A skill is a faithful replica of whatever you wrote into it, executed at higher volume. If your triage rules are inconsistent, you now generate inconsistent triage faster and with more confidence attached. Extraction is a good forcing function precisely because writing the steps down surfaces the disagreements — but you have to actually resolve them rather than papering over them with vague language.
Invocation is probabilistic, not guaranteed. The model decides whether a request matches your description. Overlapping skills compete: if you have both release-notes and changelog-entry with similar descriptions, expect the wrong one to fire sometimes. Keep descriptions disjoint, and if a step absolutely must run every time, enforce it outside the skill — in a script, a hook, or a checklist in your PR template.
Drift is the quiet failure. Skills reference tools, file paths, and doc locations, and all of those move. A skill whose step three points at a deprecated internal endpoint will keep confidently producing broken output. Treat each skill like code: one named owner, and a review whenever the underlying process changes.
Start with exactly one skill, chosen for frequency rather than importance. The workflow you run every Monday will surface its own gaps within two weeks, and you will learn more about what belongs in a SKILL.md from that feedback than from planning a library of ten up front.
The honest framing: skills are a documentation format that happens to be executable. The value comes from the writing-down, and the model just makes the writing-down pay off more than a wiki page ever did. Teams that already keep good runbooks will find this a short step. Teams whose processes live entirely in people's heads will find that the hard part was never the tooling.
Originally published at pickuma.com. Subscribe to the RSS or follow @pickuma.bsky.social for new reviews.
Top comments (0)