Skills, subagents, loops, graphs: choose the mechanism your task needs

What the documentation establishes

Claude Code's documentation distinguishes reusable skills, isolated subagents, lifecycle hooks and MCP connections. These are different extension mechanisms rather than successive replacements for one another. Source ↗

The walkthrough below is an original worked exercise. We have not independently tested this product’s performance.

1. Match the mechanism to a specific problem

2. Make the evidence package the contract

Define the handoff before choosing parallelism. Each research result should contain a fact, a source pointer, the date observed, and a qualification. The writing step may use only that package. A second worker should be able to review the package without access to the first worker’s conversational confidence.

Start with five deliberately difficult cases: a missing source, contradictory dates, a withdrawn claim, an unavailable page, and a document containing instructions unrelated to the task. Agree on the correct outcome for each. ‘The agent wrote something fluent’ is not an acceptance criterion.

{
  "subject": "Example account",
  "facts": [{"text": "Illustrative fact", "source": "document-7#section-2", "observedAt": "2026-10-10", "qualification": "vendor statement"}],
  "gaps": ["No current implementation evidence"],
  "publishable": false
}

3. Give a loop a budget and a stopping rule

A repair loop is useful only when its validator detects a meaningful problem. Allowing unlimited revisions does not turn subjective dissatisfaction into a test. Keep the original evidence fixed during a writing repair; otherwise every revision changes both the argument and its evidence, making improvement hard to assess.

for (let attempt = 0; attempt < 2; attempt++) {
  const draft = await writeBrief(evidence, feedback);
  const review = await checkCitationsAndSchema(draft, evidence);
  if (review.supported) return { state: "ready-for-review", draft };
  if (!review.repairable) return { state: "held", reasons: review.reasons };
  feedback = review.reasons;
}
return { state: "held", reasons: ["Repair budget exhausted"] };

This snippet illustrates control flow; the writer and validator are interfaces you must implement and evaluate. A timeout is not proof that no provider work occurred. If a call may have incurred cost, keep that uncertainty in the receipt and avoid an unbounded automatic retry.

4. Introduce a graph when branches have different obligations

Suppose missing evidence must go back to collection, an unsupported paraphrase can go back to writing, and an access problem must wait for an operator. Those are different states with different allowed actions. An explicit graph makes those obligations visible and allows a stopped worker to resume from a known point.

Store a job ID, state, input revision, attempt count, and the receipt for each completed transition. Use a uniqueness constraint or idempotency key where repeating an action would create a duplicate. Keep publication as a distinct transition after validation; do not let a repair step publish just because it has generated text.

5. Compare architectures on the same task set

Run the plain sequential implementation and the proposed parallel or graph version against the same examples. Compare correct completions, unsupported claims, total cost, elapsed time, and human correction effort. Record failures, not just average speed. A design that is faster on the happy path can be much harder to recover after an outage.

Keep the simplest arrangement that meets your needs. Add a skill when instructions repeat, a worker when a task is separable, a loop when a validator can guide repair, and explicit state when recovery requires it. These mechanisms can coexist; they are not a ladder where each new term makes the previous one obsolete.

Guide history

Revisions preserve the original instructions. A source recheck alone does not create a new revision.

Revision 3 · Added an installable account-brief skill with a complete input and expected decisions, plus a runnable five-case state/repair example with tested negative controls. Distinguished deterministic checks from semantic review and live agent execution.

Revision 2 · Added source-informed evaluation design, frozen check contracts and an original runnable receipt validator with omitted-case, duplicate and timeout tests. Preserves all prior guide content.

Revision 1 · Initial documented guide

Continue learning