
Answer. To tune your Claude skill, test it on new input in a new chat, check the result against its Contract yourself, and write each miss in one line. Then have Claude turn each miss into an antipattern, a sharper rule, or a red flag in the skill, rerun every test, and save each version with a note.
Time and cost. About 30 minutes the first time. $0 to practice with the sample files on the free Claude plan. Who this is for. Anyone with a Claude skill that works most of the time and still misses now and then.
This is part 2 of 2. In Turn a good chat into a reusable skill we built a shift-handoff skill for Mesquite Ridge Metal Works (sample data, a made-up company) and tested it once on Tuesday's notes. Two checklist lines failed. Here we test it on one more set of notes, fix the skill (not the handoffs), and keep going until every test passes.
The rule for the whole guide is to fix the system, not the output (fix AI mistakes for good). If you correct a handoff by hand, tomorrow's handoff has the same mistake. If you change the skill, every handoff after it is right.

What will I learn besides tuning a skill?
You will learn five methods that work for any skill, prompt, or checklist you keep improving. Each one has a short "why" later in this guide.
- Check against the Contract yourself. The skill's own "every line passes" is not proof.
- Turn each miss into an antipattern or a rule. Every miss gets a home in the skill, so it does not come back.
- Fix the instructions, not the output. You never fix a handoff by hand.
- Rerun every test after every fix. A fix can break something that worked.
- Save each version with a note. You can always go back to the last version that passed.
What do I need before I start?
You need Claude, the skill from part 1, and two sets of test notes. You never open code: Claude changes the files, and you read and judge what changed.
- Claude at claude.ai, set up the way Set up Claude shows. The free plan works.
- Your
shift-handoff.zipfrom part 1, uploaded and turned on. If you skipped part 1, everything is in tune-starter-sample.zip (download and unzip sample files): my version 1 skill, both sets of notes, and both answer keys. - The test notes: shift-notes-2026-11-17-email.pdf (Tuesday, an email) and shift-notes-2026-11-18.docx (Wednesday, typed as paragraphs).
- The answer keys: checklist-2026-11-17.md and checklist-2026-11-18.md.
Safe use. Real shift notes can hold people's names, injuries, and customer orders. Check your company rules before you attach them to any AI tool, and practice with the sample notes first. Read the safe use notes.
How do I tune my Claude skill?
Test on new notes, write each miss in one line, have Claude turn the misses into antipatterns and rules, then upload the new version and rerun every test until all pass. There are seven steps.
Step 1. Get your skill and your misses from part 1
Check that shift-handoff is in your skills list with its switch on (Upload a Claude skill). Keep the two misses from part 1's Tuesday test where you can copy them. Mine were these:
- Quality holds said "Quality control looked at them" as a fact, but the notes say "i think."
- Press brake 2 showed up under both Safety and Machines.
Step 2. Test it on Wednesday's notes and check it yourself
Start a new chat, attach shift-notes-2026-11-18.docx, and type Write the shift handoff from these notes. Then check the handoff against the Wednesday checklist, one line at a time (how to test an AI tool).
Wednesday's notes are written as paragraphs, have no safety items, and never name the plant, so they test things Tuesday could not. My version 1 caught the 41 against 42 shaft count and flagged "RL-321 display," because the Monday example shows the display as RL-231. It failed three checklist lines, for two reasons:

- Section 6 said "Ray: give the ok on Cruz's and Jaylen's Saturday overtime requests by Thu." Every line there should start with "Owner:".
- Open questions asked which job the 2 rewelded frames belong to and what Kestrel was asked, which the shop already knows.
On Tuesday, the same version ended its reply with "I walked the validation checklist and every line passes," while two lines failed. The skill checking itself is a good habit, but you are the check that counts (make AI check its own work).
Step 3. Write each miss in one line
For each miss, write which test it was, what the handoff said, and what you wanted instead. Quote the bad line when you can, because Claude writes a better fix from the real words than from a description. Put the Tuesday misses from Step 1 in the same list.
Leave out small things that do not matter to the meeting. "Wire came in" sat under Machines on Wednesday, which is a placement I can live with, so it did not go on my list.
Step 4. Turn the misses into antipatterns and rules
Start a new chat, attach your shift-handoff.zip, and send the prompt below with your list in place of [ONE LINE PER MISS] and 2 in place of [NEXT NUMBER].
I attached shift-handoff.zip, my shift-handoff skill. I tested it on new notes in new chats, and it missed some things. Do not rewrite the handoffs. Fix the skill, so these misses do not happen again.
What I saw, and what I wanted instead:
[ONE LINE PER MISS]
For each miss:
1. Add an entry to knowledge/antipatterns.md: what it looked like (quote the bad line), why it is wrong, and what to do instead.
2. If the Contract does not already say what I want, add or sharpen one Contract line, and the matching yes/no line in validation/checklist.md.
3. If I could spot it on the page at a glance, add it to Red flags in SKILL.md. Keep 5 or fewer, so replace a weaker one.
4. If the template or the example breaks the new rule, fix that file too, because the skill copies them.
Keep SKILL.md under 80 lines and change nothing else. Put "version: [NEXT NUMBER]" at the top of SKILL.md, and add one line for this version to what-changed.md saying what changed (make the file, with a v1 line too, if it is not there yet). Then show me each change as old and new wording, and give me the new shift-handoff.zip.
These are the four lines I sent:
- Wednesday: section 6 said "Ray: give the ok on the Saturday overtime." Every section 6 line starts with "Owner:", so this should be "Owner: Ray."
- Wednesday: Open questions asked which job the 2 rewelded frames belong to and what Kestrel was asked. The shop knows both. Only ask what the morning meeting cannot answer from the notes or the floor.
- Tuesday: Quality holds said "Quality control looked at them" as a fact. The notes say "i think." Anything the notes are unsure about is written as unsure everywhere, not only under Open questions.
- Tuesday: Press brake 2 showed up under both Safety and Machines. Outside section 6, each item goes in one section only.
Each miss gets a home. Every miss becomes an entry in knowledge/antipatterns.md, which records what it looked like, why it is wrong, and what to do instead (turn each miss into an antipattern). A miss the Contract did not cover becomes a new Contract line plus a matching checklist line, and a miss you can spot at a glance becomes a red flag. Claude also fixed the template and the Monday example where they broke the new rules, because the skill copies them.

