harness-audit
Skill0 starsChanged 4 days agoApache-2.0View on GitHub
Harness audit: diagnoses a project's agent harness and changes nothing. Validates HARNESS.md, finds drift between the design and the files built from it, and judges whether the design still fits the project. Use when invoked by name to review a harness; when agents keep missing a convention, bypass a check, or pile up permission prompts; or before hardening or thinning. Reports findings.
26 other projects use a version of this.
Adopted by
Most recently taken up by
- lumlaolao/spike-evaltheir own version, first seen Nov 16, 2026
- gutohuida/AgentWeavetheir own version, first seen Nov 15, 2026
- 5uck1ess/devkittheir own version, first seen Nov 15, 2026
- venhdev/skillstheir own version, first seen Nov 8, 2026
- DaeSeokSong/oh-my-ouroborostheir own version, first seen Nov 1, 2026
- AnastasiyaW/codex-claude-code-configtheir own version, first seen Oct 30, 2026
Used with
Projects with it also use project-init, autopilot and 3 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
u9401066Skillproject-init
Initialize new projects using this template. Triggers: init, new, 新專案, 初始化, create project, 建立專案, bootstrap, scaffold project.
Also in 3 projects that use this
ibahgatSkillautopilot
Run autonomous multi-stage execution loops until acceptance criteria pass or blockers are reached.
Also in 3 projects that use this
Microsoft AzureSkilltest
Also in 3 projects that use this
nicolasestremSkillbrainstorm
Structured idea generation and solution exploration with systematic analysis.
Also in 3 projects that use this
GoogleSkilltdd
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
Also in 3 projects that use this
Other versions26 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 26
- AnastasiyaW/claude-code-config★ 214same name
- AnastasiyaW/codex-claude-code-config★ 214same name
- Kanevry/session-orchestrator★ 53same name
- fabianmartinelli-fm/harness-audit★ 7same name
- fmslutions/harness-audit★ 7same name
- fernandopetry/keelson★ 5same name
- 5uck1ess/devkit★ 4same name
- gutohuida/AgentWeave★ 4same name
- DaeSeokSong/oh-my-ouroboros★ 2same name
- lumlaolao/spike-eval★ 2same name
16 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository27 other files it gives its agents.
- AGENTS.mdAGENTS.md
- github-project-workflowSkill
- human-writingSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- openspec-update-changeSkill
- plugin-developmentSkill
- authority-buildingSkill
- completion-buildingSkill
- entropy-buildingSkill
- environment-buildingSkill
- feedback-buildingSkill
- gates-buildingSkill
- harness-architectureSkill
- harness-buildSkill
- harness-designSkill
- harness-extractSkill
- harness-mdSkill
- knowledge-buildingSkill
- lightweight-spec-workflowSkill
- openspec-workflowSkill
- project-skill-buildingSkill
- spec-driven-developmentSkill
- spec-kit-workflowSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. 0 are common, 13 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 22 edited versions we read keep these.
13
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 27
Change nothing: No file is created, edited, or deleted, in the project or on the remote.
- Distinctive: line 34
When an artifact disagrees with what the design intends, the artifact is wrong, or the design has to change first.
- Distinctive: line 36
When the design names a fact the code states differently, the design is out of date.
- Distinctive: line 40
Run what is cheap and read-only (a recipe listing, a dry run).
- Distinctive: line 46
When the user keeps something a finding proposed to change, record their choice and reason on the finding.
- Distinctive: line 109
Read references/inventory.md before the first artifact.
- Distinctive: line 141
Ask the Context conditions the repository cannot show in one message before the first such layer, and only then.
- Distinctive: line 160
Read references/fitness.md before judging.
- Distinctive: line 166
Check whether Context itself is still true.
- Distinctive: line 167
Use the methodology manual skill for the defaults a Context calls for when it is installed.
- Distinctive: line 176
Read references/symptoms.md when step 1 recorded any symptom.
- Distinctive: line 223
Check how it loads before calling it unreachable.
- Distinctive: line 230
When the design and an artifact disagree, do not decide by which looks newer.
“Common” is measured: kept by at least 6 in 10 of the 22 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Harness Audit
A wrong or stale harness is worse than none:
an agent trusts it and builds on the lie.
This skill finds what is wrong with a project's harness and says what
to do about it, in three passes: the format of HARNESS.md,
the drift between that design and the files that implement it,
and the fit of the design to the project. It reads and reports.
Each layer is examined by the installed skill whose description claims
that layer.
Rules on every step
- Change nothing. No file is created, edited, or deleted, in the project or on the remote. A finding carries its fix as a proposal; an audit that edits a file has failed. Asked to fix something on the way, finish the report and name the workflow that makes the change.
- Two sources. Design intent comes from
HARNESS.md; facts come from the code. When an artifact disagrees with what the design intends, the artifact is wrong, or the design has to change first. When the design names a fact the code states differently, the design is out of date. Every finding says which side to change. - Evidence for every finding. A file and line, or the output of a command that was run. Run what is cheap and read-only (a recipe listing, a dry run); never run what writes, installs, or reaches a remote.
- A symptom is a lead, not the scope. A complaint is checked first and the three passes still run in full; the same stale fact is usually copied in two more places.
- A disposition the user gives binds. When the user keeps something a finding proposed to change, record their choice and reason on the finding; the closing proposal respects it.
- Route by role. A layer is examined by the installed skill
whose description contains
Owns the <Layer> layer. The report names no skill.
<!-- shared:format-in-brief -->The format in brief. A HARNESS.md is YAML frontmatter followed by a
Markdown body. Frontmatter: name and description are required;
version, license, and metadata are optional; any other top-level key
is an error. Body: free-form. It opens with one first-level heading, the title,
and an introduction with no heading of its own:
who the harness serves, what it is meant to achieve,
what it leaves unmanaged, and what always stays with a human.
The format requires no section. It recommends these second-level headings,
with exactly these English names and in this order: Context, Invariants,
Style, File Structure, Environment, Knowledge, Feedback, Gates, Authority,
Completion, Entropy, Open Questions, References.
A design of a complete harness usually covers Context and the five core
layers (Environment, Knowledge, Feedback, Gates, Authority);
a file that describes only part of a harness may leave out any of them.
The prose may
be in any language; the headings are never translated; other sections may
appear anywhere. For the full rules and the validator script, load the
skill that reads, writes, and validates HARNESS.md; without it, check
these rules by reading.
<!-- /shared:format-in-brief -->Workflow
1. Take the request and find what there is
Record any text after the invocation verbatim as symptoms or scope.
Then look for HARNESS.md in the project root and for harness artifacts:
an entrypoint, knowledge files, project skills, client settings and hooks,
pre-commit configuration, CI, a spec directory.
| Found | What this audit does |
HARNESS.md and artifacts | all three passes |
artifacts, no HARNESS.md | drift pass against the practice instead of a design (step 4), fitness pass, and a recommendation to extract the design |
HARNESS.md, no artifacts | format and fitness passes; the report says the design is not built yet |
| neither | report that there is nothing to audit and that the design workflow (harness-design) is where a harness starts; stop |
Done when: the symptoms are recorded and the row that applies is named.
2. Format pass
With the skill that reads, writes, and validates HARNESS.md installed,
run the validator script it ships and quote its output;
otherwise check the format rules above by reading.
Each error and warning becomes a finding in the group HARNESS.md.
Then read Context against the repository:
a Context that describes another project (another platform, another stack,
people the history does not show) is a high finding,
because every decision in the file rests on it.
Done when: the validator's result is quoted or the manual check is recorded as such.
3. Inventory
Read references/inventory.md before the first artifact. Record every harness artifact with its four facts; run the project's own harness self-check when one exists and quote its findings, adding by hand only what it does not cover; follow the entrypoint's pointers the way a new agent would, opening every path and checking every documented command against the task runner.
Done when: every artifact has its four facts, the self-check is quoted or its absence recorded, every entrypoint pointer was followed, and no file has changed.
4. Drift pass
For each layer in this order: Environment, Knowledge, Feedback, Gates,
Authority, Completion, Entropy.
Find the installed skill whose description contains Owns the <Layer> layer,
load it, and hand over in audit mode:
the Context, the layer's section, the parts of Invariants, Style,
and File Structure that concern it, and the inventory rows for the layer.
Take back its findings. When no installed skill claims the layer,
compare the section with the inventory yourself, sentence by sentence,
and record the gap.
- A layer with no section of its own is not thereby undecided: the format requires no section, so first look for the layer's subject in the introduction, in another section, or under a custom heading, and hand that text over as the layer's design.
- A core layer (Environment, Knowledge, Feedback, Gates,
Authority) the file says nothing about (there is no
HARNESS.md, or it is silent on the layer): the builder compares the project with its own defaults for the project's Context and marks each finding "no design to compare with". Ask the Context conditions the repository cannot show in one message before the first such layer, and only then. - Completion or Entropy that the file says nothing about is reported as left out by the design, with no finding, unless step 5 says the Context calls for it.
Then audit what no layer owns:
each invariant is upheld where it should be (stated in the entrypoint,
enforced by a check, or denied in the permission files);
each enforceable part of Style is in a tool's configuration;
each path File Structure requires exists;
nothing built routes ordinary tasks to HARNESS.md.
Classify every finding with the classes in references/inventory.md.
Done when: every layer was examined or recorded as having no builder, and every finding has a class, evidence, and the side to change.
5. Fitness pass
Read references/fitness.md before judging. For each layer, ask whether what the design says is right for the Context as it is today: too little where a wrong change is costly, agents are unattended, or many people rely on the conventions; too much where a constraint no longer catches anything. Check whether Context itself is still true. Use the methodology manual skill for the defaults a Context calls for when it is installed. A fitness finding always proposes amending the design, never an artifact.
Done when: every layer has a verdict (fits, too little, too much) with the Context sentence or the evidence behind it.
6. Trace the symptoms
Read references/symptoms.md when step 1 recorded any symptom. For each one: reproduce or locate it in the files, name the layer that could have stopped it most cheaply, link it to the findings that explain it, and propose the change to the design. A symptom nothing explains is reported as unexplained, with what was checked.
Done when: every recorded symptom is explained by named findings or reported as unexplained.
7. Report
Rework assets/audit-report.md into the report and show it in the conversation; write it to a file only when the user names a path. Findings are grouped by layer, most severe first. Each has:
- severity:
high(a safety boundary or an always-on rule is missing or contradicted),medium(the design and the project disagree so that a task could go wrong),low(wording or tidiness only); - class, from references/inventory.md;
- evidence:
path:line, or the command and its output; - design: the sentence of the section, quoted, or "no design to compare with";
- fix: change the artifact, or amend the design, and the change in one line.
Take the user's dispositions on the findings and record them. Then propose the next step, one of:
- findings that only change artifacts: the build workflow (
harness-build) brings the harness back to the design as it stands; - findings that amend the design:
the design workflow revises
HARNESS.mdfrom this report, then the build workflow applies it; - no
HARNESS.md: the extract workflow (harness-extract) writes down the design the harness implies, then the design workflow repairs it; - nothing found: say so, and list what was checked.
Done when: the report holds every finding in the format above,
every symptom's explanation, one proposed next step,
and git status shows that nothing changed.
Gotchas
- A file nothing links to may still load: client settings, hooks, and subdirectory entrypoints load by location. Check how it loads before calling it unreachable.
- "Nobody remembers why it exists" is not evidence that a constraint is dead weight. Without evidence that what it caught no longer occurs, the finding is a question for the user.
- A finding against a public file (README, CONTRIBUTING, SECURITY) is a suggested edit for a person; those files are not harness artifacts.
- When the design and an artifact disagree, do not decide by which looks newer. Intent is the design's; the fix names the side and the user may overrule it.
- A check that passes is not a check that runs. Confirm that a hook is installed and that CI actually invokes the recipe before recording a gate as present.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

