harness

name

harness

description

Configures a harness. A meta-skill that defines specialized agents and creates the skills those agents will use. Use it when: (1) the user asks to 'configure a harness' or 'build a harness', (2) the user asks for 'harness design' or 'harness engineering', (3) building a harness-based automation system for a new domain/project, (4) restructuring or extending a harness configuration, (5) operating/maintaining an existing harness, e.g. 'harness checkup', 'harness audit', 'harness status', or 'agent/skill sync'.

Harness — Agent Team & Skill Architect

A meta-skill that configures a harness tailored to a domain/project, defines the role of each agent, and creates the skills the agents will use.

Core principles:

1. Generate agent definitions (.claude/agents/) and skills (.claude/skills/).
2. Use agent teams as the default execution mode.
3. Register a harness pointer in CLAUDE.md. — Record only a minimal pointer (trigger rules + change history) so the orchestrator skill is triggered in new sessions.
4. A harness is an evolving system, not a fixed artifact. — After every run, incorporate feedback and continuously update the agents, skills, and CLAUDE.md.

Workflow

Phase 0: Status Audit

When the harness skill is triggered, the very first step is to check the existing harness status.

1. Read project/.claude/agents/, project/.claude/skills/, and project/CLAUDE.md

2. Branch the execution mode based on the status:

   • New build: the agents/skills directories are absent or empty → run the full pipeline from Phase 1
   • Extending an existing harness: a harness already exists and there is a request to add new agents/skills → run only the necessary phases per the Phase Selection Matrix below
   • Operations/maintenance: a request to audit, modify, or sync an existing harness → move to the Phase 7-5 operations/maintenance workflow

   Phase Selection Matrix for extending an existing harness:

   Change type	Phase 1	Phase 2	Phase 3	Phase 4	Phase 5	Phase 6
   Add an agent	Skip (reuse Phase 0 results)	Placement decision only	Required (incl. 3-0)	If a dedicated skill is needed (incl. 4-0)	Modify the orchestrator	Required
   Add/modify a skill	Skip	Skip	Skip	Required (incl. 4-0)	If connections change	Required
   Architecture change	Skip	Required	Only affected agents (incl. 3-0)	Only affected skills (incl. 4-0)	Required	Required

3. Cross-check the existing agent/skill lists against the CLAUDE.md records to detect drift

4. Summarize the audit results for the user and confirm the execution plan

Phase 1: Domain Analysis

1. Identify the domain/project from the user request
2. Identify the core task types (creation, validation, editing, analysis, etc.)
3. Based on the Phase 0 audit results, analyze conflicts/overlaps with existing agents/skills
4. Explore the project codebase — identify the tech stack, data models, and key modules
5. Detect the user's proficiency — gauge the user's technical level from contextual cues in the conversation (terminology used, level of questions) and adjust the communication tone accordingly. Do not use terms like "assertion" or "JSON schema" without explanation for users with little coding experience.

Phase 2: Team Architecture Design

2-1. Selecting the Execution Mode

Agent teams are the top-priority default. Whenever two or more agents collaborate, always consider an agent team first. Members self-coordinate through direct peer communication (SendMessage) and a shared task list (TaskCreate); sharing discoveries, debating conflicts, and filling gaps all raise the quality of the result.

Mode	When to use	Characteristics
Agent team (default)	Two or more collaborators, real-time coordination/feedback exchange needed, mutual reference of intermediate artifacts	Self-coordinate via TeamCreate + SendMessage + TaskCreate
Sub-agent (alternative)	Single-agent work, where returning only the result to main suffices, when team-communication overhead is excessive	Call the Agent tool directly; parallelize with run_in_background
Hybrid	When phases have different characteristics — e.g. parallel collection (sub) → consensus-based integration (team)	Mix teams and sub-agents on a per-phase basis

Decision order:

1. First consider whether the design can be done with an agent team — if there are two or more agents, that is the default
2. Choose sub-agents only when team communication is structurally unnecessary (result hand-off only) and the team overhead outweighs the benefit
3. If phases have markedly different characteristics, consider a hybrid — specify each phase's execution mode in the orchestrator

For the detailed comparison table and the per-pattern decision tree, see "Execution Modes" in references/agent-design-patterns.md.

2-2. Selecting the Architecture Pattern

1. Decompose the work into specialized areas
2. Decide the agent team structure (for architecture patterns, see references/agent-design-patterns.md)
   • Pipeline: sequentially dependent tasks
   • Fan-out/fan-in: parallel independent tasks
   • Expert pool: situational selective invocation
   • Generate-validate: generate, then inspect quality
   • Supervisor: a central agent manages state and dynamically distributes work
   • Hierarchical delegation: a higher-level agent recursively delegates to lower levels

2-3. Criteria for Splitting Agents

Decide along four axes: specialization, parallelism, context, and reusability. For the detailed criteria table, see "Criteria for Splitting Agents" in references/agent-design-patterns.md. Reviewing overlap/reuse with existing agents is covered in Phase 3-0.

Phase 3: Generating Agent Definitions

3-0. Reviewing Overlap with Existing Agents

Before creating a new agent, check for overlap with the existing agents in project/.claude/agents/. When you build harnesses repeatedly, it is easy to accumulate agents with overlapping roles under different names.

For overlap classification criteria and reuse design, see "Agent Reuse Design" in references/agent-design-patterns.md.

Every agent must be defined as a project/.claude/agents/{name}.md file. Putting the role directly into the Agent tool's prompt without an agent definition file is prohibited. Reasons:

• An agent definition must exist as a file so it can be reused in later sessions
• The team communication protocol must be specified to guarantee the quality of collaboration between agents
• The core value of a harness is the separation of agents (who) and skills (how)

Even when using a built-in type (general-purpose, Explore, Plan), still create an agent definition file. Specify the built-in type via the Agent tool's subagent_type parameter, and put the role, principles, and protocols in the agent definition file.

Model setting: Every agent uses model: "opus". Always specify the model: "opus" parameter when calling the Agent tool. The quality of a harness is directly tied to the agents' reasoning ability, and opus guarantees the highest quality.

Team reconfiguration: Only one agent team can be active per session, but you can disband a team and form a new one between phases. When a pattern such as a pipeline needs a different mix of experts per phase, save the previous team's artifacts as files, clean up the team, and create a new one.

Define each agent in project/.claude/agents/{name}.md. Required sections: core role, working principles, input/output protocol, error handling, collaboration. In agent team mode, add a ## Team Communication Protocol section specifying the targets for receiving/sending messages and the scope of work requests.

For the definition template and full real-world file examples, see "Agent Definition Structure" in references/agent-design-patterns.md + references/team-examples.md.

Mandatory when including a QA agent:

• Use the general-purpose type for the QA agent (Explore is read-only and therefore cannot run validation scripts)
• The heart of QA is not "confirming existence" but "cross-comparison across boundaries" — read the API response and the front-end hook at the same time and compare their shapes
• Run QA not once after everything is complete, but incrementally right after each module is completed (incremental QA)
• Detailed guide: see references/qa-agent-guide.md

Phase 4: Creating Skills

Create the skills each agent will use in project/.claude/skills/{name}/SKILL.md. For the detailed authoring guide, see references/skill-writing-guide.md.

4-0. Reviewing Overlap with Existing Skills

Before creating a new skill, check for overlap with the existing skills in project/.claude/skills/. When you build harnesses repeatedly, it is easy to accumulate skills with overlapping functionality under different names.

For overlap classification criteria and generalization patterns, see "Skill Reuse Design" in references/skill-writing-guide.md.

4-1. Skill Structure

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown body
└── Bundled Resources (optional)
    ├── scripts/    - executable code for repetitive/deterministic work
    ├── references/ - reference documents loaded conditionally
    └── assets/     - files used in the output (templates, images, etc.)