Step 5. Upload version 2 and rerun every test
Upload the new shift-handoff.zip in place of the old one, the way Upload a Claude skill shows, then rerun both the Tuesday and the Wednesday test, each in its own new chat. Rerun both, not only the one that failed, because a fix can break something that used to work (check what a fix changed).
To see what moved, save the old and new handoff for the same notes as two files, attach both to a new chat, and send this:
I attached two handoffs my shift-handoff skill wrote from the same shift notes: the one from before my last fix, and the one from after it. Do not rewrite either one, and do not say which is better.
List every difference between them in plain words, one line each, grouped by section. Put these two kinds first:
- Anything the old handoff had that the new one lost, such as a flag, a question, an owner, or a word in the title.
- Anything the new one added that is not in the notes.
Tuesday now passed every line. Wednesday fixed all three misses but broke two lines that version 1 had passed. The title said "Plant not stated," and the RL-321 question was gone. The fix had removed the Monday example's open question about RL-231, which seems to be what taught the skill to compare part numbers, and no rule said the title always says Plant 1, so version 1 had only gotten it right by luck.

Step 6. Fix what the fix broke, then test again
Send the same prompt from Step 4 in a new chat with the version 2 zip, 3 for the version, and the two new misses:
- Wednesday: the title said "Plant not stated." These notes always come from Plant 1, 2nd shift, so the title always says "Plant 1 Shift Handoff: 2nd shift".
- Wednesday: "RL-321 display" was copied as written, which is right, but it was not flagged. Version 1 flagged it. Our display is RL-231. When a part number does not match a part in shop-facts.md, keep it as written and add an open question. Add the RL-231 display to shop-facts.md.
Claude added antipatterns 8 and 9, two Contract lines, the RL-231 display as a standing shop fact, and a fixed title in the template. Upload version 3 and rerun both tests in new chats. With version 3, both handoffs passed every line of their checklists.
Step 7. Save each version with a note
Keep every zip, named by version: shift-handoff-v1.zip, shift-handoff-v2.zip, and shift-handoff-v3.zip. The skill keeps its own history in what-changed.md, one line per version, because the prompt asks for it. If a later change makes things worse, upload the last zip that passed and you are back in a minute (save every working version). My three versions are version 1, version 2, and version 3, the one to use.
What does good look like?
A tuned skill passes every line of every test, and each miss you found lives in the skill as an antipattern or a rule. Answer key, sample data. These are my results on the two checklists.
| Version | Tuesday checklist (10 lines) | Wednesday checklist (9 lines) | What changed |
|---|---|---|---|
| v1 | 8 pass. Failed 5 (unsure note as fact) and 9 (same item twice) | 6 pass. Failed 6 and 8 ("Ray:") and 7 (needless questions) | Built from the Monday chat |
| v2 | 10 pass | 7 pass. Failed 1 ("Plant not stated") and 5 (RL-321 not flagged) | Antipatterns 4 to 7, Contract lines 8 and 10 sharpened, 11 and 12 added |
| v3 | 10 pass | 9 pass | Antipatterns 8 and 9, Contract lines 13 and 14, RL-231 added to shop facts |
The finished knowledge/antipatterns.md has nine entries: the three corrections from the original chat and six from testing. You can read my version 3 antipatterns.
What can go wrong?
Most tuning problems come from trusting a test that cannot fail, or from fixing one thing and not checking the rest. These all showed up while I tuned this skill.
- A fix breaks something that worked. Version 2 fixed four misses and broke two lines on Wednesday. Rerun every test after every change.
- The skill says every line passes. It said so with a failing line in plain view. Check the checklist yourself.
- The example teaches the old way. When a rule changes, the example and the template can still show the old way, and the skill copies them. The prompt tells Claude to fix them too.
- A fact the skill needs only lived in the example. The RL-231 display was only in the Monday example, so when the example changed, the flag went away. Put standing facts in shop-facts.md.
- You describe the miss instead of quoting it. Claude then writes the antipattern from your description. Paste the bad line when you can.
- You chase every small thing. Not every placement needs a rule, and each rule makes the skill longer. Fix the misses that matter to the people who read the result.
How do I check the answer?
Check each version against every test, not only the one you just fixed.
- Every checklist line passes on every test notes file, checked by you, in a new chat.
- Every miss you listed is now an antipattern entry, a Contract line, or a red flag.
what-changed.mdhas one line for each version, and you kept every zip.- SKILL.md is still short (mine went from 45 to 50 lines), because the detail lives in the other files.
Why does this way work?
It works because every miss changes the skill instead of one handoff, and every change is tested against everything that already worked.
Check against the Contract yourself. The Contract turns "a good handoff" into yes-or-no lines, so two people checking the same handoff get the same answer (what a skill's contract is). The skill's own check is useful, but it missed a line in plain view, so the last check is yours (make AI check its own work).
Turn each miss into an antipattern or a rule. An antipattern is a written-down mistake with its fix, the way a shop keeps a list of known defects next to the inspection sheet. The skill reads that list every time, so a mistake you caught once stays caught (turn each miss into an antipattern).
Fix the instructions, not the output. People decide what good looks like, AI does the writing, and every miss goes back into the plan (people plan, AI does the work). A fixed rule makes every later handoff right, which a fixed handoff never does (fix AI mistakes for good).
Rerun every test after every fix. Rules touch each other, so a change in one place can move something you were not looking at. Rerunning both tests and comparing the before and after is how version 2's two breaks showed up in minutes (check what a fix changed). Small rounds with few changes make it clear which change did what (change one thing at a time).
Save each version with a note. Some changes make a skill worse, and a saved zip with a one-line note lets you go back in a minute instead of rebuilding from memory (save every working version).
Frequently asked questions
How many tests do I need?
Start with two or three real inputs that look different from each other, like an email and a Word file. Each time you find a new kind of miss in real use, save that input as a new test and rerun it with the rest.
When is the skill done?
When it passes every test you have, and a new week of real notes turns up nothing that matters. Keep using it and keep tuning, because new kinds of notes will show up.
Could a script do the checking?
Yes, for the parts that are fixed, like the title, the seven sections in order, and every section 6 line starting with "Owner:". A small script in the skill's scripts/ folder can check those the same way every time (what deterministic means). The judgment parts still need you.
What if a fix makes it worse?
Upload the last zip that passed. Then make a smaller change, one or two misses at a time, so you can tell which change caused the problem.
Can my team use the tuned skill?
Yes. Share the newest zip and agree on who owns changes, so everyone runs the same version. When someone finds a miss, it goes to the owner as one line, and the owner tunes and retests.
Take this with you
Two prompts and a finished version 3 skill.
1. Turn misses into antipatterns and rules. Attach the skill zip and list one line per miss.
I attached shift-handoff.zip, my shift-handoff skill. I tested it on new notes in new chats, and it missed some things. Do not rewrite the handoffs. Fix the skill, so these misses do not happen again.
What I saw, and what I wanted instead:
[ONE LINE PER MISS]
For each miss:
1. Add an entry to knowledge/antipatterns.md: what it looked like (quote the bad line), why it is wrong, and what to do instead.
2. If the Contract does not already say what I want, add or sharpen one Contract line, and the matching yes/no line in validation/checklist.md.
3. If I could spot it on the page at a glance, add it to Red flags in SKILL.md. Keep 5 or fewer, so replace a weaker one.
4. If the template or the example breaks the new rule, fix that file too, because the skill copies them.
Keep SKILL.md under 80 lines and change nothing else. Put "version: [NEXT NUMBER]" at the top of SKILL.md, and add one line for this version to what-changed.md saying what changed (make the file, with a v1 line too, if it is not there yet). Then show me each change as old and new wording, and give me the new shift-handoff.zip.
2. Check what a fix changed. Attach the before and after output for the same input.
I attached two handoffs my shift-handoff skill wrote from the same shift notes: the one from before my last fix, and the one from after it. Do not rewrite either one, and do not say which is better.
List every difference between them in plain words, one line each, grouped by section. Put these two kinds first:
- Anything the old handoff had that the new one lost, such as a flag, a question, an owner, or a word in the title.
- Anything the new one added that is not in the notes.
3. My tuned skill. Download shift-handoff.zip (version 3), or compare version 1, version 2, and version 3.
Every time your skill misses, write the miss in one line, turn it into an antipattern or a rule, rerun every test, and save the version.
What's next?
- Turn a good chat into a reusable skill, part 1: build the skill folder this guide tunes.
- Fix your quote report and keep every version safe, the same tuning habits for a skill that carries a script.
- Compare supplier quotes the same way every time, a buying job with two skills.
- Fix the instructions, not the output, the idea behind every step here.