AgentSkillsCN

two-agent-harness

此技能基于“长期运行代理的有效工具”研究，搭建完整的双代理开发系统。创建初始化代理（用于项目规划）和编码代理（用于增量实施），并配备执行钩子和进度跟踪基础设施。在用户要求“搭建双代理系统”、“安装代理工具”、“配置 Opus 委托”或希望实施双代理架构模式时使用。

SKILL.md
--- frontmatter
name: two-agent-harness
description: This skill sets up a complete two-agent development system based on the "Effective Harnesses for Long-Running Agents" research. It creates initializer-agent (for project planning) and coding-agent (for incremental implementation), along with enforcement hooks and progress tracking infrastructure. Use when users ask to "set up two-agent system", "install agent harness", "configure Opus delegation", or want to implement the two-agent architecture pattern.

Two-Agent Harness System Setup

This skill installs a complete two-agent development architecture that separates planning from implementation. Based on the research paper "Effective Harnesses for Long-Running Agents", it enables Claude Code to handle complex, multi-session projects with proper progress tracking and state recovery.

System Overview

The two-agent harness creates a workflow where:

  • •Opus (you) orchestrates and delegates - never implements directly
  • •Initializer Agent (sonnet) breaks down projects into 200+ trackable features
  • •Coding Agent (sonnet) implements features one at a time with quality assurance

Auto-Setup Process

To set up the complete two-agent system, execute the setup script:

bash
bash ~/.claude/skills/two-agent-harness/scripts/setup-two-agent-system.sh

This script will automatically:

  1. •Create agent definitions in ~/.claude/agents/
  2. •Install enforcement hooks in ~/.claude/hooks/
  3. •Add reference documentation to ~/.claude/REFRENCE/TWO-AGENT-HARNESS/
  4. •Configure ~/.claude/CLAUDE.md with delegation instructions
  5. •Validate the installation

What Gets Installed

Agents (~/.claude/agents/)

AgentModelPurpose
initializer-agentsonnetBreaks down complex tasks into feature-list.json with 200+ features
coding-agentsonnetImplements features systematically, one at a time

Hooks (~/.claude/hooks/)

HookEventAction
pre-tool-guard.shPreToolUseBlocks Opus from editing src/ files, updates heartbeat
post-tool-guard.shPostToolUseReminds about progress updates after code changes
session-progress-check.shSessionStartDetects pending features and abnormal exits
verify-coding-agent.shSubagentStopVerifies coding-agent updated progress files
session-end.shSessionEndMarks session complete for recovery detection

Reference Documentation (~/.claude/REFRENCE/TWO-AGENT-HARNESS/)

Nine comprehensive guides covering:

  • •Framework overview and philosophy
  • •Agent specifications
  • •Feature tracking system
  • •Hook system
  • •Git integration
  • •Session workflow
  • •Testing strategy
  • •File structure

Post-Installation Usage

Starting a New Project

code
User: "Initialize this as a new project with comprehensive feature breakdown"
Opus: [Invokes initializer-agent via Task tool]
Result: Creates feature-list.json with 200+ features, init.sh, and progress tracking

Implementing Features

code
User: "Implement the next feature"
Opus: [Invokes coding-agent via Task tool]
Result: Implements one feature, updates progress, commits changes

Delegation Rules

SituationAgent to Use
New project, complex breakdowninitializer-agent
Implement feature from feature-listcoding-agent
Need codebase understandingExplore (built-in)
Quick fix (<5 min), explicit requestDo directly (say "quick fix" or "direct edit")

Bypass Keywords

When you need to bypass the enforcement hooks, include these keywords in your prompt:

  • •"quick fix" - Single line change
  • •"direct edit" - User explicitly requested direct editing
  • •"no progress" - No feature-list.json exists yet

Project Progress Files

When a project is initialized, these files are created in .claude/progress/:

  • •feature-list.json - Comprehensive feature breakdown with status tracking
  • •session-state.json - Session state for recovery detection
  • •claude-progress.txt - Human-readable progress log

Templates

The skill includes templates for new projects in assets/templates/:

  • •feature-list-template.json - Starting point for feature breakdown
  • •session-state-template.json - Initial session state
  • •init-template.sh - Environment setup script

Troubleshooting

Agents Not Appearing in Task Tool

Verify agents are in ~/.claude/agents/:

bash
ls -la ~/.claude/agents/

Hooks Not Triggering

Check hook configuration in ~/.claude/settings.json and verify hooks are executable:

bash
chmod +x ~/.claude/hooks/*.sh

Recovery After Crash

If a session ended abnormally, the session-progress-check.sh hook will detect it on next startup and prompt you to invoke coding-agent for recovery.

Reference Documentation

For detailed information, see the reference files:

  • •references/two-agent-framework-overview.md - Full system design
  • •references/initializer-agent-spec.md - Initializer agent details
  • •references/coding-agent-spec.md - Coding agent details
  • •references/hook-system.md - Hook configuration and behavior
  • •references/feature-tracking-system.md - Progress tracking details
  • •references/session-workflow.md - Session lifecycle management