4-2. Writing the Description — Drive Triggering Aggressively

The description is the skill's only triggering mechanism. Claude tends to judge triggers conservatively, so write the description aggressively ("pushy").

Bad example: "A skill that processes PDF documents" Good example: "Performs all PDF operations: reading PDF files, extracting text/tables, merging, splitting, rotating, watermarking, encrypting, OCR, and more. Whenever a .pdf file is mentioned or a PDF deliverable is requested, you must use this skill."

Key point: describe both what the skill does AND the specific trigger situations, and write it so it is distinguished from similar cases that should NOT trigger.

4-3. Body Authoring Principles

Principle	Description
Explain the Why	Instead of coercive directives like "ALWAYS/NEVER", convey why something should be done that way. When the LLM understands the reason, it judges correctly even in edge cases.
Keep it lean	The context window is a common good. Aim to keep the SKILL.md body under 500 lines; delete content that does not pull its weight or move it to references/.
Generalize	Rather than narrow rules that fit only a specific example, explain the principle so the skill can handle diverse inputs. No overfitting.
Bundle repeated code	When you find scripts that agents commonly write during test runs, pre-bundle them in scripts/.
Write in the imperative	Use an imperative/directive tone ("do", "perform").

4-4. Progressive Disclosure

A skill manages context through a three-tier loading system:

Tier	Load time	Size target
Metadata (name + description)	Always present in context	~100 words
SKILL.md body	When the skill is triggered	<500 lines
references/	Only when needed	Unlimited (scripts can run without being loaded)

Size management rules:

• When SKILL.md approaches 500 lines, split the details out into references/ and leave a pointer in the body for "when to read this file"
• For reference files over 300 lines, include a table of contents (ToC) at the top
• When there are domain/framework-specific variants, separate them by domain under references/ so only the relevant files are loaded

cloud-deploy/
├── SKILL.md (workflow + selection guide)
└── references/
    ├── aws.md    ← loaded only when AWS is selected
    ├── gcp.md
    └── azure.md

4-5. Skill-Agent Linking Principles

• One agent ↔ one to N skills (1:1 or 1:many)
• A skill shared by multiple agents is also possible
• Skills hold "how to do it"; agents hold "who does it"

For detailed authoring patterns, examples, and data schema standards, see references/skill-writing-guide.md.

Phase 5: Integration and Orchestration

The orchestrator is a special form of skill that weaves the individual agents and skills into a single workflow and coordinates the whole team. Where the individual skills created in Phase 4 define "what each agent does and how", the orchestrator defines "who collaborates, when, and in what order". For a concrete template, see references/orchestrator-template.md.

Modifying the orchestrator when extending an existing harness: When this is an extension of an existing harness rather than a new build, do not create a new orchestrator; modify the existing one. When adding an agent, reflect the new agent in the team composition, task assignment, and data flow, and add trigger keywords related to the new agent to the description.

The orchestrator pattern varies according to the execution mode selected in Phase 2-1:

5-0. Orchestrator Patterns (by mode)

Agent team pattern (default): The orchestrator forms a team with TeamCreate and assigns work with TaskCreate. Team members communicate directly via SendMessage and self-coordinate. The leader (orchestrator) monitors progress and synthesizes the results.

[Orchestrator/Leader]
    ├── TeamCreate(team_name, members)
    ├── TaskCreate(tasks with dependencies)
    ├── Members self-coordinate (SendMessage)
    ├── Collect and synthesize results
    └── Tear down the team

Sub-agent pattern (alternative): The orchestrator calls sub-agents directly with the Agent tool. Parallel execution uses run_in_background: true, and results are returned only to main. Use this when team communication is unnecessary and you want to reduce overhead.

[Orchestrator]
    ├── Agent(agent-1, run_in_background=true)
    ├── Agent(agent-2, run_in_background=true)
    ├── Wait for and collect results
    └── Produce the integrated deliverable

Hybrid pattern: Mix different modes per phase. Common combinations:

• Parallel collection (sub) → consensus integration (team): in Phase 2, collect independent material in parallel with sub-agents → in Phase 3, form a team to debate and integrate by consensus
• Team creation (team) → validation (sub): in Phase 2, the team produces a draft → in Phase 3, a single sub-agent validates independently
• Inter-phase team reconfiguration: TeamDelete per phase followed by a new TeamCreate, with sub-agent calls inserted in between

When choosing a hybrid, specify that phase's execution mode at the top of each phase section in the orchestrator (e.g. **Execution mode:** agent team).

5-1. Data Hand-off Protocol

Specify within the orchestrator how data is passed between agents:

Strategy	Method	Applicable mode	Best for
Message-based	Direct peer communication via SendMessage	Team	Real-time coordination, feedback exchange, lightweight state passing
Task-based	Share work state via TaskCreate/TaskUpdate	Team	Progress tracking, dependency management, requesting work itself
File-based	Write and read files at agreed paths	Team + sub	Large data, structured deliverables, when an audit trail is needed
Return-value-based	The Agent tool's return message	Sub	Main collects sub-agent results directly

Recommended combination (team mode): task-based (coordination) + file-based (deliverables) + message-based (real-time communication) Recommended combination (sub mode): return-value-based (collecting results) + file-based (large deliverables) Hybrid: apply the appropriate combination for each phase's execution mode

Rules for file-based hand-off:

• Create a _workspace/ folder under the working directory to store intermediate artifacts
• Filename convention: {phase}_{agent}_{artifact}.{ext} (e.g. 01_analyst_requirements.md)
• Output only the final deliverable to the user-specified path; preserve intermediate files (_workspace/) for post-hoc verification and audit trails

5-2. Error Handling

Include an error-handling policy within the orchestrator. Core principle: retry once, and if it fails again, proceed without that result (noting the omission in the report); for conflicting data, do not delete it but annotate it with its source.

For the per-error-type strategy table and implementation details, see "Error Handling" in references/orchestrator-template.md.

5-3. Team Size Guidelines

Work scale	Recommended members	Tasks per member
Small (5–10 tasks)	2–3	3–5
Medium (10–20 tasks)	3–5	4–6
Large (20+ tasks)	5–7	4–5

The more members, the greater the coordination overhead. Three focused members are better than five scattered ones.

5-4. Registering the Harness Pointer in CLAUDE.md

After the harness configuration is complete, register a minimal pointer in the project's CLAUDE.md. Because CLAUDE.md is loaded in every new session, recording only the harness's existence and trigger rules lets the orchestrator skill handle the rest.

CLAUDE.md template:

## Harness: {domain name}

