菜单
Self-improving meta-harness for auditing, bootstrapping, and improving agent harnesses
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
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