[PROPOSAL] Custom skill: multi-agent document review using subagents (with PRD as the worked example)

## Preflight Checklist

- [x] I have searched existing cookbooks and this topic isn't already covered
- [x] This proposal focuses on Claude API/SDK capabilities (not external frameworks)
- [x] I am prepared to implement this cookbook

## Problem Statement

Reviewing any consequential document (a product spec, a research paper, a legal contract, a marketing brief) from a single AI perspective misses the angles the author is weakest on. Engineers spot feasibility risks. Designers spot UX gaps. Executives spot strategic misalignment. Legal spots compliance issues. A single Claude prompt asking "review this document" tends to surface the loudest issue, not the most varied issues.

Teams using Claude in production keep rebuilding the same pattern: spawn N specialized subagents with distinct roles, run them against the same document, then synthesize their feedback. There's no canonical notebook in the cookbook showing how to do this cleanly with the Anthropic SDK.

The result is fragmentation. Every shop reimplements multi-perspective review with slightly different patterns, and many newer users default to single-agent review because they don't realize the multi-agent pattern is one or two API calls away.

## Claude Capabilities Demonstrated

This notebook would showcase:

- **Subagent orchestration** using the Anthropic SDK to invoke N specialized agents with distinct system prompts and tool sets
- **Prompt caching** to keep the source document in cache across every subagent invocation (significant cost and latency win when running 5+ reviewers)
- **Tool use for structured critique extraction**: each subagent returns a JSON object with `strengths`, `concerns`, `suggestions`, `clarifying_questions` so the synthesis step can deduplicate and rank
- **The Skills feature** (in `custom_skills/`): each reviewer persona is a distinct skill with its own SKILL.md, so the same notebook scales from 3 to 12 reviewers without prompt rewrites
- **Synthesis prompt patterns** that rank cross-reviewer agreement vs disagreement, surfacing the "highest priority" issues automatically

## Differentiation

The existing `custom_skills/` folder has three skills: `analyzing-financial-statements`, `applying-brand-guidelines`, `creating-financial-models`. All are single-agent and document-generation oriented. None demonstrate the multi-agent critique pattern.

The `patterns/agents/` folder has agent orchestration code but not the specific "N specialists critique one shared document with synthesis" workflow.

The closest existing material is in `extended_thinking/` and `tool_use/`, but neither shows orchestration of multiple distinct personas against shared context.

The proposed notebook fills that gap and lands in the most natural folder for it (`skills/custom_skills/` with a companion notebook in `skills/notebooks/`).

## Proposed Structure

```
skills/custom_skills/multi-agent-document-review/
├── SKILL.md
├── reviewers/
│ ├── engineer.md
│ ├── designer.md
│ ├── executive.md
│ ├── legal.md
│ └── skeptic.md
├── synthesis.md
└── examples/
└── sample-prd.md

skills/notebooks/
└── 04_skills_multi_agent_review.ipynb
```

The worked example uses a one-page product requirements document (PRD) because it's a format most builders recognize and because the critique dimensions (feasibility, UX, strategy, risk) map cleanly onto distinct subagent roles. The pattern itself generalizes to any document type, which I'd call out explicitly in the notebook header.

## Additional Context

Reference implementation: I run a 7-reviewer version of this pattern in production inside an open-source PM workspace at [talgacapri/pm-os](https://github.com/talgacapri/pm-os) (see `sub-agents/` and `.claude/skills/prd-review-panel/`). The cookbook notebook would be a tighter, stand-alone version of that pattern, written for the SDK and self-contained.

Happy to scope this down to a single notebook in `skills/notebooks/` if a full `custom_skills/` subfolder feels too heavy for a first contribution, or split it into a two-PR sequence (notebook first, then the skills bundle).

If this lands well, a natural follow-up would be a parallel cookbook on **iterative multi-agent refinement** (reviewers critique → author revises → reviewers re-critique → convergence) using the same building blocks.