A skills-first, composable research orchestration framework for Claude Code. This system enables deep, persistent, and verifiable research through structured workflows, subagent coordination, and progressive disclosure.
researcher-agent/
├── skills/ # Primary instruction set (skills-first design)
│ ├── meta/ # Bootstrap and skill discovery
│ ├── project-setup/
│ ├── clarify-and-scope/
│ ├── prompt-rewrite/
│ ├── research-plan/
│ ├── web-research/
│ ├── data-extraction/
│ ├── analysis-and-modeling/
│ ├── synthesis-writing/
│ ├── quality-assurance/
│ ├── iteration-and-extension/
│ └── tooling-onboarding/
├── agents/ # Subagent definitions
├── commands/ # User-facing workflow triggers
├── templates/ # Report and artifact templates
├── lib/ # Helper scripts and utilities
├── docs/ # Documentation and examples
└── research_projects/ # Persistent project folders
Step 1: Invoke the research command
/research:new <your research question or topic>
Step 2: Answer clarifying questions (if any) The system will ask targeted follow-up questions only when necessary to scope the research properly.
Step 3: Review and approve the research plan The planner subagent generates a fit-for-purpose plan. Review it and confirm to proceed.
That's it. The system handles the rest and delivers:
- A clean narrative report at
outputs/report.md - An evidence table at the end of the report
- A research effort summary at
outputs/effort_summary.md - All sources and working artifacts preserved in the project folder
/research:continue <project-path>
/research:supplement <project-path> <new question or angle>
Skills are the primary system primitive. Every capability is expressed as a skill with:
- SKILL.md — YAML frontmatter (name, description, triggers, inputs, outputs) + concise instructions
- Supporting files — Checklists, rubrics, examples loaded only when needed (progressive disclosure)
Mandatory usage rule: If a relevant skill exists, the agent MUST use it.
Research is orchestrated through specialized subagents:
| Subagent | Role |
|---|---|
| Planner | Scopes research, creates plans, assigns tasks |
| Researcher | Web search, source gathering, citation capture |
| Analyst | Calculations, modeling, data processing |
| Skeptic | Verification, gap-finding, contradiction detection |
| Writer | Narrative synthesis, report drafting |
| Editor | Structure, clarity, formatting, final polish |
Subagents work in parallel where possible, writing outputs to designated folders.
Every research request creates a persistent folder:
research_projects/<subject>/<YYYY-MM-DD>__<request_slug>/
├── inputs/ # Original prompt, clarifications, constraints
├── plans/ # Research plans, query strategies, subagent briefs
├── work/ # Notes, drafts, calculations, code experiments
│ └── code/ # Scripts for deterministic processing
├── sources/ # Captured excerpts, downloads, raw data
├── outputs/ # Final deliverables
│ ├── report.md # Main narrative report
│ ├── effort_summary.md
│ └── appendix.md # (optional)
└── meta/
├── project.yaml # Scope, status, key questions
└── changelog.md # Iteration history
- Parse user request
- Determine if clarification is needed
- Ask follow-up questions BEFORE starting research
- Create project folder structure
- Generate expanded research brief
- Produce adaptive research plan
- Planner refines and assigns tasks
- Researcher gathers and captures sources
- Analyst processes data and builds models
- Skeptic audits claims and identifies gaps
- All artifacts persist to project folder
- Writer produces narrative report
- Evidence table appended at end
- Clean structure following template
- Verify claim-evidence mapping
- Check uncertainty labeling
- Confirm open questions listed
- Validate deliverable meets request
- Print medium-depth TL;DR to user
- Point to project folder and report location
- Generate effort summary
- Every key claim must appear in the Evidence Table
- Prefer primary sources; triangulate when possible
- Explicitly label uncertainty and confidence levels
- Clean narrative without inline evidence clutter
- Evidence Table at END of report
- TL;DR at appropriate depth (not too short, not full report)
- Surface unresolved contradictions
- Explain why uncertainty remains
- List open questions for future research
See skills/meta/skill-creation/ for the skill authoring guide.
See skills/tooling-onboarding/ for the tool integration guide. The system is designed for future MCP integration without refactoring.
Modify files in templates/ to adjust report structure, evidence table format, or project metadata schema.
skills/meta/using-skills/SKILL.md— Bootstrap skill (loaded at session start)templates/report_outline.md— Report structure templatetemplates/evidence_table.md— Evidence table specificationagents/*.md— Subagent instruction files
commands/new_research.md— Start new research projectcommands/continue.md— Continue existing projectcommands/supplement.md— Add supplemental research
See docs/worked_example.md for a complete walkthrough showing:
- User request
- Clarification exchange
- Generated plan
- Project folder structure
- Final report excerpt
- Skills as primitives — Capabilities are skills, not ad-hoc prompts
- Progressive disclosure — Load details only when needed
- Persistent artifacts — Everything is written to disk
- Observable process — User can inspect any intermediate state
- Composable subagents — Specialized roles with clear interfaces
- Adaptive planning — Plans fit the request, not rigid templates
- Quality gates — Verification is built-in, not optional
- Future-proof — MCP/tool integration ready without refactoring