Menu
Self-improving meta-harness for auditing, bootstrapping, and improving agent harnesses
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Close a GitHub issue with discipline — resolved, superseded, or duplicate. Pre-flights body + comments, migrates substance before destroying context, cross-links both directions.
File a new GitHub issue with duplicate search, scope decision, label discovery, and preview before posting. Prevents fragmented or silently-filed issues.
Restructure the topology of GitHub issues — split one into many focused replacements, or merge multiple into one keeper. Migrates substance and cross-links before closing anything.
Update an existing GitHub issue — edit body, post a comment, retag, or reopen. Pre-flights body + comments; acknowledges stale framing instead of silently rewriting.
Review and address PR feedback using 6-dimensional code review
Structured code review using 6 dimensions. Works with or without the code-reviewer agent.
| name | harness |
| description | Self-improving meta-harness for auditing, bootstrapping, and improving agent harnesses |
| allowed-tools | Bash(ls*), Bash(grep*), Bash(git*), Bash(${CLAUDE_PLUGIN_ROOT}/skills/shared/discover-verification-cmd.sh*), Read, Glob, Write, Edit |
Unified command for harness management. Auto-detects mode or use subcommands to audit, bootstrap, retro, or hoist agent harnesses.
Establish quality gates on agent harnesses — skills, agents, hooks, and documentation — to catch gaps and inconsistencies before they affect productivity.
.claude/ directory with agents, skills, or both (or you're bootstrapping a new project)/harness skill).harness-lock.json tracks which files came from upstream vs project-localAuto-detect and run the appropriate mode:
/harness # Auto-detect: bootstrap if no harness, audit if exists
/harness audit # Run 10-step audit on current harness
/harness bootstrap # Analyze project, install skills/agents from plugin, generate project-specific additions
/harness update # Pull latest from upstream sources, smart-merge with local changes
/harness add <repo> # Add skills from another plugin marketplace
/harness retro # Post-session retrospective
/harness hoist # Propose upstream PR for generic improvements
If no .claude/ → runs bootstrap (generates harness). If .claude/ exists → runs audit (validates quality).
Run the 10-step audit protocol on the current project's harness. Default mode when .claude/ exists.
Find the verification command for this project:
justfile for check or ci recipeMakefile for ci, check, or test targetpackage.json for test or check scriptCargo.toml → cargo testflake.nix → nix flake check.claude/agents/ and .claude/skills/.claude/commands/ directory — flag for migration to skillsCLAUDE.md for harness documentationhaiku for fast validation tasks (verifier)sonnet for generation and analysis (code-reviewer, test-writer)opus only for deep architectural decisionsChernyCode principle: "If you do something more than once a day, make it a skill."
Universal agents (should exist in every project):
code-reviewer agent? (6-dimension review)verifier agent? (skeptical validator)test-writer agent? (project testing conventions)domain-advisor agent? (read-only, answers business rules)Stack-dependent:
project-manager agent? + /feature-spec, /issue-triage, /standup skills?.impeccable.md) + /ui-review skill?Project-specific:
/commit skill with quality gates?.claude/commands/ directory? (flag for migration to skills)Automation (Hooks):
.claude/settings.local.json?/harness retro after large sessions)?WriteWrite or EditWrite but only for test filesFor each agent:
Gap classification:
skills/shared/Progressive Disclosure (scannable contract):
/documentation-writer and /skill-writer skills for structure guidanceFor domain skills: Does a test file encode these rules as executable specs? If the harness is the only place a rule is enforced, it's in the wrong place.
For agents: Does the agent report conditions users should see in the product? If yes, that's a missing product feature.
## PURPOSE line? (answerable in ≤10 tokens)## CRITICAL block? (negative constraints first)/documentation-writer and /skill-writer to create new skills/agents with proper structureFor each finding:
Analyze the project, install skills/agents from the harness-kit plugin, and generate project-specific additions. Auto-triggers when .claude/ directory doesn't exist or is empty.
Spawn harness-builder agent — It analyzes the codebase and returns:
agents/references/architecture-patterns.md)Present recommendations for approval:
Do NOT write any files until the user approves.
After approval, install and generate:
${CLAUDE_PLUGIN_ROOT}/skills/ to .claude/skills/${CLAUDE_PLUGIN_ROOT}/agents/ to .claude/agents/skills/shared/ scripts to .claude/skills/shared/${CLAUDE_PLUGIN_ROOT} references to .claude in copied files.claude/agents/.claude/skills/CLAUDE.md with all sections filled in.claude/settings.local.json.harness-lock.json tracking provenance of every installed file.claude/harness-upstream (one line: owner/repo) so /harness-issue knows where to file feedback. Use the source repo from the lock file (default dougborg/harness-kit)..gitignore (add .claude/settings.local.json if it contains secrets).claude/commands/ — commands are legacyRun verification command to confirm nothing broke.
The .harness-lock.json file is created during bootstrap and tracks every file's provenance:
{
"sources": {
"harness-kit": { "version": "0.1.0", "installed": "2026-04-04", "repo": "dougborg/harness-kit" }
},
"files": {
".claude/skills/commit/SKILL.md": { "source": "harness-kit", "modified": false },
".claude/agents/code-reviewer.md": { "source": "harness-kit", "modified": false },
".claude/agents/domain-advisor.md": { "source": "local" }
}
}
The repo field on each source records the GitHub upstream so /harness-issue and /harness hoist can route feedback and proposed changes to the right place. Omit repo for purely local sources.
This file should be committed — it lets teammates run /harness update to sync.
code-reviewer (6D review), verifier (validation), test-writer (testing), domain-advisor (read-only business rules)project-manager (issue/PR/sprint management via gh CLI)/ui-review skill for accessibility auditsPull latest changes from upstream sources and smart-merge with local modifications. Run after the harness-kit plugin is updated.
Read .harness-lock.json — Get current source versions and file provenance.
Check for upstream updates:
${CLAUDE_PLUGIN_ROOT} has the latest) vs lock file version.claude/For each upstream file:
modified: false → Overwrite with latest from plugin. Silent.modified: true → Show diff between upstream and local. Ask user:
source: "local" → Never touch. These are project-specific.Check for new upstream files — Files in the plugin that aren't in the lock file yet. Offer to install them.
Update .harness-lock.json — New version, updated timestamps, modified flags.
Show changelog — Summary of what was updated, what was skipped, what's new.
Add skills from another plugin marketplace into the project's .claude/.
/harness add vercel-labs/agent-skills
Check if marketplace is already added:
claude plugin marketplace list
If not, instruct user: /plugin marketplace add vercel-labs/agent-skills
Browse available skills from the marketplace.
User selects which skills to install into .claude/.
Copy selected skills to .claude/skills/.
Update .harness-lock.json with new source and file entries.
Run verification command to confirm nothing broke.
Post-session retrospective to identify gaps and improvements in the harness. Run after significant sessions to capture learnings.
Analyze recent changes:
git log --since="8 hours ago" --oneline
What domains were touched? What changed?
Reflect on skill usage:
Identify gaps and classify:
.claude/skills/, add to lock as source: "local").claude/patterns/)Promotion heuristic: Before classifying as Type D, ask: would this prevent the same mistake in another project, or for another agent? If yes, escalate to A/B/C — encode it in a skill, not memory. Memories are session/user-scoped and fade; skills persist and ship to every consumer of the harness. Type D is for pattern learnings genuinely scoped to this project's quirks.
Propose 1-3 improvements as specific, actionable changes.
Promotion pass — what belongs upstream? For every finding (not just Type C), ask: would this prevent the same problem in another harness-kit consumer? If yes, mark it as upstream-worthy. Common cases:
.harness-lock.json) — the upstream skill is wrong, not just your local copySurface upstream candidates and confirm with the user before filing. Show each upstream-worthy finding and ask per item: file as Issue, open as PR, hoist a local fix, or skip. Then act:
/harness-issue (configurable upstream; defaults to harness-kit)/harness hoist for cases where you already have a working local diff to propose backFor Type D patterns: Save as a brief markdown note. Patterns are lighter than skills — they capture heuristics like "in this codebase, always check X before Y" or "this API returns 404 for deleted resources, not 410." Store in memory files or a .claude/patterns/ directory.
Propose improvements to the upstream harness-kit plugin (or other upstream sources) when a project-local skill improvement is generic enough to benefit all projects.
Read the lock file — .harness-lock.json tells you which files came from which upstream source and whether they've been modified.
Inventory project harness — Read every file in project .claude/agents/ and .claude/skills/.
For each modified or local file, ask:
Classify each candidate:
Propose changes (prefer fewer, better upstream skills over more):
After approval: Clone the upstream repo, create a branch, apply changes, open a PR via gh.
When designing or reviewing harness skills and agents, follow these principles:
Commands are legacy in Claude Code — skills supersede them. Always use skills.
context: fork, user-invocable, etc.)Plugin distribution: Skills and agents are distributed via the harness-kit plugin. /harness bootstrap copies them into the project's .claude/ directory so they're committed and portable.
Project-local extension pattern: When a project needs to customize an upstream skill, modify the local copy and mark it as modified: true in .harness-lock.json. /harness update will warn before overwriting modified files.
Inline bash in skills is a smell. It costs tokens on every invocation, drifts between skills, and is untestable. Extract it into scripts.
skills/shared/ for cross-skill usegit status, nix flake check)allowed-tools frontmatter: Bash(${CLAUDE_PLUGIN_ROOT}/skills/shared/script.sh*)Never ask users to do things you can do yourself.
Skills should minimize user interaction. Only ask for:
Auto-execute safe operations:
/switch runs /pre-flight without asking)Example:
❌ Bad: "Have you staged your changes? (yes/no)"
✅ Good: [auto-check git status, report findings, only ask if deploy needed]
❌ Bad: "Should I run validation? (yes/no)"
✅ Good: [run validation, report results, only ask if issues found]
✅ OK to ask: "This will force-push main. Confirm? (yes/no)" [truly destructive]
When a global skill already exists, project-local versions should:
Example: /commit (upstream) handles conventional format; project-local /commit adds project-specific quality gates (e.g., nix flake check, cargo clippy, npm run lint).
If a skill has prerequisites (e.g., /switch requires /pre-flight):
Never:
❌ "Have you run /pre-flight? (yes/no)"
Instead:
✅ Check git status → if clean and validated, proceed
✅ If not validated, run /pre-flight automatically → then proceed
Principle: Don't ask users to do things we can automate.
Schema reference: For the correct shape of plugin hooks/hooks.json (including the common plugin-vs-settings.json gotcha), see agents/references/hooks-reference.md. Validate locally with just validate-hooks.
Configure in .claude/settings.local.json to auto-fix on every file edit:
Formatters (stage 1) — Silent, zero-token cost
nix run ".#format", prettier --write, ruff check --fixValidators (stage 2) — Bounded output (≤30 lines), gated with conditions
nix flake check, type checking, test runningGuidance (stage 3) — Context reminders (≤20 lines)
Configure session-end hooks for retrospective nudges:
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "changed=$( { git diff --name-only 2>/dev/null; git diff --name-only --cached 2>/dev/null; git log --diff-filter=ACMR --name-only --pretty=format: --since='4 hours ago' 2>/dev/null; } | sort -u | wc -l | tr -d ' '); if [ \"$changed\" -gt 3 ]; then echo \"💡 Session touched $changed files — consider /harness retro to capture learnings\"; fi"
}
]
}
]
Purpose: After large sessions (>3 files changed), remind the user to run /harness retro to capture learnings before context is lost. Counts unstaged, staged, and recently committed files to capture the full session scope.
Exit code safety: See DETAIL: Hook Exit Code Safety — all hooks must exit 0 on both success and no-op.
Note: This hook is provided by the harness-kit plugin. Projects only need to override it in .claude/settings.local.json if they want different behavior.
Use /documentation-writer and /skill-writer to create well-structured docs that scale context-efficiently. Update CLAUDE.md with "Automation Philosophy" section documenting this approach.
When you encounter a behavioral gap during any session (not just harness work):
Upstream fix — clone the harness-kit repo (or other upstream source), fix, and open a PR:
Agent(
description: "fix harness gap: [brief description]",
run_in_background: true,
prompt: "Fix [gap] in harness-kit.
1. git clone --depth 1 https://github.com/dougborg/harness-kit /tmp/harness-fix
2. cd /tmp/harness-fix && git checkout -b fix/[name]
3. Fix skills/[skill]/SKILL.md or agents/[agent].md. If fixing inline bash,
extract to a script instead of patching in place.
4. Commit, push, open PR with gh
5. Clean up: rm -rf /tmp/harness-fix"
)
Project-local fix — fix .claude/{skills,agents}/ directly in the current repo, commit normally. Mark the file as modified: true in .harness-lock.json.
Continue working — the upstream PR will be reviewed and merged separately. After merge, /harness update will pull the fix into all projects.
Behavioral gaps get encoded in skills via PRs, not memories. Memories fade; skills persist. Inline bash gets extracted into scripts.
Claude Code treats any non-zero exit code from a hook as a failure. This is a common pitfall with conditional hooks — the command works correctly but reports an error.
The problem:
# BAD: exits 1 when condition is false ([ ] returns 1, && short-circuits)
[ "$changed" -gt 3 ] && echo "message"
The fix — use if/then/fi:
# GOOD: if/then/fi always exits 0 when condition is false
if [ "$changed" -gt 3 ]; then echo "message"; fi
Alternative — append || true:
# OK: forces exit 0, but less readable
[ "$changed" -gt 3 ] && echo "message" || true
Audit rule: For every hook command, ask: "What happens when this has nothing to do?" If the answer is "it exits non-zero," it needs fixing.
Common patterns that silently fail:
| Pattern | Problem | Fix |
|---|---|---|
[ test ] && action | Exit 1 when test is false | if [ test ]; then action; fi |
grep pattern file | Exit 1 when no match | grep pattern file || true |
command | head -1 | Exit 141 (SIGPIPE) on some systems | Pipe to head -1 || true |
Any time during a session, flag a suspect skill:
> ⚠️ FLAGGED: [brief reason this guidance may be outdated or wrong]
Lightweight in-flight signal that feeds the next audit. Don't stop work — just flag it.
harness-builder agent — Used by bootstrap mode to analyze codebases and recommend harness setup/documentation-writer — Write scannable, progressive-disclosure docs/skill-writer — Create well-structured skills with PURPOSE/CRITICAL/STANDARD PATH