harness

Harness — Agent Team & Skill Architect

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

Core principles:

1. Create 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 the minimal pointer (trigger rule + change history) so the orchestrator skill is triggered in new sessions.
4. A harness is an evolving system, not a fixed artifact. — Incorporate feedback after every run and continuously update agents, skills, and CLAUDE.md.

Workflow

Phase 0: Status Audit

When the harness skill is triggered, the first thing to do is 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: agent/skill directories are missing or empty → run the full sequence from Phase 1.
   • Extend existing: a harness 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/fix/sync an existing harness → go to the Phase 7-5 operations/maintenance workflow.

   Phase Selection Matrix when extending an existing harness:

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

3. Compare the existing agent/skill list with the CLAUDE.md records to detect drift.

4. Summarize the audit result to 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 result, 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 skill level — infer the technical level from contextual cues in the conversation (terms used, level of questions) and adjust the communication tone accordingly. For users with little coding experience, do not use terms like "assertion" or "JSON schema" without explanation.

Phase 2: Team Architecture Design

2-1. Choose the Execution Mode

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

Mode	When to use	Characteristics
Agent team (default)	2+ collaborators, needs real-time coordination/feedback exchange, cross-references intermediate artifacts	Self-coordinates via TeamCreate + SendMessage + TaskCreate
Sub-agent (alternative)	Single-agent work, returning only the result to main is sufficient, team-communication overhead would be excessive	Calls the Agent tool directly, parallelizes with run_in_background
Hybrid	When phases have different characteristics — e.g. parallel gathering (sub) → consensus-based integration (team)	Mixes team/sub per phase

Decision order:

1. First check whether the design can use an agent team — the default for 2+ agents.
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 differ markedly in nature, consider a hybrid — declare each phase's execution mode in the orchestrator.

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

2-2. Choose an Architecture Pattern

1. Decompose the work into specialist areas.
2. Decide the agent team structure (see references/agent-design-patterns.md for architecture patterns):
   • Pipeline: sequentially dependent tasks
   • Fan-out/Fan-in: parallel independent tasks
   • Expert pool: situation-based selective invocation
   • Producer-Reviewer: produce, then quality-review
   • Supervisor: a central agent manages state and dynamically distributes work
   • Hierarchical delegation: a higher agent recursively delegates to lower agents

2-3. Agent Separation Criteria

Judge along 4 axes: specialization, parallelism, context, and reusability. For the detailed criteria table, see "Agent Separation Criteria" in references/agent-design-patterns.md. Overlap/reuse review against existing agents is handled in Phase 3-0.

Phase 3: Create Agent Definitions

3-0. Review Overlap with Existing Agents

Before creating a new agent, check for overlap with existing agents in project/.claude/agents/. When a harness is rebuilt repeatedly, agents with overlapping roles tend to accumulate 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 a role directly into the Agent tool's prompt without an agent definition file is prohibited. Reasons:

• An agent definition must exist as a file to be reusable in the next session.
• The team communication protocol must be explicit to guarantee collaboration quality between agents.
• The core value of a harness is the separation of agent (who) and skill (how).

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

Model setting: Every agent uses model: "opus". Always specify the model: "opus" parameter when calling the Agent tool. A harness's quality is directly tied to its 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 different specialist combinations are needed per phase (as in the pipeline pattern), save the previous team's artifacts to 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 message recipients/senders and the scope of work requests.

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

Requirements when including a QA agent:

• The QA agent must use the general-purpose type (Explore is read-only and cannot run validation scripts).
• The heart of QA is not "existence checking" but "cross-boundary comparison" — read the API response and the front-end hooks together and compare shapes.
• QA runs 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: Create Skills

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

4-0. Review Overlap with Existing Skills

Before creating a new skill, check for overlap with existing skills in project/.claude/skills/. When a harness is rebuilt repeatedly, skills with overlapping functionality tend to accumulate 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 docs loaded conditionally
    └── assets/     - files used in output (templates, images, etc.)

4-2. Writing the Description — Actively Encourage Triggering

