Agent skill

coordinate-subagents

Advanced subagent troubleshooting. Use when subagent calls fail, return bad output, or need voting for critical decisions.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/coordinate-subagents

SKILL.md

Subagent Troubleshooting & Advanced Patterns

Core coordination patterns are in CLAUDE.md <subagent_coordination>. This skill covers edge cases.

When to Load This Skill

  • Subagent returned malformed output twice
  • Need voting pattern for critical/irreversible decision
  • Debugging why coordination isn't working
  • Learning TOON format syntax details

Voting for Critical Decisions

For irreversible actions (deletions, deployments, security assessments), run same query 2-3 times in parallel:

xml
<!-- 3 parallel agents, same question -->
<invoke name="Task">
  <parameter name="subagent_type">Explore</parameter>
  <parameter name="model">haiku</parameter>
  <parameter name="prompt">@type: AssessAction about: "safe to delete auth_old.ts" ...</parameter>
</invoke>
<invoke name="Task">
  <parameter name="subagent_type">Explore</parameter>
  <parameter name="model">haiku</parameter>
  <parameter name="prompt">@type: AssessAction about: "safe to delete auth_old.ts" ...</parameter>
</invoke>
<invoke name="Task">
  <parameter name="subagent_type">Explore</parameter>
  <parameter name="model">haiku</parameter>
  <parameter name="prompt">@type: AssessAction about: "safe to delete auth_old.ts" ...</parameter>
</invoke>

Interpret results:

  • 3 agree → proceed confidently
  • 2 agree → proceed with caution, note dissent
  • All differ → query is ambiguous, refine and retry

Red-Flag Recovery

Symptom Action
Output exceeds budget by >30% Discard entirely, retry same prompt
Wrong format (expected TOON, got prose) Discard, retry with stricter instruction
2 consecutive failures Refine query OR escalate model (haiku→sonnet)
Contradictory answers across retries Query is ambiguous, decompose further

Never: Try to parse/repair confused output. Discard and retry.

TOON Format Reference

Token-Oriented Object Notation. Use for uniform arrays (file lists, steps, configs).

Basic Syntax

toon
# Array with header declaring fields
items[N]{field1,field2,field3}:
  value1,value2,value3
  value1,value2,value3

Escaping

  • Commas in values: wrap in quotes "value, with comma"
  • Quotes in values: escape \"nested quote\"
  • Newlines: use \n

Examples

File list:

toon
files[3]{path,purpose,lines}:
  src/auth/login.ts,Main login handler,145
  src/auth/session.ts,Session management,89
  src/auth/token.ts,JWT utilities,67

Process steps:

toon
steps[4]{position,action,file}:
  1,Parse request body,src/middleware/parser.ts
  2,Validate auth token,src/middleware/auth.ts
  3,Check permissions,src/middleware/rbac.ts
  4,Execute handler,src/routes/api.ts

Key-value config:

toon
config[3]{key,value}:
  maxTokens,1500
  format,toon
  itemLimit,10

Anti-Patterns Checklist

If coordination isn't working, check for these:

Anti-Pattern Fix
Single agent doing multiple tasks Split: one task per agent
No token budget specified Add @constraints: maxTokens: N
Using opus for simple search Downgrade to haiku
Full conversation history in prompt Strip to goal + constraints only
Sequential independent calls Parallelize in one message
Parsing broken output Discard and retry instead
Asking to "explain" or "describe" Request structured format
Direct MCP/web tool calls in main context Delegate: payloads unpredictable, request TOON summary
Verifying N external sources inline Delegate: N scrapes = N×2000 tokens wasted

Decomposition Examples

Bad: Compound task

Find authentication code and analyze security vulnerabilities and suggest fixes

Good: Three focused agents

Agent 1: Find authentication code (haiku, 1500 tokens)
Agent 2: Analyze security of [files from agent 1] (sonnet, 2000 tokens)
Agent 3: Suggest fixes for [issues from agent 2] (sonnet, 2000 tokens)

Note: Agent 2 depends on Agent 1, so run sequentially. But if you had 3 independent searches, run all in parallel.

Quick Diagnostics

Subagent returned garbage
├─ Was format specified? → Add explicit TOON/JSON instruction
├─ Was budget set? → Add @constraints maxTokens
├─ Was task atomic? → Check for "and", split if needed
├─ Right model? → Simple task shouldn't use opus
└─ Second failure? → Escalate model or refine query

External Data Operations

MCP tools and web scrapes are context pollution hazards:

Tool Typical Payload Risk
firecrawl_scrape 500-5000 tokens High - full page content
firecrawl_search 200-1000 tokens Medium - result snippets
WebFetch 500-3000 tokens High - full page content

Rule: Any task involving N external fetches should be delegated with:

  • Token budget: min(N × 200, 2500) tokens for summary output
  • Format: TOON for uniform results, JSON for complex analysis
  • Scrape options: onlyMainContent: true, formats: ["markdown"]

Example - URL verification:

Task(Explore, sonnet):
  "Verify these 10 legislation URLs. For each, scrape with onlyMainContent:true,
   confirm HTTP 200, identify managing authority from page content.

   @return ItemList in TOON:
   results[10]{jurisdiction,url,status,authority}:
     Commonwealth,https://legislation.gov.au,valid,Office of Parliamentary Counsel
     ...

   @constraints: maxTokens: 2000"

Reference

  • Core patterns: CLAUDE.md <subagent_coordination>
  • TOON format details: references/toon-format.md
  • Source: "Solving a Million-Step LLM Task with Zero Errors" (arxiv:2511.09030)

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results