**Goal:** {one line on the harness's core goal}

**Trigger:** When work related to {domain} is requested, use the `{orchestrator-skill-name}` skill. Simple questions can be answered directly.

**Change history:**
| Date | Change | Target | Reason |
|------|----------|------|------|
| {YYYY-MM-DD} | Initial configuration | All | - |

What NOT to put in CLAUDE.md: the agent list, the skill list, the directory structure, and detailed execution rules. Reasons: the agent/skill lists are managed by the orchestrator skill and by .claude/agents/ and .claude/skills/, so they would be duplicated. The directory structure can be checked directly in the file system. CLAUDE.md holds only the pointer (trigger rules) + change history.

5-5. Supporting Follow-up Work

The orchestrator must handle not only the initial run but also follow-up work. Guarantee the following three things:

1. Include follow-up keywords in the orchestrator description: The initial creation keywords alone will not trigger follow-up requests. Follow-up expressions to always include in the description:

• "run again", "rerun", "update", "modify", "supplement"
• "just redo the {sub-task} of {domain}"
• "based on the previous result", "improve the result"

2. Add a context-check step to the orchestrator's Phase 1: At the start of the workflow, check whether existing artifacts exist to determine the execution mode:

• _workspace/ exists + the user requests a partial modification → partial rerun (re-invoke only the relevant agents)
• _workspace/ exists + the user provides new input → new run (move the existing _workspace to _workspace_prev/)
• _workspace/ does not exist → initial run

3. Include re-invocation guidance in the agent definitions: Specify in each agent's .md file how it should "behave when a previous artifact exists":

• If a previous result file exists, read it and incorporate improvements
• If user feedback is given, modify only the relevant part

See the "Phase 0: Context Check" section of the orchestrator template: references/orchestrator-template.md

Phase 6: Validation and Testing

Validate the generated harness. For the detailed testing methodology, see references/skill-testing-guide.md.

6-1. Structural Validation

• Confirm every agent file is in the correct location
• Validate the skills' frontmatter (name, description)
• Confirm cross-references between agents are consistent
• Confirm no commands were generated

6-2. Validation by Execution Mode

• Agent team: confirm the communication paths between members, the task dependencies, and the appropriateness of the team size
• Sub-agent: confirm each agent's input/output connections, the run_in_background setting, and the return-value collection logic
• Hybrid: confirm each phase's execution mode is specified in the orchestrator and that data hand-off is not broken at phase boundaries (when transitioning team → sub, that the team's deliverables connect to the sub's input)

6-3. Skill Execution Testing

Perform actual execution tests for each generated skill:

1. Write test prompts — write 2–3 realistic test prompts for each skill. Write them as specific, natural sentences a real user is likely to enter.

2. Run a with-skill vs without-skill comparison — where possible, run the with-skill and without-skill executions in parallel to confirm the skill's added value. Spawn two agents per case:

   • With-skill: read the skill and perform the work
   • Without-skill (baseline): perform the same prompt without the skill

3. Evaluate the results — assess the quality of the deliverables both qualitatively (user review) and quantitatively (assertion-based). When a deliverable is objectively verifiable (file creation, data extraction, etc.), define assertions; when it is subjective (writing style, design), rely on user feedback.

4. Iterative improvement loop — when a problem is found in the test results:

   • Generalize the feedback and modify the skill (no narrow fixes that fit only a specific example)
   • Re-test after modifying
   • Repeat until the user is satisfied or there is no longer any meaningful improvement

5. Bundle repeated patterns — when you find code that agents commonly write during test runs (e.g. every test creates the same helper script), pre-bundle that code in scripts/.

6-4. Trigger Validation

Validate that each skill's description triggers correctly:

1. Should-trigger queries (8–10) — diverse expressions that should trigger the skill (formal/casual, explicit/implicit)
2. Should-NOT-trigger queries (8–10) — "near-miss" queries with similar keywords where a different tool/skill, not this one, is appropriate

Key to writing near-misses: an obviously unrelated query like "write a Fibonacci function" has no test value. A query with a blurry boundary like "extract the chart in this Excel file as a PNG" (xlsx skill vs. image conversion) makes a good test case.

Also confirm trigger conflicts with existing skills at this stage.

6-5. Dry-run Testing

• Review whether the orchestrator skill's phase order is logical
• Confirm there are no empty segments (dead links) in the data hand-off paths
• Confirm every agent's input matches the output of the previous phase
• Confirm the fallback path for each error scenario is executable

6-6. Writing Test Scenarios

• Add a ## Test Scenarios section to the orchestrator skill
• Describe at least one normal flow + one error flow

Phase 7: Harness Evolution

A harness is not a static artifact you build once and finish. It is a system that keeps evolving based on user feedback.

7-1. Collecting Post-run Feedback

After every harness run completes, ask the user for feedback:

• "Is there anything to improve in the results?"
• "Is there anything you'd like to change in the agent team composition or the workflow?"

If there is no feedback, move on. Do not force it, but always provide the opportunity.

7-2. Feedback Routing

The target to modify differs by feedback type:

Feedback type	Modification target	Example
Output quality	The relevant agent's skill	"The analysis is too superficial" → add depth criteria to the skill
Agent role	The agent definition .md	"We also need a security review" → add a new agent
Workflow order	The orchestrator skill	"Validation should come first" → change the phase order
Team composition	Orchestrator + agents	"These two could be merged" → merge the agents
Missing trigger	The skill description	"It doesn't work with this phrasing" → expand the description

7-3. Change History

Record every change in the change history table of CLAUDE.md (the same table as the "change history" section of the Phase 5-4 template):

**Change history:**
| Date | Change | Target | Reason |
|------|----------|------|------|
| 2026-04-05 | Initial configuration | All | - |
| 2026-04-07 | Added QA agent | agents/qa.md | Feedback about insufficient deliverable quality validation |
| 2026-04-10 | Added tone guide | skills/content-creator | "Too stiff" feedback |

This history lets you track how the harness has evolved and prevents regression.

7-4. Evolution Triggers

Propose evolution not only when the user explicitly says "modify the harness", but also in the following situations:

• When the same type of feedback recurs two or more times
• When a pattern of repeated agent failures is discovered
• When the user is observed bypassing the orchestrator and working manually

7-5. Operations/Maintenance Workflow

Systematically perform the checkup, modification, and synchronization of an existing harness. Follow this workflow when Phase 0 branched into the "operations/maintenance" path.

Step 1: Status audit

• Compare the file list in .claude/agents/ with the agent composition in the orchestrator skill → produce a discrepancy list
• Compare the directory list in .claude/skills/ with the skill composition in the orchestrator skill → produce a discrepancy list
• Report the audit results to the user

Step 2: Incremental addition/modification

• Per the user request, add/modify/delete agents and add/modify/delete skills
• Make changes one at a time, and run Step 3 (synchronization) immediately after each change

Step 3: Update the CLAUDE.md change history

• Record the date, change, target, and reason in the change-history table

Step 4: Validate the changes

• Structural validation of the modified agents/skills (per Phase 6-1)
• If the scope of the modification affects triggering, perform trigger validation (per Phase 6-4)
• For large-scale changes (architecture changes, adding/deleting three or more agents), also perform Phase 6-3 (execution testing) and 6-5 (dry-run)
• Final confirmation that CLAUDE.md matches the actual files

Deliverable Checklist

Confirm after generation is complete:

• project/.claude/agents/ — agent definition files must be created (a file is required even for built-in types)
• project/.claude/skills/ — skill files (SKILL.md + references/)
• One orchestrator skill (including data flow + error handling + test scenarios)
• Execution mode specified (choose among agent team / sub-agent / hybrid; if hybrid, note the mode per phase)
• model: "opus" parameter specified on every Agent call
• Overlap review with existing agents completed before creating new agents (Phase 3-0)
• Overlap review with existing skills completed before creating new skills (Phase 4-0)
• .claude/commands/ — nothing generated
• No conflicts with existing agents/skills
• Skill descriptions written aggressively ("pushy") — including follow-up work keywords
• SKILL.md body within 500 lines; if it exceeds that, split into references/
• Execution validation completed with 2–3 test prompts
• Trigger validation (should-trigger + should-NOT-trigger) completed
• Harness pointer registered in CLAUDE.md (trigger rules + change history)
• Agent/skill additions/deletions/modifications recorded in the CLAUDE.md change history
• Context-check step in the orchestrator's Phase 1 (distinguishing initial / follow-up / partial rerun)

References

• Harness patterns: references/agent-design-patterns.md
• Existing harness examples (including full real file content): references/team-examples.md
• Orchestrator template: references/orchestrator-template.md
• Skill writing guide: references/skill-writing-guide.md — authoring patterns, examples, data schema standards
• Skill testing guide: references/skill-testing-guide.md — testing/evaluation/iterative-improvement methodology
• QA agent guide: references/qa-agent-guide.md — reference this when including a QA agent in a build harness. Includes integration-consistency validation methodology, boundary bug patterns, and a QA agent definition template. Based on 7 bug cases found in a real project.