diff --git a/.claude/skills/write/SKILL.md b/.claude/skills/write/SKILL.md new file mode 100644 index 00000000000..3099b3a0c08 --- /dev/null +++ b/.claude/skills/write/SKILL.md @@ -0,0 +1,176 @@ +--- +name: write +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". +--- + +# Documentation Writer + +Orchestrates research, writing, and review for React documentation. + +## Invocation + +``` +/write add optimisticKey → creates new reference docs +/write update ViewTransition Activity → updates ViewTransition docs to cover Activity +/write transition learn docs → creates new learn docs for transitions +/write blog post for React 20 → creates a new blog post +``` + +## Workflow + +```dot +digraph write_flow { + rankdir=TB; + "Parse intent" [shape=box]; + "Research (parallel)" [shape=box]; + "Synthesize plan" [shape=box]; + "Write docs" [shape=box]; + "Review docs" [shape=box]; + "Issues found?" [shape=diamond]; + "Done" [shape=doublecircle]; + + "Parse intent" -> "Research (parallel)"; + "Research (parallel)" -> "Synthesize plan"; + "Synthesize plan" -> "Write docs"; + "Write docs" -> "Review docs"; + "Review docs" -> "Issues found?"; + "Issues found?" -> "Write docs" [label="yes - fix"]; + "Issues found?" -> "Done" [label="no"]; +} +``` + +### Step 1: Parse Intent + +Determine from the user's instruction: + +| Field | How to determine | +|-------|------------------| +| **Action** | "add"/"create"/"new" = new page; "update"/"edit"/"with" = modify existing | +| **Topic** | The React API or concept (e.g., `optimisticKey`, `ViewTransition`, `transitions`) | +| **Doc type** | "reference" (default for APIs/hooks/components), "learn" (for concepts/guides), "blog" (for announcements) | +| **Target file** | For updates: find existing file in `src/content/`. For new: determine path from doc type | + +If the intent is ambiguous, ask the user to clarify before proceeding. + +### Step 2: Research (Parallel Agents) + +Spawn these agents **in parallel**: + +#### Agent 1: React Expert Research + +Use a Task agent (subagent_type: `general-purpose`) to invoke `/react-expert `. This researches the React source code, tests, PRs, issues, and type signatures. + +**Prompt:** +``` +Invoke the /react-expert skill for . Follow the skill's full workflow: +setup the React repo, dispatch all 6 research agents in parallel, synthesize +results, and save to .claude/research/.md. Return the full research document. +``` + +#### Agent 2: Existing Docs Audit + +Use a Task agent (subagent_type: `Explore`) to find and read existing documentation for the topic. + +**Prompt:** +``` +Find all existing documentation related to in this repo: +1. Search src/content/ for files mentioning +2. Read any matching files fully +3. For updates: identify what sections exist and what's missing +4. For new pages: identify related pages to understand linking/cross-references +5. Check src/sidebarLearn.json and src/sidebarReference.json for navigation placement + +Return: list of existing files with summaries, navigation structure, and gaps. +``` + +#### Agent 3: Use Case Research + +Use a Task agent (subagent_type: `general-purpose`) with web search to find common use cases and patterns. + +**Prompt:** +``` +Search the web for common use cases and patterns for React's . +Focus on: +1. Real-world usage patterns developers actually need +2. Common mistakes or confusion points +3. Migration patterns (if replacing an older API) +4. Framework integration patterns (Next.js, Remix, etc.) + +Return a summary of the top 5-8 use cases with brief code sketches. +Do NOT search Stack Overflow. Focus on official docs, GitHub discussions, +and high-quality technical blogs. +``` + +### Step 3: Synthesize Writing Plan + +After all research agents complete, create a writing plan that includes: + +1. **Page type** (from docs-writer-reference decision tree or learn/blog type) +2. **File path** for the new or updated file +3. **Outline** with section headings matching the appropriate template +4. **Content notes** for each section, drawn from research: + - API signature and parameters (from react-expert types) + - Usage examples (from react-expert tests + use case research) + - Caveats and pitfalls (from react-expert warnings/errors/issues) + - Cross-references to related pages (from docs audit) +5. **Navigation changes** needed (sidebar JSON updates) + +Present this plan to the user and confirm before proceeding. + +### Step 4: Write Documentation + +Dispatch a Task agent (subagent_type: `general-purpose`) to write the documentation. + +**The agent prompt MUST include:** + +1. The full writing plan from Step 3 +2. An instruction to invoke the appropriate skill: + - `/docs-writer-reference` for reference pages + - `/docs-writer-learn` for learn pages + - `/docs-writer-blog` for blog posts +3. An instruction to invoke `/docs-components` for MDX component patterns +4. An instruction to invoke `/docs-sandpack` if adding interactive code examples +5. The research document content (key findings, not the full dump) + +**Prompt template:** +``` +You are writing React documentation. Follow these steps: + +1. Invoke /docs-writer- to load the page template and conventions +2. Invoke /docs-components to load MDX component patterns +3. Invoke /docs-sandpack if you need interactive code examples +4. Write the documentation following the plan below + +PLAN: + + +RESEARCH FINDINGS: + + +Write the file to: +Also update if adding a new page. +``` + +### Step 5: Review Documentation + +Invoke `/review-docs` on the written files. This dispatches parallel review agents checking: +- Structure compliance (docs-writer-*) +- Voice and style (docs-voice) +- Component usage (docs-components) +- Sandpack patterns (docs-sandpack) + +### Step 6: Fix Issues + +If the review finds issues: +1. Present the review checklist to the user +2. Fix the issues identified +3. Re-run `/review-docs` on the fixed files +4. Repeat until clean + +## Important Rules + +- **Always research before writing.** Never write docs from LLM knowledge alone. +- **Always confirm the plan** with the user before writing. +- **Always review** with `/review-docs` after writing. +- **Match existing patterns.** Read neighboring docs to match style and depth. +- **Update navigation.** New pages need sidebar entries. diff --git a/.claude/skills/write/diagrams/write_flow.svg b/.claude/skills/write/diagrams/write_flow.svg new file mode 100644 index 00000000000..49056ef11ab --- /dev/null +++ b/.claude/skills/write/diagrams/write_flow.svg @@ -0,0 +1,100 @@ + + + + + + +write_flow + + + +Parse intent + +Parse intent + + + +Research (parallel) + +Research (parallel) + + + +Parse intent->Research (parallel) + + + + + +Synthesize plan + +Synthesize plan + + + +Research (parallel)->Synthesize plan + + + + + +Write docs + +Write docs + + + +Synthesize plan->Write docs + + + + + +Review docs + +Review docs + + + +Write docs->Review docs + + + + + +Issues found? + +Issues found? + + + +Review docs->Issues found? + + + + + +Issues found?->Write docs + + +yes - fix + + + +Done + + +Done + + + +Issues found?->Done + + +no + + +