mcpField
A
agent-harness

agent-harness

github.com/netresearchAgent workflows635 installsUpdated 1d ago
Repository

About agent-harness

agent-harness is a skill for making repositories ready for agent work through verification, bootstrapping, and maturity audits. It suits teams that want CI, hooks, and conventions to enforce repository-level practices.

Key features

  1. 01Verify references, files, and command alignment
  2. 02Bootstrap missing files from templates
  3. 03Audit and report maturity levels
  4. 04Run declared skill checkpoints

Use cases

  1. 01Check a repository against harness conventions
  2. 02Add foundational docs and CI to a repository
  3. 03Assess what is needed for the next maturity level

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/netresearch/agent-harness-skill --skill agent-harness

After installing, type/agent-harnessin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

checkpoints.yaml
references/
agent-first-architecture.md
enforcement-mechanisms.md
harness-engineering-overview.md
maturity-levels.md
skill-integration-map.md
references/adr/
001-verify-first-design.md
002-enforcement-layers.md
003-skill-delegation-model.md
004-agents-md-as-index.md
005-checkpoint-maturity-model.md
scripts/
run-shipped-checkpoints.sh
verify-harness.sh
templates/
AGENTS.md.tmpl
ARCHITECTURE.md.tmpl
envrc.tmpl
exec-plan.md.tmpl
forgejo-harness-checkpoints.yml.tmpl
forgejo-harness-verify.yml.tmpl
gitlab-ci-harness-checkpoints.yml.tmpl
gitlab-ci-harness-verify.yml.tmpl
harness-checkpoints.yml.tmpl
harness-verify.yml.tmpl
Makefile.harness.tmpl
merge_request_template.md.tmpl
pull_request_template.md.tmpl

Details

From the project README

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:

ArtefactTemplatePlatform
AGENTS.mdtemplates/AGENTS.md.tmplAll
docs/ARCHITECTURE.mdtemplates/ARCHITECTURE.md.tmplAll
docs/exec-plans/{active,completed}/Create directoriesAll
.github/workflows/harness-verify.ymltemplates/harness-verify.yml.tmplGitHub
.gitlab-ci.yml (harness-verify job)templates/gitlab-ci-harness-verify.yml.tmplGitLab
.forgejo/workflows/harness-verify.ymltemplates/forgejo-harness-verify.yml.tmplForgejo/Gitea
.github/workflows/harness-checkpoints.ymltemplates/harness-checkpoints.yml.tmplGitHub
.gitlab-ci.yml (harness-checkpoints job)templates/gitlab-ci-harness-checkpoints.yml.tmplGitLab
.forgejo/workflows/harness-checkpoints.ymltemplates/forgejo-harness-checkpoints.yml.tmplForgejo/Gitea
.github/pull_request_template.mdtemplates/pull_request_template.md.tmplGitHub
.gitlab/merge_request_templates/Default.mdtemplates/merge_request_template.md.tmplGitLab
.forgejo/pull_request_template.mdtemplates/pull_request_template.md.tmplForgejo/Gitea
.envrctemplates/envrc.tmplAll
Makefile harness targetstemplates/Makefile.harness.tmplAll
scripts/verify-harness.sh${CLAUDE_SKILL_DIR}/scripts/verify-harness.sh (copy directly)All
.harness/checkpoints.ymlsee references/enforcement-mechanisms.md § 12All

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

Comments

Markdown supported