Skilllibrary subagent-research-patterns
install
source · Clone the upstream repo
git clone https://github.com/merceralex397-collab/skilllibrary
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/merceralex397-collab/skilllibrary "$T" && mkdir -p ~/.claude/skills && cp -r "$T/05-agentic-orchestration-and-autonomy/subagent-research-patterns" ~/.claude/skills/merceralex397-collab-skilllibrary-subagent-research-patterns && rm -rf "$T"
manifest:
05-agentic-orchestration-and-autonomy/subagent-research-patterns/SKILL.mdsource content
Purpose
Provides a repeatable procedure for decomposing a research question into narrow sub-questions, delegating each to a read-only sub-agent, validating the returned evidence, and synthesizing a consolidated answer — all without any sub-agent mutating repository state.
When to use
- A question requires evidence from 2+ distinct sources or domains.
- The lead agent's context window would overflow if it did all research inline.
- The user explicitly asks for delegated or parallel research.
- A planning phase needs facts gathered before decisions can be made.
Do NOT use when
- The answer is retrievable with a single grep, glob, or web-fetch call.
- The task requires writing code, creating files, or mutating repo state.
- Research scope is undefined — ask the user to clarify before delegating.
- A more specific skill (e.g.,
) already covers the domain.sc2-domain-expert
Operating procedure
- Extract the root question. Copy the user's request verbatim into a
field. If it contains multiple questions, list each one.root_question - Decompose into sub-questions. For each root question, write 1–5 sub-questions that are independently answerable. Record each in a numbered list with an explicit scope boundary (files, APIs, docs to search).
- Define the evidence contract per sub-agent. For every sub-question, specify: (a) allowed tool calls (grep, glob, view, web_search, web_fetch), (b) maximum sources to consult (default 3), (c) required output shape (quote + citation + confidence tag: high / medium / low).
- Launch sub-agents in parallel. Use the
tool withtask
for each sub-question. Include the evidence contract verbatim in the prompt.agent_type: explore - Collect and validate returns. For each sub-agent response, check: (a) at least one direct quote or data point is present, (b) every claim has a file path, URL, or commit SHA citation, (c) confidence tag is included. Reject any response missing these and re-prompt once.
- Cross-reference overlapping findings. If two sub-agents return conflicting data, list both claims side-by-side with citations and flag the conflict explicitly — do not silently pick one.
- Synthesize the consolidated answer. Merge validated findings into a single structured response: Summary → Evidence table (claim | source | confidence) → Open questions.
- Record the research trace. Append a
section listing each sub-question, the sub-agent that handled it, and the verdict.## Research Log
Decision rules
- Never allow a sub-agent to run
,bash
, oredit
— research is read-only.create - If a sub-agent returns only a status phrase ("I found it", "looks good") with no evidence, mark the sub-question as FAILED and re-delegate once.
- If re-delegation also fails, escalate the sub-question to the lead agent with an explicit "evidence gap" note.
- Cap total sub-agents at 6 per research round to avoid context explosion.
- Prefer primary sources (code, docs, API responses) over secondary commentary (blog posts, Stack Overflow) unless no primary source exists.
Output requirements
- Research Brief — a markdown section with: Summary, Evidence Table (claim | source | confidence), Conflicts, Open Questions.
- Sub-agent Trace — a collapsed details block listing each sub-question, its delegate, and pass/fail status.
- Confidence Rating — an overall HIGH / MEDIUM / LOW tag on the brief.
References
— template for sub-agent contracts.references/delegate-contracts.md
— when and how to escalate gaps.references/failure-escalation.md
Related skills
— when research scales to many parallel agents.swarm-patterns
— gating next steps on research quality.verification-before-advance
— persisting research results across sessions.workflow-state-memory
— resuming interrupted research.session-resume-rehydration
Failure handling
- Sub-agent timeout: If a sub-agent does not return within 120 seconds, cancel it and note the sub-question as TIMED_OUT in the trace.
- All sub-agents fail: Attempt the research inline with the lead agent. If the lead agent also cannot answer, return a frank "unable to determine" with the list of attempted sources.
- Conflicting evidence with no resolution: Present both sides to the user with citations and ask for a tiebreaker rather than guessing.
- Scope creep: If a sub-agent's findings suggest the root question needs reframing, pause synthesis and propose a revised decomposition to the user.