Skip to content

Commit f33842d

Browse files
rickhanloniirickhanlonii
committed
Add /write command
1 parent dfa152b commit f33842d

File tree

2 files changed

+276
-0
lines changed

2 files changed

+276
-0
lines changed

‎.claude/skills/write/SKILL.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
name: write
3+
description: Use when creating new React documentation pages or updating existing ones. Accepts instructions like "add optimisticKey reference docs", "update ViewTransition with Activity", or "transition learn docs".
4+
---
5+
6+
# Documentation Writer
7+
8+
Orchestrates research, writing, and review for React documentation.
9+
10+
## Invocation
11+
12+
```
13+
/write add optimisticKey → creates new reference docs
14+
/write update ViewTransition Activity → updates ViewTransition docs to cover Activity
15+
/write transition learn docs → creates new learn docs for transitions
16+
/write blog post for React 20 → creates a new blog post
17+
```
18+
19+
## Workflow
20+
21+
```dot
22+
digraph write_flow {
23+
rankdir=TB;
24+
"Parse intent" [shape=box];
25+
"Research (parallel)" [shape=box];
26+
"Synthesize plan" [shape=box];
27+
"Write docs" [shape=box];
28+
"Review docs" [shape=box];
29+
"Issues found?" [shape=diamond];
30+
"Done" [shape=doublecircle];
31+
32+
"Parse intent" -> "Research (parallel)";
33+
"Research (parallel)" -> "Synthesize plan";
34+
"Synthesize plan" -> "Write docs";
35+
"Write docs" -> "Review docs";
36+
"Review docs" -> "Issues found?";
37+
"Issues found?" -> "Write docs" [label="yes - fix"];
38+
"Issues found?" -> "Done" [label="no"];
39+
}
40+
```
41+
42+
### Step 1: Parse Intent
43+
44+
Determine from the user's instruction:
45+
46+
| Field | How to determine |
47+
|-------|------------------|
48+
| **Action** | "add"/"create"/"new" = new page; "update"/"edit"/"with" = modify existing |
49+
| **Topic** | The React API or concept (e.g., `optimisticKey`, `ViewTransition`, `transitions`) |
50+
| **Doc type** | "reference" (default for APIs/hooks/components), "learn" (for concepts/guides), "blog" (for announcements) |
51+
| **Target file** | For updates: find existing file in `src/content/`. For new: determine path from doc type |
52+
53+
If the intent is ambiguous, ask the user to clarify before proceeding.
54+
55+
### Step 2: Research (Parallel Agents)
56+
57+
Spawn these agents **in parallel**:
58+
59+
#### Agent 1: React Expert Research
60+
61+
Use a Task agent (subagent_type: `general-purpose`) to invoke `/react-expert <topic>`. This researches the React source code, tests, PRs, issues, and type signatures.
62+
63+
**Prompt:**
64+
```
65+
Invoke the /react-expert skill for <TOPIC>. Follow the skill's full workflow:
66+
setup the React repo, dispatch all 6 research agents in parallel, synthesize
67+
results, and save to .claude/research/<topic>.md. Return the full research document.
68+
```
69+
70+
#### Agent 2: Existing Docs Audit
71+
72+
Use a Task agent (subagent_type: `Explore`) to find and read existing documentation for the topic.
73+
74+
**Prompt:**
75+
```
76+
Find all existing documentation related to <TOPIC> in this repo:
77+
1. Search src/content/ for files mentioning <TOPIC>
78+
2. Read any matching files fully
79+
3. For updates: identify what sections exist and what's missing
80+
4. For new pages: identify related pages to understand linking/cross-references
81+
5. Check src/sidebarLearn.json and src/sidebarReference.json for navigation placement
82+
83+
Return: list of existing files with summaries, navigation structure, and gaps.
84+
```
85+
86+
#### Agent 3: Use Case Research
87+
88+
Use a Task agent (subagent_type: `general-purpose`) with web search to find common use cases and patterns.
89+
90+
**Prompt:**
91+
```
92+
Search the web for common use cases and patterns for React's <TOPIC>.
93+
Focus on:
94+
1. Real-world usage patterns developers actually need
95+
2. Common mistakes or confusion points
96+
3. Migration patterns (if replacing an older API)
97+
4. Framework integration patterns (Next.js, Remix, etc.)
98+
99+
Return a summary of the top 5-8 use cases with brief code sketches.
100+
Do NOT search Stack Overflow. Focus on official docs, GitHub discussions,
101+
and high-quality technical blogs.
102+
```
103+
104+
### Step 3: Synthesize Writing Plan
105+
106+
After all research agents complete, create a writing plan that includes:
107+
108+
1. **Page type** (from docs-writer-reference decision tree or learn/blog type)
109+
2. **File path** for the new or updated file
110+
3. **Outline** with section headings matching the appropriate template
111+
4. **Content notes** for each section, drawn from research:
112+
- API signature and parameters (from react-expert types)
113+
- Usage examples (from react-expert tests + use case research)
114+
- Caveats and pitfalls (from react-expert warnings/errors/issues)
115+
- Cross-references to related pages (from docs audit)
116+
5. **Navigation changes** needed (sidebar JSON updates)
117+
118+
Present this plan to the user and confirm before proceeding.
119+
120+
### Step 4: Write Documentation
121+
122+
Dispatch a Task agent (subagent_type: `general-purpose`) to write the documentation.
123+
124+
**The agent prompt MUST include:**
125+
126+
1. The full writing plan from Step 3
127+
2. An instruction to invoke the appropriate skill:
128+
- `/docs-writer-reference` for reference pages
129+
- `/docs-writer-learn` for learn pages
130+
- `/docs-writer-blog` for blog posts
131+
3. An instruction to invoke `/docs-components` for MDX component patterns
132+
4. An instruction to invoke `/docs-sandpack` if adding interactive code examples
133+
5. The research document content (key findings, not the full dump)
134+
135+
**Prompt template:**
136+
```
137+
You are writing React documentation. Follow these steps:
138+
139+
1. Invoke /docs-writer-<TYPE> to load the page template and conventions
140+
2. Invoke /docs-components to load MDX component patterns
141+
3. Invoke /docs-sandpack if you need interactive code examples
142+
4. Write the documentation following the plan below
143+
144+
PLAN:
145+
<writing plan from Step 3>
146+
147+
RESEARCH FINDINGS:
148+
<key findings from Step 2 agents>
149+
150+
Write the file to: <target file path>
151+
Also update <sidebar JSON> if adding a new page.
152+
```
153+
154+
### Step 5: Review Documentation
155+
156+
Invoke `/review-docs` on the written files. This dispatches parallel review agents checking:
157+
- Structure compliance (docs-writer-*)
158+
- Voice and style (docs-voice)
159+
- Component usage (docs-components)
160+
- Sandpack patterns (docs-sandpack)
161+
162+
### Step 6: Fix Issues
163+
164+
If the review finds issues:
165+
1. Present the review checklist to the user
166+
2. Fix the issues identified
167+
3. Re-run `/review-docs` on the fixed files
168+
4. Repeat until clean
169+
170+
## Important Rules
171+
172+
- **Always research before writing.** Never write docs from LLM knowledge alone.
173+
- **Always confirm the plan** with the user before writing.
174+
- **Always review** with `/review-docs` after writing.
175+
- **Match existing patterns.** Read neighboring docs to match style and depth.
176+
- **Update navigation.** New pages need sidebar entries.

‎.claude/skills/write/diagrams/write_flow.svg‎

Lines changed: 100 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)