More detail: Turn the part that repeats into a reusable skill

This page goes with the Week 3 lesson Turn the part that repeats into a reusable skill (course/workforce/week3/lessons/anw-w3-l11.md). You don't need it to finish the lesson. Read it when you want the longer version.

The fresh job

Why it stays out of your design. Your team was built from your design, and its five test cases shaped every agent. A job written into the design, or shown to Gigawatt while it builds, stops being a fair test: the team may have been tuned to it. A fresh job is one the team has never seen, of a kind your design already covers.

Why you change nothing after it. The fresh job is run once, on the team exactly as it is. If you fix what it shows and run it again, it is no longer fresh. Keep what it shows as a finding. Week 4 grades from these notes.

How your Chief runs it. The same way as a test case: the plan first, your "Go.", each agent in turn in the Chief's thread, your questions gathered at the end, and the lead's summary. The job folder is new, like every run.

If it passed. A fresh job that passed can join your team's golden set: the five cases in your design plus every fresh job you approve, listed as golden: lines in your team's record. Say so in your Chief's thread; the Charter Steward adds the line on your yes, and from then on the suite runs that job too.

How Gigawatt finds the step

Gigawatt reads the job folders you point it at, read only. It looks at each agent's file in each run, and lines up the steps. It names a step only when it appears in every run, in the same place, and quotes each run's version side by side so you can see the drift for yourself.

Often the step is already in the agent's own instructions, or in a skill it has. The runs show it drifting anyway: the instructions say what to do, but not the exact form. A skill of its own fixes the form: the same headings, the same order, the same words for each result.

What a skill is, on disk

A skill is one folder with one file, SKILL.md. The file starts with the skill's name and one line that says when to use it, then the instructions. The same folder goes in three places, byte for byte, so both apps can read it:

• workforce/skills/<skill>/
• .claude/skills/<skill>/, for Claude Code
• .agents/skills/<skill>/, for Codex

The agent's own files list the skill: its capability profile (the file that says what the agent may use) and its two agent files, one for each app. Gigawatt changes those by rendering them again from the agent's instructions, never by hand.

What install writes

Gigawatt builds everything first in your team's job folder, under runs/<job>/setup/<agent>/, and runs the same check that gated your team's first install. Nothing moves until it prints RESULT PASS. Then it writes a list of exactly what install will write, bound to your approved design, with a number. Your yes must name that number. A plain "yes" isn't enough, so a yes can never land on a different change.

On your yes, Gigawatt checks the staged files once more. If any file changed after your yes, it copies nothing and names the file, and you say yes to the new number. Otherwise it copies:

• the skill, into the three skills folders
• the agent's capability profile and instructions, under workforce/profiles/
• the agent's files for both apps, in .claude/agents/ and .codex/agents/
• the registry, workforce/shed/registry.yaml, made again by its generator, never by hand
• the copy of the agent in your global agents folder, which Claude Code's @ list reads (in Codex, made the next time you ask Gigawatt in Claude Code)

Why your app asks again. Claude Code asks before any write into .claude/. Codex keeps .codex/ and .agents/ closed until you approve the write. Both check the same change you said yes to.

The two record checks

The drift check compares your charter, the registry and every agent's files. Drift: 0 findings means they agree.

The seat record check confirms that the registry, each agent's tools line and the roster page all match what each agent's capability profile and your connector record declare. 0 mismatch(es) means every record of every agent agrees.

Either check can name a problem. Each one comes with its fix, and Gigawatt applies a fix only on your yes.

A skill on a borrowed or reused agent

An agent's skills belong to the agent, not to one team, the same as its notes. A skill added to the Quality Reviewer (Kansa) or the Internal Knowledge Researcher (Hatch) becomes part of that agent in every department it works for.

What decides whether a team uses it is that team's record. Your Chief names in each order only the skills the team's record lists for that agent. So the skill joins your team when your record lists it, and another team's orders don't name it unless that team's record does too. Word the skill so it is right anywhere that agent might use it, or attach it to an agent that works only for this team, such as your lead.

Why the record changes too

Your team's record lists each agent's skills for this team. Your Chief reads the record before every job and copies those skills into each agent's order. That's how the agent knows to load the skill.

The Charter Steward replaces a team's record only on your yes to the exact new text. It files your yes as a ruling, quotes the earlier list of agents in it so the change is on file, and runs the team check. OK means the record is complete and points at your design.

Reading the before and after

Gigawatt starts new notes for the rerun and adds a table. Each item from the first run shows what the agent said then, what it says now (quoted, with the file), and whether the item is closed, changed or still open. For this lesson, look for three things:

1. The step follows the skill's form. Same headings, same order, same words.
2. Nothing else moved. If other parts changed, the skill did more than write the step down. Tell Gigawatt.
3. The order named the skill. The work order in the job folder lists it for that agent. If it doesn't, your record doesn't list it yet.

A step that didn't change is a finding, not a failure. Write down why you think it didn't, and take it to Gigawatt another day, one change at a time.

Running the neighbors after the skill

A skill is a change to the team, so your Chief runs the golden set again as one suite (run_suite), the refusal case three times, and reports one line. The skill is kept only if every golden case still passes. A skill that only writes a step down moves no other case; if one fails, the skill did more than that, and Gigawatt shows you what. The suite in full is in the details for "Run five cases and fix what breaks".