AGENT SKILL

orchestration

Multi-agent workflow patterns for Claude Code -- parallel dispatch, sequential pipelines, QC gates, retry loops, shared partials. Use when designing systems with multiple agents, commands, or processing stages.

License 许可
MIT
最近更新
2026-11-01
Stars
★ 3
Forks
1

01 前言 Front Matter

name
orchestration
version
0.1.0
description
Multi-agent workflow patterns for Claude Code -- parallel dispatch, sequential pipelines, QC gates, retry loops, shared partials. Use when designing systems with multiple agents, commands, or processing stages.

03 SKILL.md 正文

Orchestration

Scope: covers multi-agent workflow design. For individual agent authoring, see [[writing-agents]]. For plugin architecture, see [[writing-plugins]].

1. Four Orchestration Patterns

Pattern A: Parallel Dispatch

Multiple agents run simultaneously on independent work. A command dispatches them via the Task tool and synthesizes results.

Command dispatches via Task:
  |-- agent-1 (analyzes security)
  |-- agent-2 (analyzes performance)
  |-- agent-3 (analyzes architecture)
  --> Command synthesizes all results into final report

Use when: agents don't depend on each other's output.

Real examples:

  • grill plugin: 6 review agents analyze code from different angles in parallel
  • docs-guardian: 4 agents (staleness, accuracy, coverage, quality) run simultaneously

Implementation pattern in command body:

## Execution
1. Dispatch the following agents in parallel using Task:
   - security-agent: analyze for vulnerabilities
   - performance-agent: analyze for bottlenecks
   - architecture-agent: analyze for structural issues
2. Collect all agent outputs
3. Synthesize into a unified report with cross-references

Key decisions:

Decision Recommendation
Max parallel agents 6 (diminishing returns above this)
Timeout per agent 120 seconds for sonnet, 300 for opus
Failure handling Continue with other agents if one fails
Result merging Deduplicate findings that appear in multiple agents

Pattern B: Sequential Pipeline

Each stage feeds into the next. Output of stage N is input to stage N+1.

parse --> chunk --> summarize --> QC --> output

Use when: each stage depends on the previous stage's output.

Real examples:

  • reading-assistant: parse PDF -> chunk content -> summarize chunks -> QC summaries -> output
  • tdd-guardian: discover tests -> run tests -> check coverage -> analyze failures -> report -> enforce

Implementation pattern:

## Execution
### Phase 1: Parse (haiku)
1. Scan input files
2. Extract structured content
3. Output: parsed data as JSON

### Phase 2: Process (sonnet)
4. Receive parsed data from Phase 1
5. Analyze and transform
6. Output: processed results

### Phase 3: QC (sonnet)
7. Verify Phase 2 output meets quality bar
8. Output: pass/warn/fail verdict

### Phase 4: Output
9. If QC passed: format and deliver final report
10. If QC failed: report failures and stop

Key decisions:

Decision Recommendation
Phase boundary Each phase should have a clear input type and output type
Error propagation Fail fast -- don't continue past a failed phase
State passing Use structured output (JSON) between phases
Resumability Track phase status for long pipelines (see section 4)

Pattern C: QC Gate

AI processing followed by quality verification before output reaches the user.

Phase 1: Mechanical prep (haiku)
Phase 2: AI work (sonnet)
Phase 3: QC verification (sonnet/opus)
  --> pass: proceed to output
  --> warn: output with warnings
  --> fail: stop, report issues
Phase 4: Output

Use when: AI output needs verification before the user sees it.

Threshold design:

Verdict Condition Action
PASS All checks green Deliver output directly
WARN Minor issues (< 3 low-severity) Deliver output with warnings section
FAIL Any critical issue OR > 5 total issues Stop, report what failed, suggest re-run

Real examples:

  • reading-assistant: QC agents verify summaries for accuracy, completeness, fidelity
  • codex-toolkit audit-fix: audit -> fix -> verify loop

Pattern D: Retry Loop

On failure, re-dispatch with error context. The agent gets a second chance with specific feedback about what went wrong.

agent produces output
  --> QC checks output
    --> pass: done
    --> fail: re-dispatch agent with error context
      --> QC re-checks
        --> pass: done
        --> fail (attempt 2): re-dispatch again
          --> max retries reached: fail with report

Use when: quality failures are recoverable by re-trying with more context.

Implementation:

## Retry Protocol
- Max retries: 3
- On retry, include in the agent prompt:
  - Previous output (or summary if too long)
  - Specific failures from QC
  - Instruction: "Fix ONLY the listed failures. Do not change passing sections."
- If max retries exhausted: output best attempt with failure annotations

Key decisions:

Decision Recommendation
Max retries 3 (rarely succeeds after 3 if it failed 3 times)
Error context Include specific failures, not "try again"
Scope of retry Fix only failures, preserve passing output
Cost cap Each retry costs full agent invocation -- budget accordingly

2. Shared Partials for DRY

