Skills are Markdown prompt programs you summon with /skill-name. They chain through defined gates so work flows discovery → design → planning → execution → review → shipping — no skipping
steps allowed.

Why this exists

The problem

Most repositories are built for humans who already know the codebase. A coding agent arrives with
only a chat prompt and a shallow file snapshot — and that gap produces predictable failure modes:

• It edits code before understanding intent — solving the wrong problem fluently.
• Constraints live only in chat history or someone's head, so they're lost between sessions.
• Validation expectations are vague, discovered too late, or asserted without proof.
• Architecture tradeoffs get re-litigated every time instead of inherited.
• The same process is applied to every change — over-ceremonying a typo, under-scrutinizing an
  auth rewrite — and the human is asked about everything or nothing.

The harness approach

A repo grows a harness so an agent can answer the practical engineering questions before it
writes code, without relying on conversation history:

• What should I read first?
• What type of work is this, and how risky?
• Which product contract does it touch?
• What proof will show the work is done?
• What decision or lesson should future agents inherit?

And it sizes the answer with one principle, two independent dials:

Ceremony scales with risk. Human interruption scales with ambiguity.

Risk decides how much proof and process a change carries (planning, reviews, recorded
evidence and rollback). Ambiguity / confidence decides whether a human is asked — never to
classify risk, only to confirm intent or authorize a dangerous boundary. So a high-risk-but-clear
change runs autonomously through heavy proof, while a tiny-but-unclear change stops to ask. Risk ≠
interruption.

How this repo resolves it

The repo is two layers: an engine of invocable /skills that do the work, and a thin
harness that decides — before the engine runs — how much process and when to involve a
human. Each engineering question maps to an enforced mechanism, not a convention:

And the claim is corroborated by code: at commit time, hooks check the staged diff against the
declared lane — the agent can't label a risky change "tiny" and slip it through.

See HARNESS.md for the full model — lanes, hard gates, and how each hook
enforces it.

Installation

Add to an existing project

One-liner that clones the harness, builds .claude/, and leaves your project root clean:

curl -fsSL "https://raw.githubusercontent.com/minhtran3124/harness-skills/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --yes

Everything the harness needs lives in a gitignored .claude/ (skills, agents, hooks, rules, templates, settings). At the project root it touches only two things: .mcp.json (wires the code-review-graph MCP server — merged into your existing one if present; Claude Code only reads this file at the root), and the workflow's structural dirs (specs/, docs/solutions/), scaffolded create-if-missing. The installer never overwrites or deletes anything at your root — it only adds structural files that are absent. To update, just re-run the one-liner (idempotent; .claude/ is merge-synced, non-harness entries and locally-generated files kept; a protected file that differs from incoming is reported via a <file>.harness-incoming sidecar rather than overwritten).

Needs git + jq; uv is strongly recommended — the code-review-graph MCP server launches through uvx, and the installer warns when it's missing.
Flags: --directory <path> · --branch <name> · --source <local checkout> · --keep-sources · --dry-run · --overwrite-conflicts (replace protected files with the incoming copy; --force/--yes keep local files instead of overwriting them).

Then restart Claude Code so it loads the skills, agents, and hooks.

Develop on this repo

Working on the harness itself keeps the editable source at the repo root and Claude Code loads from a derived, gitignored .claude/. Rebuild it with:

bash scripts/deploy-harness.sh

First run installs; any later run updates (idempotent). Re-run after editing anything under skills/ agents/ hooks/ rules/ templates/ settings.json. (Installing into another project with --keep-sources keeps a copy of these sources in <target>/.harness-source/, for inspection or offline re-sync via bash .harness-source/scripts/deploy-harness.sh --target ..)

Testing

bash scripts/run-tests.sh runs what CI runs: syntax checks + a doc-truth lint (every path referenced in the core docs exists; the CLAUDE.md hook table matches settings.json), hermetic contract tests for the hooks (each runs in a throwaway git repo against its stdin-JSON contract), and installer integration tests. The harness-ci workflow runs the same suite on ubuntu + macos.

MCP servers

This repo wires the code-review-graph MCP server in .mcp.json — and install-harness.sh wires the same server into a consuming project's root .mcp.json automatically (creating it, or merging the entry into an existing one). It launches through uv's uvx runner, so there's no manual pip install — uvx fetches and runs it on demand.
You just need uv (which provides uvx):

curl -LsSf https://astral.sh/uv/install.sh | sh   # installs uv + uvx
uvx code-review-graph serve                        # exactly what .mcp.json invokes

The graph data is written to .code-review-graph/ (gitignored). The context7 MCP server is configured at the Claude Code user level (HTTP, needs CONTEXT7_API_KEY) — it is not in this repo's .mcp.json, so each user wires it in their own global config.

Further reading

skills/README.md is the single source of truth — full skill
inventory, triggers, outputs, handoff map, alternate paths, and per-skill design rationales.

HARNESS.md — how the risk/trust harness shapes the workflow: lanes,
when a human is asked, and how hooks enforce it. Read this to understand why the flow behaves
the way it does.

Guide site — the companion walkthrough at
skill-harness-guide.vercel.app.

Author

Minh Tran — @minhtran3124 · [email protected]

See CONTRIBUTORS.md for the full cast and how to join in.