The description is the skill's only trigger 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: 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 it should be done that way. When an LLM understands the reason, it judges correctly even in edge cases.
Keep it lean	The context window is a shared resource. Aim for under 500 lines in the SKILL.md body; delete content that does not earn its weight or move it to references/.
Generalize	Rather than narrow rules that fit only specific examples, explain the principle so it handles diverse inputs. No overfitting.
Bundle repeated code	When agents commonly write the same script during test runs, pre-bundle it in scripts/.
Write imperatively	Use an imperative/directive tone ("do X", "perform Y").

4-4. Progressive Disclosure

A skill manages context with a 3-stage loading system:

Stage	Loaded when	Size target
Metadata (name + description)	Always 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 details 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, split under references/ by domain so only the relevant file is loaded.

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

4-5. Skill-Agent Linking Principles

• 1 agent ↔ 1~N skills (1:1 or 1:many)
• A skill shared by multiple agents is also possible.
• A skill holds "how it is done," an agent holds "who does it."

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

Phase 5: Integration and Orchestration

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

Updating the orchestrator when extending an existing harness: For an extension 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 depends on the execution mode chosen in Phase 2-1:

5-0. Orchestrator Patterns (per mode)

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

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

Sub-agent pattern (alternative): The orchestrator calls sub-agents directly with the Agent tool. Parallel execution uses run_in_background: true; results return only to main. Use 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 artifact

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

• Parallel gathering (sub) → consensus integration (team): gather independent material in parallel with sub-agents in Phase 2 → form a team in Phase 3 for discussion/consensus-based integration.
• Team creation (team) → validation (sub): a team produces a draft in Phase 2 → a single sub-agent validates independently in Phase 3.
• Team reconfiguration between phases: TeamDelete then a new TeamCreate per phase, with sub-agent calls inserted in between.

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

5-1. Data-Passing Protocol

Within the orchestrator, specify how data is passed between agents:

Strategy	Method	Applicable mode	Suitable when
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, self-requested work
File-based	Write and read files at agreed paths	Team + Sub	Large data, structured artifacts, audit trail needed
Return-value-based	The Agent tool's return message	Sub	Main directly collects sub-agent results

Recommended combination (team mode): task-based (coordination) + file-based (artifacts) + message-based (real-time communication) Recommended combination (sub mode): return-value-based (result collection) + file-based (large artifacts) Hybrid: apply the combination matching each phase's execution mode.

Rules for file-based passing:

• 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 final artifacts to the user-specified path; preserve intermediate files (_workspace/) for later validation/audit trail.

5-2. Error Handling

Include an error-handling policy within the orchestrator. Core principles: retry once, and if it fails again proceed without that result (note the omission in the report); do not delete conflicting data — keep it with its source attribution.

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. 3 focused members beat 5 scattered ones.

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

After completing the harness configuration, register a minimal pointer in the project's CLAUDE.md. Since CLAUDE.md is loaded every new session, recording just the harness's existence and trigger rule lets the orchestrator skill handle the rest.

CLAUDE.md template:

## Harness: {domain name}

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

**Trigger:** For {domain}-related work requests, 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, skill list, directory structure, detailed execution rules. Reasons: the agent/skill lists are managed by the orchestrator skill and by .claude/agents/, .claude/skills/, so they would be duplicates. The directory structure can be checked directly from the file system. CLAUDE.md holds only the pointer (trigger rule) + change history.

5-5. Support for Follow-up Work

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

1. Include follow-up keywords in the orchestrator description: Initial-creation keywords alone will not trigger follow-up requests. Follow-up phrasings to include in the description:

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

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

• _workspace/ exists + user requests a partial fix → partial rerun (re-invoke only the relevant agent)
• _workspace/ exists + 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 agent definitions: Specify "behavior when a previous artifact exists" in each agent .md file:

• If a previous result file exists, read it and incorporate improvements.
• If user feedback is given, fix only that 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. See references/skill-testing-guide.md for the detailed testing methodology.

6-1. Structure Validation

• Confirm all agent files are in the correct location.
• Validate skill frontmatter (name, description).
• Confirm cross-reference consistency between agents.
• Confirm no commands were created.

