From harness-skills
Initialize and operate a project-level Agent Harness for software engineering work. Use when the user wants to create or update AGENTS.md, scaffold a minimal harness/ directory, define project context/tools/guardrails/gates, create run records, or combine bundled workflow skills into a repeatable Harness Engineering workflow.
How this skill is triggered — by the user, by Claude, or both
Slash command
/harness-skills:agent-harnessThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill to bootstrap and operate an Agent Harness: a controlled loop that tells agents what to do, what not to do, which context to load, which tools to use, how to record work, and how to evaluate completion.
agents/openai.yamlassets/templates/harness/context/architecture.mdassets/templates/harness/context/architecture.zh-CN.mdassets/templates/harness/context/coding-conventions.mdassets/templates/harness/context/coding-conventions.zh-CN.mdassets/templates/harness/context/dependency-notes.mdassets/templates/harness/context/dependency-notes.zh-CN.mdassets/templates/harness/context/initialization-notes.mdassets/templates/harness/context/initialization-notes.zh-CN.mdassets/templates/harness/context/project-brief.mdassets/templates/harness/context/project-brief.zh-CN.mdassets/templates/harness/context/repo-map.mdassets/templates/harness/context/repo-map.zh-CN.mdassets/templates/harness/controls/gates.mdassets/templates/harness/controls/gates.zh-CN.mdassets/templates/harness/controls/lifecycle.mdassets/templates/harness/controls/lifecycle.zh-CN.mdassets/templates/harness/controls/skills.mdassets/templates/harness/controls/skills.zh-CN.mdassets/templates/harness/evals/acceptance-checklist.mdUse this skill to bootstrap and operate an Agent Harness: a controlled loop that tells agents what to do, what not to do, which context to load, which tools to use, how to record work, and how to evaluate completion.
This is an orchestration skill. Do not duplicate the full workflows of related skills. Use this skill to create the project harness and route work to the right supporting skill when needed.
xs, standard, or full).Choose one mode before scaffolding or updating harness files:
greenfield: Use when the project is empty, has no source or manifest files, or the user describes a new project from a short idea.brownfield: Use when the project already has source code, manifests, tests, CI, README, or other implementation history.existing-harness: Use when AGENTS.md or harness/ already exists.For existing-harness, preserve existing harness content by default. Add missing files, refresh stale placeholders, and propose larger rewrites only when the user asks.
Choose the harness language before writing files:
AGENTS.md, harness/context/*, run records, workflow.md, design.md, spec.md, plan.md, execution-log.md, review.md, and evaluation.md.brownfield, prefer the existing project documentation language when it is consistent. If the user language and project language differ, use the user language for new run records and keep references to existing files unchanged.--language zh-CN. Use --language en only when the project or user clearly prefers English.Use guided initialization before implementation when the project has only a short idea, the product shape is unclear, or blocking decisions are missing.
Use brainstorming for the actual clarifying questions and design.md output. Do not duplicate that workflow in this skill.
Do not write application code after asking the brainstorming questions. Wait for the user's answers, then update project-brief.md, create or update workflow.md and design.md, and proceed to spec only when the blocking decisions are answered or explicitly deferred as a non-coding decision task.
For content-driven products such as news, directories, dashboards, or curated feeds, this gate is required unless the user already provided content categories, source strategy, update cadence, ranking/filtering, page structure, and MVP quality bar.
Inspect the target project before writing harness files:
For greenfield, also capture the project idea, target user, success criteria, constraints, product shape, preferred stack if provided, core implementation direction, and unknown decisions. If the user only gave a one-sentence idea, use brainstorming to clarify target audience, content/data scope, core user experience, success criteria, constraints, technology stack, and core approach before writing the executable spec.
For content-driven products such as news, directories, dashboards, or curated feeds, clarify content categories, source strategy, update cadence, ranking/filtering, page structure, and MVP quality bar before implementation. Do not turn a broad content product idea into a generic demo without confirming what the user wants the experience to be.
For brownfield, use read-only discovery first. Prefer existing project facts over generic templates, reference existing documentation and configuration, and do not replace established conventions unless the user explicitly asks.
If a command is unknown, mark it as Unknown or Not applicable in harness/tools/commands.md; do not invent commands.
Create or update the minimal harness from assets/templates/:
AGENTS.md
harness/
├── context/
│ └── project-brief.md
├── controls/
│ └── gates.md
├── tools/
│ └── commands.md
├── guardrails/
│ └── boundaries.md
├── scripts/
│ └── check_run.py
└── runs/
Use scripts/init_harness.py for deterministic scaffolding when creating the structure from scratch:
--profile core (default): the only supported scaffold profile. It creates the minimal harness, local gates, and run checker.--language zh-CN: Chinese harness templates.--language en: English harness templates.--language auto (default): follows process locale; prefer explicit zh-CN when the user prompt is Chinese.Do not use --force for existing projects unless the user explicitly confirms overwriting harness files.
For greenfield, fill harness/context/project-brief.md from the user idea and discovered facts.
For brownfield, scaffold the same minimal core first. Add extra context files later only when repository evidence shows they remove real ambiguity.
For existing-harness, update only missing or clearly stale harness files. Preserve existing AGENTS.md, README, CI, tests, and code conventions unless the user confirms a rewrite.
Do not expand the harness just because templates exist.
Workflow skills may guide how the agent works, but local gates, commands, guardrails, and verification evidence remain authoritative.
Use this ownership model for team projects:
AGENTS.md, harness/context/, harness/controls/, harness/tools/, harness/guardrails/, and harness/scripts/.harness/runs/ as task-owned records. Commit run directories only when they are useful for review, audit, onboarding, future context, architecture decisions, or complex bug investigations.evaluation.md instead of directly editing canonical harness files.AGENTS.md and canonical harness/ directories.If the project wants to keep most run records out of version control, recommend ignoring harness/runs/* while preserving harness/runs/.gitkeep, then force-add selected run directories when they matter.
For raw product ideas, vague project concepts, or early feature directions, use brainstorming before writing a spec. Save the one-page design in the active run directory when the user confirms:
harness/runs/YYYY-MM-DD-short-task-name/design.md
The refined design should define the problem statement, recommended direction, key assumptions, MVP scope, not-doing list, and open questions.
For greenfield, a one-sentence idea should normally produce workflow.md, design.md, and an executable spec.md. Do not silently choose product shape, content scope, information architecture, technology stack, or core implementation approach. If product, technology, or architecture decisions are missing, ask the user before planning implementation, or make choosing them the first non-coding task.
For non-trivial tasks, use writing-specs. Save the resulting task contract in the active run directory:
harness/runs/YYYY-MM-DD-short-task-name/spec.md
The spec must define objective, scope, non-goals, assumptions, acceptance criteria, verification, required evidence, context updates, and open questions. Do not use the spec step to generate the implementation plan.
Before moving to planning, block on unresolved decisions that would materially affect implementation:
If the user does not want to decide yet, record the decision in Open Questions and make it the first task in plan.md. Do not write application code before that decision task is resolved.
After the spec is clear, use writing-plans. Save the implementation plan in:
harness/runs/YYYY-MM-DD-short-task-name/plan.md
Tasks should be small, ordered by dependency, and include verification steps.
Do not proceed to execution if spec.md or plan.md contains unresolved blocking questions. Resolve them with the user or execute only the explicit non-coding decision task.
Implement against the active run only:
AGENTS.mdworkflow.md and design.md when presentspec.md and plan.mdharness/context/harness/controls/gates.mdharness/guardrails/ before editspython3 harness/scripts/check_run.py harness/runs/<run> --stage before-implementation --tier <xs|standard|full> when an active run exists and the checker is availableRun commands from harness/tools/commands.md and record results in execution-log.md.
Before claiming completion, run python3 harness/scripts/check_run.py harness/runs/<run> --stage before-completion --tier <xs|standard|full> when an active run exists and the checker is available. If the checker cannot be run, record the reason in execution-log.md.
Each task run should use the smallest tier that safely controls the work.
XS:
harness/runs/YYYY-MM-DD-short-task-name/
├── execution-log.md
└── evaluation.md
Standard:
harness/runs/YYYY-MM-DD-short-task-name/
├── workflow.md
├── spec.md
├── plan.md
├── execution-log.md
└── evaluation.md
Full:
harness/runs/YYYY-MM-DD-short-task-name/
├── input.md
├── workflow.md
├── design.md
├── spec.md
├── plan.md
├── execution-log.md
├── review.md
└── evaluation.md
Use design.md for new feature or product direction work. Legacy runs may still contain idea.md. Record changed files, commands run, verification results, review findings, unresolved risks, and whether each acceptance criterion passed.
After each run, review whether the harness itself needs improvement. Treat this as controlled maintenance of canonical harness files:
For normal feature or bugfix runs, propose harness updates first and apply them only when the user approves or the project workflow explicitly allows harness maintenance. When the user asks to initialize, refine, or improve the harness, update the relevant harness files directly from evidence.
Update harness files, not unrelated application code, during this improvement phase. Keep changes small and traceable to the latest run, repository facts, or user-confirmed decisions.
Read references/related-skills.md when deciding how this skill composes with existing skills. In short:
brainstorming for the Intake layer when a request is still exploratory.writing-specs for the Spec layer.writing-plans for the Plan layer.npx claudepluginhub wcxcw/harness-skills --plugin harness-skillsGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.