SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsagent-harness

agent-harness

Agents & models

View repository

Updated 10-16 01:35

About this skill

Agent Harness

The agent harness makes a repo agent-ready with self-sustaining enforcement. This skill installs it; CI, hooks, and conventions then enforce it.

Modes

1. Verify (primary)

Always start here. From the target repo root, run:

${CLAUDE_SKILL_DIR}/scripts/verify-harness.sh

Analyse the output and fix or suggest fixes. Verification checks dead references, line counts, missing artefacts, and command/target alignment.

2. Bootstrap

When artefacts are missing, create them from templates:

Artefact Template Platform
AGENTS.md templates/AGENTS.md.tmpl All
docs/ARCHITECTURE.md templates/ARCHITECTURE.md.tmpl All
docs/exec-plans/{active,completed}/ Create directories All
.github/workflows/harness-verify.yml templates/harness-verify.yml.tmpl GitHub
.gitlab-ci.yml (harness-verify job) templates/gitlab-ci-harness-verify.yml.tmpl GitLab
.forgejo/workflows/harness-verify.yml templates/forgejo-harness-verify.yml.tmpl Forgejo/Gitea
.github/workflows/harness-checkpoints.yml templates/harness-checkpoints.yml.tmpl GitHub
.gitlab-ci.yml (harness-checkpoints job) templates/gitlab-ci-harness-checkpoints.yml.tmpl GitLab
.forgejo/workflows/harness-checkpoints.yml templates/forgejo-harness-checkpoints.yml.tmpl Forgejo/Gitea
.github/pull_request_template.md templates/pull_request_template.md.tmpl GitHub
.gitlab/merge_request_templates/Default.md templates/merge_request_template.md.tmpl GitLab
.forgejo/pull_request_template.md templates/pull_request_template.md.tmpl Forgejo/Gitea
.envrc templates/envrc.tmpl All
Makefile harness targets templates/Makefile.harness.tmpl All
scripts/verify-harness.sh ${CLAUDE_SKILL_DIR}/scripts/verify-harness.sh (copy directly) All
.harness/checkpoints.yml see references/enforcement-mechanisms.md § 12 All

Populate with repo-specific values; never overwrite existing files without confirmation.

3. Audit

Report the repo's maturity level (1, 2, or 3) and show what is needed to reach the next level. See references/maturity-levels.md for detailed criteria.

Running the checks that skills ship

A skill's own validator is run by an agent only if the agent decides to, and measured over six trials on the case where it was most obviously relevant, it was run once (#61). A repository therefore declares in .harness/checkpoints.yml which skills' checkpoints apply to it, pinned by ref, and a CI job runs them:

${CLAUDE_SKILL_DIR}/scripts/run-shipped-checkpoints.sh

It fails the job on a failing checkpoint of severity error, reports the rest, and exits 2 on a declaration it cannot resolve rather than passing quietly. verify-harness.sh errors when a declaration has no job, and when a job has no declaration.

Key Principles

  • AGENTS.md is an index, not an encyclopedia. Keep it under 150 lines. Put detail in docs/.
  • Enforcement is project-level. CI workflows, git hooks, and branch protection enforce the harness -- not this skill at runtime.
  • Verify first, bootstrap second. Always run verification before creating artefacts. The skill checks artefacts, not tools.
  • Delegate specialist work. See references/skill-integration-map.md for skill routing (@agent-rules, @github-project, @enterprise-readiness, @retro).
  • Does not own learning. Session retrospection, outcome review, and constitutional audits are delegated to retro-skill. The harness verifies integration points exist (AH-22, AH-23) but does not invoke retro at runtime.

Maturity Levels

Level 1 -- Basic: AGENTS.md exists, is an index, documents commands.

Level 2 -- Verified: CI enforces harness integrity, AGENTS.md references resolve, commands match Makefile/scripts, ARCHITECTURE.md exists.

Level 3 -- Enforced: Branch protection requires harness CI, git hooks auto-activate, PR template includes checklist, drift detection on push.

See references/maturity-levels.md for the full breakdown.

References

  • references/maturity-levels.md -- Maturity criteria and progression
  • references/harness-engineering-overview.md -- Theory: four functions, patterns
  • references/agent-first-architecture.md -- Legibility, layered deps, agent-first tech
  • references/enforcement-mechanisms.md -- 12-mechanism table (CI, hooks, protection, drift, shipped checkpoints)
  • references/skill-integration-map.md -- Skill routing map + integration contracts with companion skills