ingpoc/agentharness-audit

agentharness-audit — score any agent harness against 13 quality principles

Self-validate after edits. Any change to this skill's files must be followed by ./scripts/validate.sh from the skill directory.

Audits an agent harness codebase against 13 evidence-based meta-principles derived from comparative analysis of Hermes, Claude Code, Codex CLI, and OpenClaw. Each principle is scored 0–10 with code citations. The operator receives a print-ready Tufte HTML report; the harness itself receives a concrete self-improvement directive in AGENTS.md format.

Procedure

Full step-by-step: references/procedure.md

1. Discover — map the codebase (system prompt, tool loading, memory, compaction, subagents, config)
2. Score — evaluate each of the 13 principles with file:line citations (references/principles.md)
3. Report — copy the bundled templates/audit.html.template to docs/agentharness-audit/<name>-audit.html and fill placeholders using references/html-template.md. Do not regenerate the report from scratch or require loading another skill.
4. Directive — write docs/agentharness-audit/<name>-AGENTS.md (references/agents-template.md)
5. Print — output scores table to terminal

If no path is specified, audit the current working directory.

Hard rules

1. Evidence before score. Every score requires a file:line citation or an explicit "not found" declaration.
2. Both files always. HTML report and AGENTS.md are both produced on every run.
3. Concrete recommendations only. AGENTS.md must name specific files and patterns — "implement Y at Z", never "improve X".
4. Self-contained HTML path. The bundled template is the required source of truth. html-artifact is provenance only; do not depend on loading it during an audit run.
5. Not a harness → exit cleanly. If no agent loop, tool dispatch, or model calls are found, say so and stop.

Cross-references

• references/procedure.md — full audit procedure
• references/principles.md — 13 principles with scoring rubric and 9.5 references
• references/html-template.md — fill guide + substitution helpers for the HTML report
• templates/audit.html.template — literal self-contained HTML scaffold; this is the source of truth for report generation. It was derived from html-artifact report-lane conventions but does not require loading html-artifact.
• references/agents-template.md — AGENTS.md template and writing rules
• references/architecture.md — canonical patterns, anti-patterns, design rationale, and winner codebase references per principle

Why this skill exists

Agent harnesses are evaluated on marketing claims, not the mechanisms that determine token efficiency, self-improvement, and operator accessibility. This skill makes those mechanisms legible and scoreable — enabling evidence-based harness selection and a concrete improvement roadmap that the harness agent can execute autonomously.