⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
harness-audit
Audits and restructures a project's AI agent harness (CLAUDE.md, AGENTS.md, GEMINI.md, rules, skills, hooks, docs and Obsidian vault notes) so an agent starts each session with a short map and finds the rest on demand, then installs the guardrails that keep it that way. Expect the win in speed, consistency and blast radius rather than in tokens. Run manually with /harness-audit diagnose | apply | verify | check. Supports Claude Code, Codex, Cursor and Antigravity CLI, with or without Obsidian.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
harness-audit
Cut what your coding agent loads before you type, and point it straight at what it needs.
harness-audit is an Agent Skill that audits the harness of a software project (CLAUDE.md, AGENTS.md, GEMINI.md, rules, skills, hooks, docs and Obsidian notes), restructures it so agents start every session with a short map, measures the result, and installs guardrails so the project does not drift back into a mess.
It works with Claude Code, Codex, Cursor and Antigravity CLI (the successor of Gemini CLI), with or without an Obsidian vault.
What it did on real repos
Session start, read from /context in a fresh session:
| Repo | Before | After |
|---|---|---|
| Large Next.js product repo | 555.8k tokens, 56% of a 1M window | 73.6k, 7% |
| Hospitality SaaS repo | 347.2k, 35% | 70.5k, 7% |
The finding that paid for the first audit was not size, it was silence. AGENTS.md had reached 349 KB against Codex's 32 KB read cap (project_doc_max_bytes), so the agent was receiving roughly the first tenth of it. No error, no warning, nothing in any log. On the second repo the same cap cut the file at 19.1%, mid-sentence, and CLAUDE.md had grown to 603,471 bytes, which meant nothing with a 200k window could open the project at all.
The honest ceiling: task success was 8/8 before the audit and 8/8 after. This does not make an agent smarter and never will. What moved was time (40 min to 7 across four tasks), operator interventions (2 to 0) and side effects (6 to 0).
The three pilots are written up as open issues, including a third one where the after-benchmark turned out to be invalid, and why.
Contents
- The problem
- What the skill does
- Commands
- Quick start
- Installation
- How it keeps the project organized
- What gets installed in your project
- Compatibility
- Obsidian
- Measuring the results
- Lint codes
- Limits
- FAQ
- Contributing
- Sources
The problem
Every token an agent loads before your first prompt competes for the model's attention. In real projects that layer grows quietly:
- instruction files turn into encyclopedias;
- the same paragraphs live in CLAUDE.md, AGENTS.md and GEMINI.md;
@importspull whole documents into every session;- rules without scope load even when you never touch that code;
- dates and "currently working on" notes break prompt caching;
- notes pile up in Obsidian with no index an agent can use.
The research points in one direction. Model accuracy degrades as context grows (Chroma, Context Rot, 18 models tested). Instruction-following drops when files carry too many rules (HumanLayer). Redundant or auto-generated AGENTS.md files can lower task success and raise cost (ETH Zurich evaluation). Fewer, better-placed instructions work better than more instructions.
What the skill does
- Interviews you briefly. Detects which agents the project uses and whether there is an Obsidian vault, then confirms with you.
- Measures a baseline. Tokens loaded per agent, per layer (always-on, conditional, on demand), plus runtime numbers from Claude Code and Codex transcripts.
- Scores the harness on 8 dimensions and writes a change plan grouped by risk.
- Applies only what you approve, on a separate git branch. It relocates content instead of deleting it.
- Installs a maintenance layer: a placement map, an automatic keeper skill, hooks for each agent, a git pre-commit check and optional CI.
- Measures again and writes a before/after report. Budgets are locked so they can only shrink.
Commands
| Command | What it does | Changes project files? | When to use |
|---|---|---|---|
/harness-audit diagnose | Detects agents and Obsidian vaults, asks you to confirm, measures the baseline, scores the harness and writes a plan with every proposed change, its risk and the tokens it saves. | No. Writes only to .harness/reports/. | First run on any project, or when budgets are breached. |
/harness-audit apply | Creates a git branch, installs the maintenance layer, executes only the plan items you approved, regenerates the index and projections, and runs the lint until it is clean. | Yes, on a new branch, after approval. | Right after reviewing and approving the plan. |
/harness-audit verify | Takes a new snapshot, compares it with the baseline, hands you the task benchmark prompts to run in a fresh session, locks the new budgets and writes HARNESS-REPORT.md. | Only reports and the budget lock. | After apply, in fresh agent sessions. |
/harness-audit check | Runs the fast lint and summarizes problems by severity with suggested fixes. | No. | Weekly, before a release, or anytime. |
Running /harness-audit with no argument starts diagnose. apply refuses to run without an approved plan.
In agents without slash commands, just ask: "run the harness-audit skill in diagnose mode".
How changes are approved
| Risk | Examples | Approval |
|---|---|---|
| Low | frontmatter, index, broken links, moving files into the right folders | once, as a batch |
| Medium | moving content out of entry files into rules, skills or docs; scoping rules; turning prose rules into hooks | per group |
| High | merging or rewriting knowledge, archiving notes, anything outside the repo (user-level files, external vault) | item by item |
Quick start
# 1. Install the skill for Claude Code
git clone https://github.com/fabianmartinelli-fm/harness-audit.git
cp -r harness-audit/skills/harness-audit ~/.claude/skills/
# 2. In your project, with everything committed
claude
> /harness-audit diagnose
Review .harness/reports/plan.md, approve, then run /harness-audit apply and /harness-audit verify.
Installation
Requirements: Python 3.9+ (standard library only) and git.
Claude Code
cp -r skills/harness-audit ~/.claude/skills/ # personal, all projects
# or
cp -r skills/harness-audit .claude/skills/ # this project only
Keep the disable-model-invocation: true line in SKILL.md: it hides the skill from the model's context until you call it.
Claude apps (Settings > Skills upload)
Download harness-audit.zip from the latest release and upload it. The release zip contains a single SKILL.md with standard frontmatter, as the upload requires. Use it where Claude can reach your local project files.
Codex, Cursor, Antigravity
| Agent | Project folder | Notes |
|---|---|---|
| Codex | .agents/skills/harness-audit/ | user-level skills folder per Codex docs |
| Cursor | .cursor/skills/harness-audit/ | or ~/.cursor/skills/ |
| Antigravity CLI | .agents/skills/harness-audit/ | shares .agents/skills with Codex |
Build the packages yourself
python3 tools/build_dist.py
Creates dist/harness-audit.zip and dist/harness-keeper.zip (upload-ready, validated) and dist/claude-code/ (filesystem copies with Claude Code extensions).
How it keeps the project organized
Writing instructions is not enough, because instructi
// HOW IT'S BUILT
KEY FILES