Research Create Skill
Design a research plan that decomposes a topic into parallel investigation tasks.
Process
Invoke an Explore subagent using the Task tool with subagent_type=Explore to understand the current codebase context relevant to the research topic. Capture the agentId from the Task result.
Design the research plan. Break the topic into independent questions that can be investigated in parallel. For each question, define:
- The question itself (what we need to find out)
- The where/what/how/why framework:
- Where: Which codebases, files, docs, or external sources to investigate
- What: What specific information to extract
- How: How the system/algorithm/feature works
- Why: Why it was designed this way, what tradeoffs were made
- The output file name for findings
- Which sources to consult (local code, external repos, docs, web)
Find the next research number by checking both research/ and research/archive/ for the highest NNNN-* prefix. Unnumbered directories are legacy and should be ignored when determining the next number.
Create the research directory: research/NNNN-topic-name/
Write research-plan.md with this format:
# Research: Topic Name
## Status: PLANNED
---
## Goal
[What we're trying to learn and why]
## Context
[Current state, what prompted this research, relevant background]
## Questions
### Q1: [Question title]
**Where:** [Sources to investigate]
**What:** [Specific information needed]
**How:** [Methodology — read code, run experiments, compare implementations]
**Why:** [Why this matters for our goals]
**Output file:** `q1-descriptive-name.md`
---
### Q2: [Question title]
**Where:** [Sources to investigate]
**What:** [Specific information needed]
**How:** [Methodology]
**Why:** [Why this matters]
**Output file:** `q2-descriptive-name.md`
---
[Continue for each question]
## Sources
| Source | Location | Used by |
|--------|----------|---------|
| [Source name] | [Path or URL] | Q1, Q2 |
## Expected Outputs
| File | Question | Status |
|------|----------|--------|
| `q1-descriptive-name.md` | Q1: Title | Pending |
| `q2-descriptive-name.md` | Q2: Title | Pending |
| `synthesis.md` | Combined findings | Pending |
Write .research-state.json with initial state:
{
"status": "planned",
"created_at": "2026-01-28T10:30:00Z",
"updated_at": "2026-01-28T10:30:00Z",
"planning_agent_id": "abc-123-def",
"agent_ids": [],
"synthesis_agent_id": null,
"last_session_notes": null
}
status: "planned" — research plan created but agents not yet spawnedplanning_agent_id: agentId from the Explore subagentagent_ids: empty array, populated when /research:resume spawns agentssynthesis_agent_id: null until synthesis is performed
Do not spawn research agents yet. The plan should be reviewed first. Agents are spawned by /research:resume.
Present the plan to the user:
**Research plan created:** `research/NNNN-topic-name/`
**Created:** YYYY-MM-DD HH:MM UTC
**Questions:** N questions defined
**Planning agent:** `{agentId}` (resume for additional context)
**Questions:**
- Q1: [Title] -> `q1-output-file.md`
- Q2: [Title] -> `q2-output-file.md`
- Q3: [Title] -> `q3-output-file.md`
Review the research plan, then run `/research:resume` to spawn parallel investigation agents.
*Research summary: Brief description of what we're investigating*
Findings File Template
Each subagent should produce findings following this structure:
# Q1: [Question Title]
## Summary
[2-3 sentence answer to the question]
## Where
[Sources consulted — files read, repos explored, docs referenced]
## What
[Detailed findings — the factual information discovered]
## How
[How the system/algorithm/feature works, with code references and examples]
## Why
[Why it was designed this way, tradeoffs, constraints, design rationale]
## Key Takeaways
- [Bullet point takeaway 1]
- [Bullet point takeaway 2]
- [Bullet point takeaway 3]
## Open Questions
- [Any follow-up questions that emerged during investigation]
Hierarchical Research
If a research plan needs deeper investigation on a subtopic:
- Create a subdirectory:
research/NNNN-topic-name/subtopic-name/
- The subdirectory gets its own
research-plan.md and .research-state.json
- The parent's synthesis should reference the child research
1---2name: research-create3description: Create a research plan with parallel investigation tasks. Use when exploring a topic, analyzing external code, or gathering information to inform an implementation plan.4---5
6# Research Create Skill
7
8Design a research plan that decomposes a topic into parallel investigation tasks.
9
10## Process
11
121. **Invoke an Explore subagent** using the Task tool with `subagent_type=Explore` to understand the current codebase context relevant to the research topic. **Capture the `agentId`** from the Task result.
13
142. **Design the research plan.** Break the topic into independent questions that can be investigated in parallel. For each question, define:
15 - The question itself (what we need to find out)
16 - The where/what/how/why framework:
17 - **Where:** Which codebases, files, docs, or external sources to investigate
18 - **What:** What specific information to extract
19 - **How:** How the system/algorithm/feature works
20 - **Why:** Why it was designed this way, what tradeoffs were made
21 - The output file name for findings
22 - Which sources to consult (local code, external repos, docs, web)
23
243. **Find the next research number** by checking both `research/` and `research/archive/` for the highest `NNNN-*` prefix. Unnumbered directories are legacy and should be ignored when determining the next number.
25
264. **Create the research directory:** `research/NNNN-topic-name/`
27
285. **Write `research-plan.md`** with this format:
29
30 ```markdown
31 # Research: Topic Name
32
33 ## Status: PLANNED
34
35 ---
36
37 ## Goal
38
39 [What we're trying to learn and why]
40
41 ## Context
42
43 [Current state, what prompted this research, relevant background]
44
45 ## Questions
46
47 ### Q1: [Question title]
48
49 **Where:** [Sources to investigate]
50 **What:** [Specific information needed]
51 **How:** [Methodology — read code, run experiments, compare implementations]
52 **Why:** [Why this matters for our goals]
53
54 **Output file:** `q1-descriptive-name.md`
55
56 ---
57
58 ### Q2: [Question title]
59
60 **Where:** [Sources to investigate]
61 **What:** [Specific information needed]
62 **How:** [Methodology]
63 **Why:** [Why this matters]
64
65 **Output file:** `q2-descriptive-name.md`
66
67 ---
68
69 [Continue for each question]
70
71 ## Sources
72
73 | Source | Location | Used by |
74 |--------|----------|---------|
75 | [Source name] | [Path or URL] | Q1, Q2 |
76
77 ## Expected Outputs
78
79 | File | Question | Status |
80 |------|----------|--------|
81 | `q1-descriptive-name.md` | Q1: Title | Pending |
82 | `q2-descriptive-name.md` | Q2: Title | Pending |
83 | `synthesis.md` | Combined findings | Pending |
84 ```
85
866. **Write `.research-state.json`** with initial state:
87
88 ```json
89 {
90 "status": "planned",
91 "created_at": "2026-01-28T10:30:00Z",
92 "updated_at": "2026-01-28T10:30:00Z",
93 "planning_agent_id": "abc-123-def",
94 "agent_ids": [],
95 "synthesis_agent_id": null,
96 "last_session_notes": null
97 }
98 ```
99
100 - `status`: `"planned"` — research plan created but agents not yet spawned
101 - `planning_agent_id`: agentId from the Explore subagent
102 - `agent_ids`: empty array, populated when `/research:resume` spawns agents
103 - `synthesis_agent_id`: null until synthesis is performed
104
1057. **Do not spawn research agents yet.** The plan should be reviewed first. Agents are spawned by `/research:resume`.
106
1078. **Present the plan** to the user:
108
109 ```
110 **Research plan created:** `research/NNNN-topic-name/`
111 **Created:** YYYY-MM-DD HH:MM UTC
112 **Questions:** N questions defined
113 **Planning agent:** `{agentId}` (resume for additional context)
114
115 **Questions:**
116 - Q1: [Title] -> `q1-output-file.md`
117 - Q2: [Title] -> `q2-output-file.md`
118 - Q3: [Title] -> `q3-output-file.md`
119
120 Review the research plan, then run `/research:resume` to spawn parallel investigation agents.
121
122 *Research summary: Brief description of what we're investigating*
123 ```
124
125## Findings File Template
126
127Each subagent should produce findings following this structure:
128
129```markdown
130# Q1: [Question Title]
131
132## Summary
133
134[2-3 sentence answer to the question]
135
136## Where
137
138[Sources consulted — files read, repos explored, docs referenced]
139
140## What
141
142[Detailed findings — the factual information discovered]
143
144## How
145
146[How the system/algorithm/feature works, with code references and examples]
147
148## Why
149
150[Why it was designed this way, tradeoffs, constraints, design rationale]
151
152## Key Takeaways
153
154- [Bullet point takeaway 1]
155- [Bullet point takeaway 2]
156- [Bullet point takeaway 3]
157
158## Open Questions
159
160- [Any follow-up questions that emerged during investigation]
161```
162
163## Hierarchical Research
164
165If a research plan needs deeper investigation on a subtopic:
166- Create a subdirectory: `research/NNNN-topic-name/subtopic-name/`
167- The subdirectory gets its own `research-plan.md` and `.research-state.json`
168- The parent's synthesis should reference the child research
majiayu000