6-2. Per-Mode Validation

• Agent team: confirm inter-member communication paths, task dependencies, and team-size appropriateness.
• Sub-agent: confirm each agent's input/output wiring, run_in_background settings, and return-value collection logic.
• Hybrid: confirm each phase's execution mode is declared in the orchestrator and that data passing is not broken at phase boundaries (when switching team → sub, confirm the team's artifact connects as 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 per skill. Write them as concrete, natural sentences an actual user might type.

2. Run a With-skill vs Without-skill comparison — if possible, run with and without the skill in parallel to confirm the skill's added value. Spawn agents in pairs:

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

3. Evaluate the results — assess artifact quality qualitatively (user review) + quantitatively (assertion-based). For objectively verifiable artifacts (file creation, data extraction, etc.), define assertions; for subjective ones (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 a meaningful improvement.

5. Bundle repeated patterns — when agents commonly write the same code during test runs (e.g. every test generates 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 phrasings 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 is more 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 check for trigger conflicts with existing skills at this stage.

6-5. Dry-Run Test

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

6-6. Write Test Scenarios

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

Phase 7: Harness Evolution

A harness is not a static artifact you make once and forget. It is a system that keeps evolving with user feedback.

7-1. Collect Feedback After Each Run

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

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

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

7-2. Feedback Routing

The modification target differs by feedback type:

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

7-3. Change History

Record every change in CLAUDE.md's change history table (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 on insufficient output-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 prevent regression.

7-4. Evolution Triggers

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

• When the same type of feedback repeats 2+ times.
• When a pattern of repeated agent failure is found.
• When the user is observed bypassing the orchestrator and working manually.

7-5. Operations/Maintenance Workflow

Systematically perform checks/fixes/syncs of an existing harness. Follow this workflow when Phase 0 branched into "operations/maintenance."

Step 1: Status audit

• Compare the .claude/agents/ file list with the orchestrator skill's agent composition → produce a mismatch list.
• Compare the .claude/skills/ directory list with the orchestrator skill's skill composition → produce a mismatch list.
• Report the audit result to the user.

Step 2: Incremental add/modify

• Per user request, add/modify/delete agents and add/modify/delete skills.
• Change one thing at a time; immediately run Step 3 (sync) after each change.

Step 3: Update CLAUDE.md change history

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

Step 4: Validate the change

• Structure-validate the modified agents/skills (Phase 6-1 criteria).
• If the change scope affects triggers, run trigger validation (Phase 6-4 criteria).
• For large changes (architecture change, adding/removing 3+ agents), also run Phase 6-3 (execution test) and 6-5 (dry run).
• Final check that CLAUDE.md and the actual files match.

Deliverables Checklist

Confirm after creation:

• project/.claude/agents/ — agent definition files created (required) (a file is required even for built-in types)
• project/.claude/skills/ — skill files (SKILL.md + references/)
• 1 orchestrator skill (with data flow + error handling + test scenarios)
• Execution mode declared (agent team / sub-agent / hybrid; for hybrid, record the per-phase mode)
• model: "opus" parameter specified on all Agent calls
• 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 created
• No conflicts with existing agents/skills
• Skill descriptions written aggressively ("pushy") — including follow-up keywords
• SKILL.md body within 500 lines; split into references/ if exceeded
• Execution validated with 2~3 test prompts
• Trigger validation (should-trigger + should-NOT-trigger) completed
• Harness pointer registered in CLAUDE.md (trigger rule + change history)
• Agent/skill add/delete/modify recorded in the CLAUDE.md change history
• Context-check step in orchestrator Phase 1 (distinguish initial/follow-up/partial rerun)

References

• Harness patterns: references/agent-design-patterns.md
• Existing harness examples (with full real files): references/team-examples.md
• Orchestrator template: references/orchestrator-template.md
• Skill writing guide: references/skill-writing-guide.md — authoring patterns, examples, data schema standard
• Skill testing guide: references/skill-testing-guide.md — testing/evaluation/iterative-improvement methodology
• QA agent guide: references/qa-agent-guide.md — reference 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 real bug cases found in actual projects.