How to turn a workflow you keep repeating into an AI skill that fires on its own

After the third time you’ve done it. Not the first.

Honestly this is the rule that matters most and it’s the one people skip. Write a skill after run one and you’re writing down a guess. Write it after run three and you’re writing down what went wrong twice and how you fixed it, which is the only part your assistant doesn’t already know.

Before you open the file, answer three questions about the work you just did. These are the questions that produce everything worth putting in a skill.

1. 01What surprised you? That’s the thing nobody would guess from first principles.
2. 02What did you try first that didn’t work? That’s a whole section, saved from being rediscovered.
3. 03What would you tell someone starting this tomorrow? That’s your opening paragraph.

If you can’t answer those, stop and go do the work again. A skill built without them is a summary of what the model already knows, and loading it changes nothing except your context bill.

Because your description says what the skill is instead of when to reach for it. This is the single most common failure, and it’s worth being blunt: a perfect skill that never triggers is worth exactly nothing.

Assistants undertrigger. Left to their own judgment they’ll answer from general knowledge rather than go load your file. So you write the description to push, and you write it in the words a real person would actually type.

---
name: proposal-builder
description: Guidance for writing client proposals.
---

---
name: proposal-builder
description: Build a client proposal from a discovery call, including
  scope, phased pricing, timeline, and the assumptions section that keeps
  scope from creeping. Use whenever someone mentions a proposal, quote,
  estimate, statement of work, SOW, bid, or "what would this cost," when
  turning discovery notes into something sendable, or when revising
  pricing on a proposal already out the door. Do not use for invoices
  or contracts.
---

Three things changed. It names the deliverable, it lists the phrases people actually use including the ugly informal ones, and it says where to stop. That last line matters more than it looks: a description with no boundary starts firing on everything nearby, and a skill that fires constantly is worse than one that never does.

Length is a real tradeoff, not a rule. Across the eleven skills in our library the descriptions run from 30 words up to 167, measured on 2026-08-12. The short ones cover work with obvious, unmistakable trigger words. The long ones cover work people ask for in twenty different ways, and every one of those ways had to be spelled out.

Under about 500 lines. Past that, you’re not writing a skill, you’re writing a manual, and the useful parts get buried in the parts that only matter sometimes.

The fix is to split. The body holds the decisions and the workflow. Separate files in the same folder hold the deep detail, and the body says explicitly when to go read each one.

Our heaviest skill is a good illustration of the shape. The body is 421 lines. Alongside it sit eight reference files holding 7,794 words that never enter a conversation unless the body sends the assistant to fetch one. That’s the point: all of it available, almost none of it loaded.

A reference file with no pointer to it is a file nobody reads. Every time you split something out, add a line in the body saying what it covers and when to open it.

Instructions, in the imperative. “Run the build before you screenshot,” not “it is often helpful to run the build.” Hedged prose reads as optional, and optional instructions get skipped.

Beyond that, four things earn their space and almost nothing else does.

1. 01The order. Which step comes first and why it can’t come second. Most of what makes an expert an expert is sequence, and sequence is invisible in a finished deliverable.
2. 02The thresholds. When to split a file, when to start over, when a thing is good enough to ship. Real numbers where you have them.
3. 03The failure list. The mistake you actually made, named plainly, with the correct move next to it. This is the highest-value paragraph in any skill.
4. 04The pre-flight check. A short list to run before declaring the job done, so “it applied cleanly” never gets confused with “it worked.”

Then cut everything the model already knows. If a paragraph would be true of any competent practitioner anywhere, delete it. You’re writing the delta between general competence and how this gets done well, and every sentence that isn’t the delta makes the delta harder to find.

Because you will reuse it, and the version welded to your first client won’t survive the second.

We learned this the boring way. Skills written around one brand’s colors, one client’s naming, one product’s quirks. The workflow inside them was genuinely good. The moment a second project needed the same workflow, every example had to be untangled by hand, and worse, one client’s details were sitting in a file that loads during another client’s work.

So genericize as you write, not later. Swap specific names for the role they play: “the brand’s accent color,” “the client’s booking tool,” “a dedicated testing skill.” Then audit before you save.

grep -rniE "acme|jane|northstar-crm|<your client>" ~/.claude/skills/proposal-builder/

One honest exception: keep the specifics that are intrinsically part of the subject. A skill about a particular deploy platform has to name that platform, and stripping it would break the skill. The test is whether the name is the domain or just the example you happened to have on hand.

Keep the real files in a folder you own, organized by what kind of work they are. Then symlink them into wherever your assistant looks. The assistant’s folder becomes a directory of pointers, and your library stays somewhere you can version it, back it up, and carry it to a new machine.

~/code/skills/
  content/     writing, editing, distribution
  dev/         building, testing, shipping
  research/    teardowns, competitive work
  meta/        skills about making skills

ln -s ~/code/skills/content/proposal-builder ~/.claude/skills/proposal-builder
ls -la ~/.claude/skills

You should see an arrow pointing back at your real folder. From then on you edit the file in your library, and every machine you’ve linked picks up the change with no copying and no drift between versions.

Three checks, in a fresh session each time. A session that already discussed the topic will fire the skill for reasons that have nothing to do with your description.

1. 01Does it fire? Type the request the way a real person would, in their words, not yours. If it doesn’t load, the description is the problem and nothing else is worth touching yet.
2. 02Does it stay quiet? Ask for something adjacent but different. A proposal skill should not wake up for an invoice. If it fires on everything, tighten the boundary line.
3. 03Does the output actually change? Run the real job and compare against what you got before the skill existed. If it loaded and nothing improved, your body is a description of the work rather than instructions for doing it.

That third check is the one people skip, and it’s the only one that tells you whether the hour was worth it.

When it does fire and the output does change, you’ve turned something you were carrying in your head into something that carries itself. That compounds. The tenth skill is easier than the first, and it sharpens every job the first nine touch.

One last thing worth knowing: a skill sets the standing instructions, but the request you type still decides what you get back. The two work together, and the fastest upgrade available to most people is still writing a better single prompt.

A skill doesn’t make your assistant capable of something it can’t do. It organizes and sharpens ability that’s already there. If the underlying task is beyond the model, a beautifully written skill produces a beautifully organized wrong answer.

One-off work isn’t worth a file. If you won’t do this again, just explain it in the conversation and move on. The rule of three exists in both directions.

Standing preferences aren’t skills either. “Never use em-dashes,” “always use our house font,” “deploy only when I say deploy”: those need to apply everywhere, always, so they belong in your project instructions or your assistant’s memory. A skill only helps when it’s loaded, which makes it exactly the wrong home for a rule that must never lapse.

And there is a real ceiling on how many you should keep. Every description sits in context on every request, whether or not it’s relevant. Eleven good skills cost little and pay for themselves. Forty mediocre ones make every conversation slightly worse and give the assistant forty near-misses to choose between. Prune the ones you stopped using.

Finally, the file format and folder locations here are current as of August 2026 and they’re specific to assistants that support skills. Check your tool’s current documentation before you build a library around it.