Last month I asked an agent for a research document. The request was one line: "Prepare a feasibility document for an on-demand transit service."
What came back was a readable essay of about three thousand words. It had no budget range, no options for who would operate the service, and no criteria for deciding when to withdraw. It was a good blog post, not something you could bring into a decision meeting.
The agent had not been lazy. I had asked only for the finished text and said nothing about the process that leads to it.
The first thing I want to say is this: stop asking the agent for an answer, and hand it a process. That is how I understand "harness engineering." Here I place that idea in Antigravity Skills and then check, with a script, whether the agent actually finished.
Why agents fail to ship projects
Human work runs a loop we rarely notice.
| Stage | What people do without thinking |
|---|---|
| 1 | Research and collect information |
| 2 | Structure the information |
| 3 | Decide who owns what |
| 4 | Each owner writes their part |
| 5 | Review and flag problems |
| 6 | Revise according to the review |
A request like "summarize X" asks for stage 4 only. The other five stages were never requested, so they do not happen.
A harness spells out all six as instructions and makes each stage leave a file behind. With files, the next stage can read the previous output, and I can inspect the middle of the run.
Where to put it: Skills
I used to keep templates like this in Workflows. Workflows are deprecated and will be retired on November 1, 2026, so new templates belong in Skills.
- Workspace:
.agents/skills/<name>/SKILL.md - Global:
~/.gemini/config/skills/<name>/SKILL.md
A Skill is a folder, so the check script described below can sit next to the template. At the start of a conversation only the name and description are read; the body loads when needed. Unlike Rules, whose full text is carried every turn, a long process sheet does not become a constant cost. For the differences, see Rules vs Skills placement, and for the pre-retirement inventory, inventory before migrating.
The six-step harness template
This goes in .agents/skills/project-harness/SKILL.md. Invoke it with /project-harness, or let the agent pick it up from the description.
---
name: project-harness
description: Runs a project in stages (research, design, writing, review, revision) and produces a set of documents under docs/. Use when asked for a multi-document plan, research brief, or adoption proposal.
---
# Project Harness
Save every stage's output as a file and read it as input to the next stage.
Do not skip stages. When switching roles, declare that the previous role is finished.
## Input
- Project name / subject / intended readers / deadline (read from the request; ask if missing)
## Step 1: Research
- Collect at least 6 cases from Japan and abroad. For each: operator, technical setup, cost structure, success factors, challenges
- Output: `docs/01-research.md`
## Step 2: Architect
- Read 01 and design the document set (purpose, readers, rough length)
- Output: `README.md` and `docs/_outline.md`. Do not write the documents yet
## Step 3: Business
- Market size, competitors, revenue model, local regulation and business customs
- Output: `docs/02-business.md`
## Step 4: Engineer
- Compare the technical setups, recommend a stack, estimate staffing, schedule and running cost
- Output: `docs/03-engineering.md`
## Step 5: Reviewer
- Read all documents together. Flag reader-level mismatch, missing assumptions, inconsistent terms, missed risks
- Write open items as `- [ ]` and resolved items as `- [x]`
- Output: `docs/99-review.md`
## Step 6: Revision
- Apply the review to each document and flip handled items to `- [x]`
- Finally run `bash .agents/skills/project-harness/check-harness.sh .`; if anything fails, fix it and run again
## Finish line
- At least 4 numbered documents under `docs/`
- README.md links to every document
- `docs/99-review.md` contains zero `- [ ]`What matters is that every Step names its output file. Without that, agents tend to pour everything into one giant Markdown file.
Let a script state the finish line
One thing became clear once the template was in place: if the finish line is only prose, the agent can simply report "done."
So I let a machine check it instead. This check-harness.sh sits beside the Skill.
#!/usr/bin/env bash
# Mechanically check the finish line. Argument: project root
root="${1:-.}"; fail=0
docs=$(find "$root/docs" -maxdepth 1 -name '[0-9]*.md' | wc -l)
[ "$docs" -ge 4 ] && echo "OK ${docs} numbered docs under docs/" || { echo "NG only ${docs} numbered docs (need 4+)"; fail=1; }
for f in "$root"/docs/[0-9]*.md; do
b=$(basename "$f")
grep -q "$b" "$root/README.md" || { echo "NG README.md does not link to ${b}"; fail=1; }
done
open=$(grep -c '^- \[ \]' "$root/docs/99-review.md" 2>/dev/null)
[ "${open:-0}" -eq 0 ] && echo "OK 0 unresolved review items" || { echo "NG ${open} unresolved review items"; fail=1; }
exit $failI ran it on a small scratch directory with deliberate gaps: five documents, README links to only three, and two unresolved review items.
$ ./check-harness.sh .
OK 5 numbered docs under docs/
NG README.md does not link to 04-risk.md
NG README.md does not link to 99-review.md
NG 2 unresolved review items
exit=1After resolving the items and adding the 04-risk.md link, the second run still failed:
$ ./check-harness.sh .
OK 5 numbered docs under docs/
NG README.md does not link to 99-review.md
OK 0 unresolved review items
exit=1The review file counts as a numbered document too, and I had not linked it from the README. I was the one who overlooked it. After adding the link, the third run passed with exit=0.
That small miss shows why the script earns its place. "README links to every document" is a sentence that both the agent and I can feel we satisfy just by reading it. An exit code does not allow that.
Because Step 6 says "run the check and fix what fails," the agent decides whether it has finished by the exit code, not by its own words.
Declare the end of a role when switching
When five roles share one conversation, make the switch explicit.
## Role switch: Research → Architect
Work as Research ends here.
As Architect, read `docs/01-research.md` and design only the document structure.
Do not write the documents. The output is `docs/_outline.md`.If you only say "go to the next step," a structure-design stage can come back looking like more research. Saying once that the previous role is done, and what the next role reads and must not write, makes the boundary clear.
I am not claiming this is a tag the model treats specially. It is plain natural language, but it gives the reader, human or model, a visible seam between stages.
Add and remove roles per project
A harness is less a fixed template than a frame in which you swap the specialists you need. For example:
| Project | Role to add | Why |
|---|---|---|
| Adoption study for a municipality | Business (finances, subsidies) | Budget and withdrawal criteria drive the decision |
| New feature plan for an app | UX Designer (flows, error states) | Experience quality decides output quality |
| Company-wide AI adoption plan | Policy (usage rules) and Reviewer (labor, legal) | Prohibited uses and consistency with existing rules are the issues |
The more concrete a role name is, the better it holds. "A researcher of local-government transit policy" keeps its footing across a switch better than "Planning Agent."
When it does not work: check in this order
- Is there a finish line? Without one, the agent is satisfied with its first draft and never loops back through review.
- Can a machine check it? Words like "adequate" or "appropriate" cannot be judged.
- Are the role names concrete?
- Is any single Step overloaded? Beyond five to seven items, something tends to get dropped.
- Is there a role-switch declaration?
Entrust the judgment of "finished" to an exit code, not to the agent's words. That is the line that stayed with me from this round.
Applying it to your own work
Copying the template as it is rarely helps, because the work is in putting your own implicit process into words.
Pick one recent job where AI left you unsatisfied. If a person did it, what would they research first, whose expertise would they borrow, who would check it, and what would make it done? Those answers are the skeleton of your own harness.
As a first step, create one empty SKILL.md under .agents/skills/ and write just three lines of finish line that a script could judge. Once you have those three lines, I feel the harness is already half built.