◉ANTIGRAVITY LABJP
Articles/Agents & Manager
◈ Agents & Manager/2026-04-22Advanced

Harness Engineering for Antigravity

How to get an agent past answering single questions and actually finish a project: a six-step harness, where to place it as a Skill, how to write role switches, and a script that checks the finish line mechanically, with real output.

antigravity476agents150harness-engineeringprompt-design3agent-architecture

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.

StageWhat people do without thinking
1Research and collect information
2Structure the information
3Decide who owns what
4Each owner writes their part
5Review and flag problems
6Revise 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 $fail

I 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=1

After 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=1

The 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:

ProjectRole to addWhy
Adoption study for a municipalityBusiness (finances, subsidies)Budget and withdrawal criteria drive the decision
New feature plan for an appUX Designer (flows, error states)Experience quality decides output quality
Company-wide AI adoption planPolicy (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

  1. Is there a finish line? Without one, the agent is satisfied with its first draft and never loops back through review.
  2. Can a machine check it? Words like "adequate" or "appropriate" cannot be judged.
  3. Are the role names concrete?
  4. Is any single Step overloaded? Beyond five to seven items, something tends to get dropped.
  5. 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.

Share

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.

  • ✦Copy-paste ready implementation code
  • ✦New advanced guides published daily
  • ✦$5/mo or $10 for lifetime access
View Membership →

If you found this article helpful, a small tip ($1.50) would mean a lot to us. Your support helps keep this site ad-free and covers server and hosting costs.

Related Articles

◈ Agents & Manager2026-10-13
Turning Gut-Feeling Judgments into Rules an Agent Can Actually Follow
A repeatable way to turn the judgment calls that live only in your head into rules an Antigravity agent can apply: build conditions from past cases, choose where in .agents/rules they live and which trigger to use, catch rules that are silently ignored, and replay old cases before trusting them.
◈ Agents & Manager2026-09-04
Snapshot Your Agents' Effective Scope So You Notice the Day a Default Changes
Antigravity 1.1.25 made Markdown-defined custom agents inherit the surrounding skills, rules, and subagents by default. Here is the snapshot-and-diff routine I now use to check whether an agent I meant to keep narrow quietly got wider after an update.
◈ Agents & Manager2026-08-21
Why I Check Description Overlap Before Turning On inheritCustomizations
CLI 1.1.14 collapsed markdown agent inheritance into a single inheritCustomizations switch. Here is what happened when I actually inventoried the 47 skills in my workspace and decided the switch on description overlap rather than on context size.