Start

Home / Big ideas

Idea6-min read+5 pts

Turn Misses Into Antipatterns: How a Skill Stops Repeating a Mistake

With Josh Schultz ·

Answer. To turn a miss into an antipattern, you write one entry in the skill's mistakes file with three lines: what the mistake looked like, why it is wrong, and what to do instead. An antipattern is a written-down mistake with its fix. The skill reads that file every time, so you fix the skill once instead of correcting each result by hand.

The picture

Diagram: a handoff with one line circled, "Quality control looked at them." An arrow leads to a page labeled antipatterns.md with three lines: looked like, why it is wrong, instead. A second arrow leads to a stack of later handoffs, each marked with a check.

On the left is a result with one bad line, and the bad line is circled. Instead of fixing that line and moving on, you write it into the antipatterns page in the middle, with the mistake, the reason, and the right way to do it. On the right are all the handoffs the skill will write later, and each one is made with that page open, so each one avoids the mistake.

Think of it like this

Next to an inspection sheet, a good shop keeps a list of known defects. When an inspector finds a burr on a part, they do not only deburr that one part and hand it on. They write the defect on the list, with what it looks like and what to do about it, so the next shift watches for it and the cause gets fixed.

The list works because it is written once and read by everyone, and it does not depend on anyone's memory.

An antipattern file is that list for a skill. The skill opens it before it starts, the way an inspector looks at the defect list before the first part, so a mistake you caught once stays caught.

Why does it matter at work?

If you fix a bad result by hand, tomorrow's result can make the same mistake, because nothing in the skill changed. If you fix the skill, every result after it comes out right (fix AI mistakes for good). This is the idea that people plan and AI does the work, so the fix goes into the plan (humans plan, AI does the work).

Here is how it looked at Mesquite Ridge Metal Works (a made-up company in our sample data). Their shift handoff skill turns 2nd shift's rough notes into the handoff 1st shift reads at 6 am. On Tuesday's test, the Quality holds line said "Quality control looked at them." The notes said "i think," so the skill had turned a guess into a fact, and 1st shift might act on it.

You could correct that one line in 30 seconds. The better move, which the tuning guide takes, is to write the miss as one line, hand it to Claude, and have it become an entry in the skill. By the end of that guide, the antipatterns file had nine entries: three from the original chat and six from testing.

How does it work?

The method has four parts. You write the miss, give it a home, make the entry in three lines, and let the skill read it.

Write the miss in one line, and quote the bad line. Say which test it came from, what the result said, and what you wanted instead. Claude writes a better fix from the real words than from your summary of them.

Give each miss a home. An antipattern entry is the usual home. A miss the contract did not cover also becomes a new contract line with a matching checklist line, and a miss you can spot at a glance can become a red flag. If the template or the example showed the old way, those get fixed too, because the skill copies them.

Keep each entry to three lines. Looked like is the bad line, quoted. Why it is wrong says what it costs the reader. Instead says what to do, with a real example, and it gives one answer, so the skill does the same thing each time.

The skill reads the file on every run. In the sample skill, the third step says "Open knowledge/antipatterns.md and note which mistakes apply," so the file is read before the handoff is written (SKILL.md is a router).

Diagram: one miss on the left sends arrows to four homes: antipatterns, contract and checklist, red flags, and template and example. A note says "one miss, one or more homes."

Afterward, you test again, because a new entry can change other results (check what a fix changed).

Where do people get it wrong?

Most mistakes come from fixing the result instead of the skill, or from writing entries that are too thin to help. These are the four I would watch for.

  1. Fixing the result by hand. The handoff looks right today, and the skill makes the same mistake tomorrow.
  2. Describing the miss instead of quoting it. "It got the Quality line wrong" gives Claude nothing to work from, while the exact bad line does.
  3. An entry with no "Instead." Saying only what is wrong leaves the skill to guess the fix, and it may guess differently each time.
  4. A rule for every small thing. Each entry makes the skill longer to read. In the guide, "Wire came in" sat under Machines, which was a placement the author could live with, so it never became an entry.

Try this in 2 minutes

This test asks Claude to turn one real miss into one antipattern entry. You can use any chat tool.

  1. Open a new chat and paste this:
My shift handoff skill made this mistake. The notes said "I think quality control looked at them," and the handoff said under Quality holds: "Quality control looked at them." That turned a guess into a fact.

Write one entry for the skill's antipatterns file, with exactly three lines: Looked like, Why it is wrong, and Instead. Quote the bad line in Looked like. Keep it short.
  1. Read the three lines. Did Looked like quote the bad line, did Why it is wrong say what it costs, and did Instead say one clear thing to do?
  2. Swap in a miss from your own work, and try it again.

A chat reply with three lines. Looked like quotes the notes and the bad handoff line. Why it is wrong says the hedge was dropped so a guess read as fact. Instead says to carry the uncertainty forward. The Instead line is circled.

When I tried this, Claude wrote the three lines. Looked like quoted both sides: "Notes said 'I think quality control looked at them,' and the handoff stated under Quality holds: 'Quality control looked at them.'" Why it is wrong said "It dropped the hedge, so a guess read as a confirmed fact, and the next shift may skip checking items that were never verified."

The Instead line gave two answers: "Carry the uncertainty forward ('Quality control may have looked at them, unconfirmed') or flag it as something to verify." A skill given two options may pick a different one each time, so this is the line I would tighten. In the guide's version of this entry, Instead says to keep the doubt wherever the item appears, and that single answer is what makes the fix repeatable.

Frequently asked questions

What is an antipattern?

It is a mistake that looks reasonable but keeps causing trouble, written down with its fix. In a skill, it is one entry in the mistakes file, with what it looked like, why it is wrong, and what to do instead.

Does the skill really read the file every time?

It reads it when a step tells it to. In the sample skill, the third step says to open the antipatterns file before writing, so it is read on every run.

How many antipatterns should a skill have?

Only as many as real misses. The sample skill ended with nine after three tests, and each one came from something that actually went wrong.

Should every miss become an antipattern?

No. Fix the misses that matter to the people who read the result. A small thing you can live with does not need an entry, because each entry makes the skill longer.

Use it today

From my training: the antipatterns file is part of the skill template we use for client work, so every skill starts with a place to write down what went wrong.

Ideas are worth 5 points. Guides are worth 10 and up.

Get your first win this week.

One minute. Three guides picked for your job.

Start my first win