# Craft Harness > Build, repair, sync, prune, and evolve a project-specific agent harness for Codex and Claude Code. Use when repo guidance, AGENTS.md/CLAUDE.md, local skills, commands, hooks, subagents, MCP/integration notes, plugins, or adoption choices need a repo-local plan or small edits. Use when this capability is needed. - Skill: `tomevault-io/craft-harness` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/craft-harness` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/craft-harness/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/craft-harness --- # craft-harness ## Purpose Build and maintain the agent harness around a real repo. A harness is the set of files and installed capabilities that help coding agents work well in a project: root context, local context/rules, skills, commands, scripts, hooks, subagents, MCP/integrations, plugins, and external assets worth adopting. This skill is not only for first setup. Use it across the harness lifecycle: bootstrap, task-fit, repair, sync, adopt, prune, and maintain. ## Non-goals - Not a global config manager. - Not an installer or plugin publisher. - Not a runtime framework. - Not a replacement for the user's agent settings UI or marketplace flow. - Default output is a repo-local plan, small repo-local markdown/skill edits, or reviewable asset recipes. ## How it differs from related skills - `craft-skill-spec` designs one reusable artifact: a skill, skill suite, subagent, or plugin. - `craft-harness` decides what a repo's agent harness needs, where each piece belongs, and what to create, adopt, update, defer, or remove. - `craft-survey` studies prior art. `craft-harness` uses prior-art search as one step when buy-vs-build matters. - `craft-critique` reviews a prompt or skill without editing. `craft-harness` may use critique-style checks on the harness plan before applying changes. ## Inputs - the repo or task being supported - current primary target, if any: Codex, Claude Code, or both - observed agent failures or desired workflows - existing harness files and commands - constraints around edits, installs, hooks, MCP, plugins, or global config If the user does not state a primary target, default to dual-target output with Codex as the current primary. Claude Code remains a first-class target, not a fallback. ## Required reads Before making recommendations: 1. Inspect existing repo harness files first: - shared root and local context files - provider-specific skill, command, hook, subagent, MCP, plugin, and rules locations - repo workflow files: `package.json`, `Makefile`, CI config, scripts, docs 2. Read `references/platform-surfaces.md` when a recommendation touches provider-specific paths, hooks, subagents, MCP, plugins, or install locations. 3. Read `references/dual-target-layout.md` when the harness targets both Codex and Claude Code, uses `.agents/` as shared source, or needs symlink/copy decisions. 4. Read `references/hook-patterns.md` when recommending, reviewing, pruning, or generating hooks. 5. Read `references/eval-cases.md` when drafting or validating `craft-harness` changes. 6. Read adjacent CraftKit skills only when the recommendation would create or modify a prompt/skill artifact. Do not inspect user/global config unless the user explicitly asks for personal or global harness work. ## Lifecycle modes Choose one primary mode and mention secondary modes when useful: - `bootstrap` - create the smallest useful harness for a repo with little setup. - `task-fit` - add harness support for a specific task, PR, workflow, or team convention. - `repair` - fix repeated agent failures by moving guidance to the right surface. - `sync` - align Codex and Claude Code surfaces when they drift. - `adopt` - evaluate external skills, plugins, MCPs, or integrations before building locally. - `prune` - remove stale, bloated, duplicated, or conflicting harness guidance. - `maintain` - reassess after model, tool, repo, or workflow changes. ## Workflow 1. State the harness mode and primary target. If tradeoffs conflict, prefer the user's current primary agent; otherwise prefer Codex while keeping Claude Code support explicit. 2. Inventory the existing harness. Mark each relevant file or installed surface as `keep`, `update`, `missing`, `risky`, or `prune`. 3. Name the repeated agent jobs: navigation, implementation, review, verification, release, incident work, research, handoff, backlog work, external-tool work, or project onboarding. 4. Choose placement for each need: - root context for stable rules every task needs - local context or path-scoped rules for directory-specific facts - skill for reusable judgment workflow - command for explicit manual shortcut - script for deterministic checks that should be run on demand - hook for deterministic lifecycle automation: either a community-proven guardrail candidate or a project-specific repeated miss where timing matters - MCP/integration for structured access to an external system - subagent for isolated exploration, review, or role separation - plugin for installable multi-surface packaging - external adoption when a maintained asset fits better than local invention - no change when the existing harness is enough 5. Run buy-vs-build when a new skill, plugin, MCP server, hook, or integration is plausible. Search or explicitly say why search was skipped. Use `adopt`, `fork/adapt`, `build local`, or `defer`. 6. Produce a patch plan before high-risk edits. Low-risk repo-local markdown and skill drafts may be edited when the user asked to make the change. 7. Verify the harness with prompts or commands that exercise the intended behavior, not just static file syntax. ## Risk gates Low-risk repo-local edits may be made when the user asks for implementation: - repo-local markdown guidance - `AGENTS.md` / `CLAUDE.md` bridge updates - repo-local skill drafts - repo-local docs and verification prompts Require explicit approval before: - adding or enabling hooks or hook scripts - adding MCP servers or external integrations - installing plugins or adding marketplaces - editing user/global config - creating write-capable subagents or custom agents - adding commands that affect secrets, auth, deployment, or CI behavior Defer by default: - organization-managed policy - plugin packaging and publishing - broad agent-team factories This skill may propose high-risk surfaces, but it does not install or enable them unless the user explicitly asks for that after seeing the plan. When proposing a hook, name the hook class, dry-run command, false-positive notes, and rollback steps. When proposing third-party adoption, inspect the files that execute or steer tools before recommending install. ## Output format ### Harness mode - mode - primary target - why this mode fits ### Existing harness Short inventory grouped as `keep`, `update`, `missing`, `risky`, and `prune`. ### Pain / need map Table with: - need - repeated agent job - evidence - placement - promotion trigger ### Buy vs build Include when a new skill, plugin, MCP server, hook, or integration is plausible. For each candidate, name source, decision (`adopt`, `fork/adapt`, `build local`, or `defer`), trust notes, why it fits or fails, and rollback path. Trust notes cover provenance, execution, permissions, freshness, and portability. ### Proposed edits Table with path/target, action, risk gate (`none`, `approval required`, or `defer`), and rationale. For hook rows, also include: - hook class: `community-proven guardrail` or `project-specific` - dry-run command - rollback note ### Codex target List Codex-specific files, commands, trust/reload steps, and caveats. ### Claude target List Claude-Code-specific files, commands, trust/reload steps, and caveats. ### Verification List prompts or commands with expected evidence and failure signals. ### Deferred / prune List work intentionally skipped, why now is too early, and the reassessment trigger. ## Placement rules - Keep root context small. Move procedures into skills, commands, scripts, or hooks. - Prefer `AGENTS.md` plus a `CLAUDE.md` import or symlink only when both agents should read the same stable core. Do not assume identical load behavior. - Prefer a skill over a long root instruction when the guidance is a reusable workflow. - Prefer a script over prose when the rule is deterministic and easy to run. - Prefer a community-proven guardrail hook candidate during `bootstrap` or `maintain` only when it is deterministic, fast, read-only by default, no-network by default, low-noise, and easy to roll back. - Prefer a project-specific hook over a script only when timing matters and repeated repo-specific misses justify lifecycle automation. - Prefer a subagent only when isolated context, parallel work, or a constrained role improves output quality. - Prefer a plugin only when installation, versioning, bundled integrations, or marketplace distribution are part of the value. - Prefer no change when the existing harness already supports the job. ## Verification prompts Use one or two starter evals before shipping changes to this skill. The full case set and expected checks live in `references/eval-cases.md`. - "Set up this repo so Codex and Claude both know the test, lint, and release workflow without bloating root instructions." - "Agents keep missing migration safety checks in this repo. Decide whether to use context, skill, script, hook, or subagent." Pass signal: the output inventories existing harness files first, separates provider-neutral decisions from Codex/Claude targets, risk-gates high-risk surfaces, and verifies behavior rather than only file syntax. ## Failure modes - over-generating every possible harness surface instead of solving the repeated job - treating Codex and Claude paths as a mechanical one-to-one migration - putting long workflow procedures into `AGENTS.md` or `CLAUDE.md` - skipping external search and rebuilding a maintained asset - recommending third-party install without trust and maintenance checks - avoiding hooks even when the guardrail is deterministic, common, low-noise, and timing-sensitive - installing hooks automatically instead of proposing reviewable scripts and target adapters - adding hooks or MCP config without rollback or approval notes ## Example ### Input "Agents keep missing our migration safety process. We use Codex more lately, but some teammates use Claude Code too." ### Output sketch **Harness mode** - mode: `repair` - primary target: Codex current-primary, Claude Code first-class target - why: the issue is a repeated agent miss in an operating repo **Pain / need map** | need | repeated agent job | evidence | placement | promotion trigger | |---|---|---|---|---| | migration safety checklist | verification/review | repeated misses during DB work | repo-local skill plus short root pointer | promote to hook only if agents still skip deterministic checks | **Verification** - Prompt: "Review this migration change and tell me what safety checks apply." - Expected evidence: agent finds the migration skill and names rollback, idempotency, data-size, and test checks. - Failure signal: agent only says "run tests" or misses rollback/data safety. **Deferred / prune** - plugin packaging: defer until the skill proves useful across more than one repo. --- > Source: [sungjunlee/craftkit](https://github.com/sungjunlee/craftkit) — distributed by [TomeVault](https://tomevault.io).