SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsharness-zh

harness-zh

Design & creation

View repository

Updated 10-16 01:38

About this skill

Harness — Agent Team & Skill Architect

Build a Harness for a specific domain/project, define the role of each Agent, and generate the meta skill of the Skill used by the Agent (meta skill).

Core principles:

  1. Generate Agent definitions (.claude/agents/) and Skill (.claude/skills/）。
  2. Use the Agent Team as the default execution mode.
  3. Register the Harness pointer in CLAUDE.md. — Record only the minimal pointer (trigger rules + change history) so that the orchestrator Skill is automatically triggered in a new session.
  4. A Harness is not a fixed object, but a continuously evolving system. — Absorb feedback after each execution and continuously update the Agent, Skill, and CLAUDE.md.

Workflow

Phase 0: Current State Audit

When the Harness Skill is triggered, first confirm the current state of the existing Harness.

  1. Read 项目/.claude/agents/、项目/.claude/skills/、项目/CLAUDE.md

  2. Branch the execution mode based on the current state:

    • Fresh build: The Agent/Skill directory does not exist or is empty → Execute the full process starting from Phase 1
    • Existing extension: There is already a Harness and new Agent/Skill needs to be added → Execute only the necessary Phases according to the Phase selection matrix below
    • Operations/Maintenance: Audit, modification, or synchronization request for an existing Harness → Jump to the Phase 7-5 Operations/Maintenance workflow

    Phase selection matrix for existing extensions:

    Change type Phase 1 Phase 2 Phase 3 Phase 4 Phase 5 Phase 6
    Add Agent Skip (reuse Phase 0 results) Only determine the orchestration position Required When a dedicated Skill is needed Modify orchestrator Required
    Add/Modify Skill Skip Skip Skip Required When connection relationships change Required
    Architecture change Skip Required Only affected Agents Only affected Skills Required Required

  3. Compare the existing Agent/Skill list with the CLAUDE.md records to detect inconsistencies (drift)

  4. Summarize the audit results and report them to the user, and confirm the execution plan

Phase 1: Domain Analysis

  1. Grasp the domain/project from the user request
  2. Identify the core task types (generation, validation, editing, analysis, etc.)
  3. Based on the Phase 0 audit results, analyze conflicts/duplication with existing Agents/Skills
  4. Explore the project codebase — grasp the tech stack, data model, and main modules
  5. Detect user proficiency — Infer their technical level from contextual cues in the conversation, and adjust the tone of subsequent communication accordingly. For users with little programming experience, avoid using technical jargon without explanation.

Phase 2: Team Architecture Design

2-1. Choose Execution Mode

The Agent team is the highest-priority default. When 2 or more Agents collaborate, you must first consider whether to use an Agent team. Team members self-coordinate through direct communication (SendMessage) and a shared task list (TaskCreate), and improve result quality through discovery sharing, conflict discussion, and gap filling.

Mode When to Use Characteristics
Agent team(default) Collaboration among 2 or more people, requiring real-time coordination and feedback exchange, mutual reference to intermediate artifacts Through TeamCreate + SendMessage + TaskCreate self-coordination
Sub Agent(alternative) Single-Agent operations, when it is sufficient to return results to the main body only, when team communication overhead is too high Directly call the Agent tool, use run_in_background in parallel
Hybrid When the characteristics of each Phase differ — for example: parallel collection (Sub Agent) → consensus-based integration (team) Mix team/Sub Agent by Phase

Decision order:

  1. First consider whether it can be designed as an Agent team — 2 or more people is the default
  2. Choose Sub Agents only when team communication is structurally unnecessary (only result passing is needed) and team overhead outweighs the benefits
  3. Consider a hybrid when the characteristics of each Phase differ significantly — make the execution mode of each Phase explicit in the orchestrator

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

2-2. Choose Architecture Pattern

  1. Decompose the task into specialized domains
  2. Decide the Agent team structure (for architecture patterns, see references/agent-design-patterns.md）
    • Pipeline: sequentially dependent operations
    • Fan-out/Fan-in: parallel independent operations
    • Expert Pool: select and invoke based on the scenario
    • Generate-Verify: perform quality review after generation
    • Supervisor: a central Agent manages state and dispatches dynamically
    • Hierarchical Delegation: a superior Agent recursively delegates to subordinates

2-3. Agent Splitting Criteria

Judge by the 4 dimensions of specialization, parallelism, context, and reusability. For the detailed criteria table, see references/agent-design-patterns.md the "Agent Splitting Criteria" section in.

Phase 3: Generate Agent Definitions

All Agents must be defined as 项目/.claude/agents/{name}.md files. It is prohibited to not create Agent definition files and directly stuff roles into the Agent tool prompt. Reasons:

  • Agent definitions must exist as files so they can be reused in the next session
  • The team communication protocol must be made explicit to ensure the quality of collaboration between Agents
  • The core value of Harness lies in the separation of Agent (who) and Skill (how)

Even when using built-in types (general-purpose、Explore、Plan), also generate an Agent definition file. Built-in types are specified via the Agent tool's subagent_type parameter, while the Agent definition file carries the role, principles, and protocol.

Model settings: By default, use model: "opus"to ensure the highest reasoning quality. For low-complexity structured tasks (format conversion, template filling, data extraction, etc.), you may downgrade to model: "sonnet" to save cost. In the orchestrator, explicitly state the chosen model and its rationale for each Agent.

Task complexity Recommended model Example
High (reasoning-intensive, creative work, architecture design, QA) opus Orchestrator, analysis, synthesis judgment, quality review
Medium (following templates, structured generation) sonnet Format conversion, data extraction, template filling, simple CRUD

Team reorganization: Only one Agent team can be active per session, but you can disband the old team and form a new team between Phases. As in pipeline mode, when different Phases require different combinations of experts, first save the previous team's artifacts as files, then clean up the team and create a new team.

Define each Agent in 项目/.claude/agents/{name}.md. Required sections: core role, operating principles, input/output protocol, error handling, collaboration. In Agent team mode, also add a ## 团队通信协议 section, explicitly stating the recipients/senders of messages and the scope of work requests.

For the definition template and the full text of actual files, see references/agent-design-patterns.md in "Agent Definition Structure" as well as references/team-examples.md。

Requirements when including a QA Agent:

  • The QA Agent uses the general-purpose type (Explore is read-only and cannot execute validation scripts)
  • The core of QA is not "existence confirmation" but "cross-boundary comparison" — reading code on both sides simultaneously and comparing the shapes
  • QA is not performed once after everything is complete, but executed incrementally immediately after each module is completed（incremental QA）
  • Detailed guide: see references/qa-agent-guide.md

Phase 4: Generate Skills

Generate the Skill used by each Agent into 项目/.claude/skills/{name}/SKILL.md. For detailed authoring guidance, see references/skill-writing-guide.md。

4-1. Skill structure

skill-name/
├── SKILL.md (必需)
│   ├── YAML frontmatter (name, description 必需)
│   └── Markdown 本文
└── Bundled Resources (可选)
    ├── scripts/    - 重复/确定性作业的可执行代码
    ├── references/ - 条件加载的参考文档
    └── assets/     - 用于输出的文件（模板、图片等）

4-2. Writing the Description — proactively inducing triggers

The description is the only trigger mechanism for a Skill. Claude tends to judge whether to trigger conservatively, so the description should be written proactively ("pushy")。

Bad example: "处理 PDF 文档的 Skill" Good example: "读取 PDF 文件、提取文本/表格、合并、拆分、旋转、加水印、加密、OCR 等执行所有 PDF 作业。当提及 .pdf 文件或请求 PDF 产物时，必须使用本 Skill。"

Key points: describe both what the Skill does + the specific trigger scenarios, and distinguish it from similar situations where it should not trigger.

4-3. Principles for writing the body

Principle Explanation
Clarify the Why Do not use forceful instructions like "ALWAYS/NEVER"; instead convey the reason for doing it this way. Once an LLM understands the reason, it can make the correct judgment even in edge cases.
Stay lean The context window is a shared resource. Aim for the SKILL.md body to be within 500 lines, and delete content that does not substantially help decision-making or move it to references/.
Generalize Rather than narrow rules tailored to specific examples, the principles should be explained clearly so that the Skill can handle diverse inputs. Overfitting is prohibited.
Repeated code should be bundled If it is found that the Agent commonly writes the same script during test execution, bundle it in advance into scripts/。
Use imperative mood Use a command/instruction tone such as "Do..." or "Execute...".

4-4. Progressive Disclosure

The Skill manages context through a 3-level loading system:

Level Loading timing 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 No upper limit (scripts can be executed without loading)

Size management rules:

  • When SKILL.md approaches 500 lines, separate the details into references/, and leave a pointer in the body for "when to read that file"
  • Reference files exceeding 300 lines should include at the top a table of contents (ToC)
  • If there are variants by domain/framework, split them under references/ by domain and load only the relevant file

4-5. Skill–Agent Connection Principles

  • 1 Agent ↔ 1~N Skills (1:1 or 1:many)
  • Multiple Agents sharing the same Skill is also allowed
  • The Skill carries "how to do it", and the Agent carries "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, responsible for connecting each Agent and Skill into a single workflow and coordinating the entire team. If the Skills generated in Phase 4 define "what each Agent does and how", then the orchestrator defines "who collaborates when and in what order". For specific templates, see references/orchestrator-template.md。

Orchestrator modification when extending an existing system: When extending an existing system rather than building a new one, do not create a new orchestrator; modify the existing orchestrator. When adding a new Agent, reflect the new Agent in the team composition, task assignment, and data flow, and add trigger keywords related to the new Agent in the description.

The orchestrator mode differs depending on the execution mode selected in Phase 2-1. For detailed templates of orchestrator modes (Agent team/sub-Agent/hybrid), see references/orchestrator-template.md。

5-1. Data Transfer Protocol

Explicitly state within the orchestrator how data is transferred between Agents. Recommended combinations: for team mode, "task-based + file-based + message-based"; for sub-Agent mode, "return-value-based + file-based". For file-based transfer, save intermediate artifacts under _workspace/ , with the filename convention {phase}_{agent}_{artifact}.{ext}. Only the final artifacts are output to the user-specified path.

For detailed explanations of each strategy, see references/orchestrator-template.md。

5-2. Error Handling

Include an error handling policy within the orchestrator. Core principles: if it still fails after 1 retry, skip that result and continue (noting the omission in the report); do not delete conflicting data, but list the sources side by side.

For the strategy table by error type, see references/orchestrator-template.md the "Error Handling" section in .

5-3. Team Size Guidelines

Task scale Recommended number of members Jobs per person
Small scale (5~10 jobs) 2~3 people 3~5 jobs
Medium scale (10~20 jobs) 3~5 people 4~6 jobs
Large scale (more than 20 jobs) 5~7 people 4~5 jobs

The more team members, the greater the coordination overhead. 3 focused members are better than 5 unfocused members.

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

After the Harness is built, register a minimal pointer in the project's CLAUDE.md . CLAUDE.md is loaded in every new session, so you only need to record the existence of the Harness and the trigger rules, and leave the rest to the orchestrator Skill.

CLAUDE.md template:

## Harness：{领域名}

**目标：** {Harness 的核心目标一行}

**触发：** 当收到与 {领域} 相关的作业请求时，使用 `{orchestrator-skill-name}` Skill。简单问题可直接回答。

**变更历史：**
| 日期 | 变更内容 | 对象 | 事由 |
|------|----------|------|------|
| {YYYY-MM-DD} | 初始构建 | 全体 | - |

Content that should not go into CLAUDE.md: Agent list, Skill list, directory structure, execution rule details. Reason: the Agent/Skill lists are managed by the orchestrator Skill and .claude/agents/、.claude/skills/ , so putting them in CLAUDE.md is merely duplication. CLAUDE.md carries only the pointer (trigger rules) + change history。

5-5. Subsequent job support

The orchestrator must handle not only the initial execution but also subsequent jobs. The following three points must be ensured:

1. Include subsequent keywords in the orchestrator description: With only the keywords generated initially, subsequent requests cannot be triggered. The description must include the following subsequent expressions: "re-execute", "run again", "update", "modify", "supplement", "re-execute only for {part}", "based on previous results", "improve results".

2. Append a context confirmation step to orchestrator Phase 1: At the start of the workflow, confirm whether existing artifacts exist, and decide the execution mode accordingly:

  • _workspace/ exists + user requests partial modification → Partial rerun
  • _workspace/ exists + user provides new input → Fresh execution(remove old _workspace)
  • _workspace/ does not exist → Initial execution

3. Include repeated invocation guidance in Agent definitions: In each Agent .md file, explicitly state "behavior when previous artifacts exist".

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

Phase 6: Validation and testing

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

6-1. Structural validation

  • Confirm that all Agent files are in the correct locations
  • Validate the Skill's frontmatter (name, description)
  • Confirm the consistency of references between Agents
  • Confirm that no command was generated

6-2. Validate by execution mode

  • Agent team: confirm whether the communication paths between members, job dependencies, and team size are appropriate
  • Sub-agent: confirm each Agent's input/output connections,run_in_background settings, and return value collection logic
  • Hybrid: confirm whether each Phase's execution mode is explicitly stated in the orchestrator, and whether data transfer at Phase boundaries is uninterrupted

6-3. Skill execution testing

Perform actual runtime tests on each generated Skill. Core flow: write 2–3 realistic test prompts → run with-skill / without-skill in parallel for comparison → qualitative/quantitative result evaluation → iterative improvement → repeat code bundling.

For detailed test prompt writing, evaluation methods, and the iterative improvement loop, see references/skill-testing-guide.md。

6-4. Trigger validation

Validate whether each Skill's description is triggered correctly:

  1. Should-trigger queries(8–10) — Various expressions that should trigger the Skill (formal/casual, explicit/implicit)
  2. Should-NOT-trigger queries(8–10) — "near-miss" queries with similar keywords that should match other tools/Skills

Key points for writing near-misses: An obviously irrelevant query like "write a Fibonacci function" has no testing value. Ambiguous boundary queries are good test cases. At this stage, also confirm trigger conflicts with existing Skills.

6-5. Dry-run testing

  • Review whether the Phase order of the orchestrator Skill is reasonable
  • Confirm there are no empty segments (dead links) along the data transfer path
  • Confirm whether each Agent's input matches the previous Phase's output
  • Confirm whether the fallback path corresponding to each error scenario is executable

6-6. Writing test scenarios

  • Append to the orchestrator Skill the ## 测试场景 section
  • Describe at least 1 normal flow + 1 error flow

Phase 7: Harness evolution

The Harness is not a static artifact that ends after one generation, but a system that continuously evolves based on user feedback.

7-1. Collect feedback after execution

After each Harness execution is complete, request feedback from the user. If there is no feedback, let it pass. Not mandatory, but an opportunity must be provided.

7-2. Feedback implementation paths

Depending on the feedback type, the modification target differs:

Feedback type Modification target Example
Artifact quality The corresponding Agent's Skill "Analysis is too superficial" → append depth standards to the Skill
Agent role Agent definition .md "Security review is also needed" → add a new Agent
Workflow order Orchestrator Skill "Validation should come first" → adjust the Phase order
Team composition Orchestrator + Agent "These two can be merged" → merge Agents
Trigger omission Skill description "It doesn't work with this expression" → extend the description

7-3. Change history

Record all changes to CLAUDE.md's change history table (the same table as the "Change History" section in the Phase 5-4 template). Through this history, you can track the direction in which the Harness is evolving and prevent regression.

7-4. Evolution triggers

Evolve not only when the user explicitly says "modify the Harness," but also proactively propose evolution in the following cases:

  • When the same type of feedback appears repeatedly 2 or more times
  • When a certain Agent repeatedly fails in a pattern
  • When observing the user bypassing the orchestrator to handle tasks manually

7-5. Operations/Maintenance Workflow

Systematically perform inspection, modification, and synchronization of an existing Harness. When entering the "Operations/Maintenance" branch in Phase 0, follow this workflow.

Step 1: Current State Audit

  • Compare the .claude/agents/ file list with the Agent configuration in the orchestrator Skill → generate a list of inconsistencies
  • Compare the .claude/skills/ directory list with the Skill configuration in the orchestrator Skill → generate a list of inconsistencies
  • Report the audit results to the user

Step 2: Incremental Addition/Modification

  • Execute Agent addition/modification/deletion and Skill addition/modification/deletion according to the user's request
  • Make only one change at a time, and immediately execute Step 3 (Synchronization) after each change

Step 3: Update CLAUDE.md Change History

Step 4: Validate Changes

  • Validate the modified Agent/Skill structure (Phase 6-1 baseline)
  • If the scope of modification affects triggering, perform trigger validation (Phase 6-4 baseline)
  • For large-scale changes, also execute Phase 6-3 (execution test) and 6-5 (dry-run)
  • Finally, confirm whether CLAUDE.md matches the actual files

Deliverables Checklist

After generation is complete, confirm the following:

  • 项目/.claude/agents/ —— Agent definition files must be generated(files must be generated even when using built-in types)
  • 项目/.claude/skills/ —— Skill file group (SKILL.md + references/)
  • 1 orchestrator Skill (including data flow + error handling + test scenarios)
  • Explicitly state the execution mode (choose one of Agent team / sub-Agent / hybrid; if hybrid, annotate the mode for each Phase)
  • Explicitly state model parameter in all Agent calls (default opus; sonnet may be used for low-complexity tasks)
  • .claude/commands/ —— Do not generate any content
  • No conflict with existing Agents/Skills
  • Skill description is written in a proactive ("pushy") manner —— includes follow-up task keywords
  • SKILL.md body is within 500 lines; if exceeded, separate into references/
  • Complete execution validation with 2~3 test prompts
  • Complete trigger validation (should-trigger + should-NOT-trigger)
  • Register the Harness pointer in CLAUDE.md(trigger rules + change history)
  • Record Agent/Skill additions/deletions/modifications in the CLAUDE.md change history
  • Include a context confirmation step in orchestrator Phase 1(distinguish first run/subsequent run/partial rerun)

References

  • Harness patterns:references/agent-design-patterns.md
  • Existing Harness examples (including full text of actual files):references/team-examples.md
  • Orchestrator template:references/orchestrator-template.md
  • Skill authoring 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 —— includes integration consistency validation methodology (general + multi-domain examples), boundary bug patterns, QA Agent definition template