Extract common logic into commands/shared/*.md with user-invocable: false in frontmatter.

When to Extract

Situation Extract?
Same logic in 3+ commands Yes -- always extract
Same logic in 2 commands, complex (> 20 lines) Yes -- extract
Same logic in 2 commands, simple (< 10 lines) No -- duplication is fine
Logic used by 1 command but might be reused No -- wait until it's actually reused

Good Candidates for Extraction

Partial What it contains Who includes it
shared/load-config.md Read and validate plugin config file All commands that need config
shared/discover-files.md Find target files by pattern/extension Commands that scan the repo
shared/validate-prereqs.md Check tool availability, environment Commands with external dependencies
shared/format-report.md Common report header, footer, severity colors Commands that output reports

Partial File Structure

---
user-invocable: false
description: "Shared config loading logic — reads and validates the plugin config file"
---
## Config Loading

1. Look for `.config.md` in the project root
2. If not found, look for `.config.yaml`
3. If neither found, output error: "Run `/plugin:init` first to create a config file"
4. Parse the config file
5. Validate required fields: [list fields]
6. Return parsed config

3. Cost Gates

For expensive AI pipelines, add a cost estimation step between mechanical prep and AI processing.

Implementation

Phase 1: Parse and discover (haiku -- cheap)
  --> Count items to process
  --> Estimate cost: items x model cost per item
  --> Display estimate to user

User confirms or adjusts scope

Phase 2: AI processing (sonnet/opus -- expensive)
  --> Process confirmed scope

Cost Estimation Table

Model Approx cost per item 10 items 100 items 1000 items
haiku $0.001 $0.01 $0.10 $1.00
sonnet $0.01 $0.10 $1.00 $10.00
opus $0.03 $0.30 $3.00 $30.00

"Item" = one agent invocation processing one unit of work (one file, one chunk, one component).

User Confirmation Pattern

## Cost Gate
After Phase 1, display:
- Items to process: {N}
- Estimated model: {model}
- Estimated cost: ~${amount}
- Estimated time: ~{minutes} minutes

Ask: "Proceed with {N} items? (You can reduce scope with --filter)"

4. Pipeline State

For resumable pipelines (long-running, expensive, or failure-prone), track state in a JSON file.

State File Schema

{
  "pipeline": "my-pipeline",
  "startedAt": "2024-01-15T10:00:00Z",
  "configFingerprint": "sha256:abc123",
  "phases": {
    "parse": {
      "status": "completed",
      "startedAt": "2024-01-15T10:00:00Z",
      "completedAt": "2024-01-15T10:00:05Z",
      "itemsProcessed": 42,
      "output": "parse-output.json"
    },
    "analyze": {
      "status": "running",
      "startedAt": "2024-01-15T10:00:06Z",
      "itemsProcessed": 15,
      "itemsTotal": 42
    },
    "qc": {
      "status": "pending"
    }
  },
  "lock": {
    "pid": 12345,
    "acquiredAt": "2024-01-15T10:00:00Z"
  }
}

State Transitions

pending --> running --> completed
                   --> failed
                   --> skipped (if previous phase failed)

Resumability Rules

  1. On start: check for existing state file
  2. If state exists and configFingerprint matches: resume from last incomplete phase
  3. If state exists and configFingerprint differs: warn user, offer fresh start or resume
  4. If lock exists: check if PID is alive. If dead, clear stale lock. If alive, abort.

5. Model Tier Allocation

Assign models by cognitive load, not by importance.

Mechanical / IO:     haiku    (parser, scanner, formatter, counter)
Reasoning / AI:      sonnet   (summarizer, extractor, reviewer, linter)
Judgment / QC:       opus     (coordinator, architect, final reviewer)

Pipeline Model Assignment Example

Phase 1: Discover files          → haiku  (just glob + read)
Phase 2: Parse and chunk         → haiku  (mechanical splitting)
Phase 3: Analyze each chunk      → sonnet (requires judgment)
Phase 4: QC all analyses         → sonnet (verify, not create)
Phase 5: Synthesize final report → opus   (cross-reference, prioritize)

Cost Optimization

Optimization How Savings
Batch mechanical work One haiku call processes all files, not one per file 5-10x
Pre-filter before AI Use grep/glob to skip irrelevant files before sonnet 2-5x
Cache phase outputs Don't re-run completed phases on retry 1-3x
Scope reduction Let user filter to subset before expensive phases Variable

6. Error Propagation

Rules

  1. Phase fails -> STOP. Set status "failed" + error message in state. Do not continue to next phase.
  2. Agent fails -> report and continue (in parallel dispatch). One agent's failure shouldn't block others.
  3. Retry fails -> escalate. After max retries, surface the failure to the user with full context.
  4. Never swallow errors silently. Every failure must be visible in the final output.

Error Report Format

## Pipeline Error

**Phase**: {phase_name}
**Status**: FAILED
**Error**: {error_message}

### Context
- Items processed before failure: {N} of {M}
- Last successful item: {item_id}
- Time elapsed: {duration}

### Recovery Options
1. Fix the issue and run `/command --resume` to continue from this phase
2. Run `/command --restart` to start fresh
3. Run `/command --skip-phase {phase_name}` to skip this phase (not recommended)

Fallback Paths

Always offer a manual fallback when automation fails:

## Fallback
If the pipeline fails after 3 retries:
1. Output all successfully processed items
2. List failed items with error context
3. Suggest manual analysis for failed items

7. Pattern Selection Guide

Your situation Pattern Why
Multiple independent analyses of same input A: Parallel No dependencies, maximize throughput
Each step needs previous step's output B: Sequential Data flows in one direction
AI output must be verified before delivery C: QC Gate Catch errors before user sees them
Quality failures are recoverable with feedback D: Retry Cheaper than manual re-run
Complex multi-stage with verification B + C Pipeline with QC gates between expensive phases
Multiple analyses with quality bar A + C Parallel dispatch, then QC all results

04 同仓库更多 Skills

shengdabai
shengdabai/Tony-Claude-Code-Skills

seedance-prompt-en

Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

onepage-pdf

Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file/report/proposal into a "single-page PDF", "long PDF", "不分页 PDF", "单页 PDF", "长图式 PDF", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

native-feel-cross-platform-desktop

Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

gstack

Router for the gstack skill suite. (gstack)

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

fireworks-tech-graph

Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent/memory, or concept map - and export as SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图" "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any system/flow description the user wants illustrated.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

dbs-video-extract

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

★ 3