with one click
docs-writer-learn
// Use when writing or editing files in src/content/learn/. Provides Learn page structure and tone.
// Use when writing or editing files in src/content/learn/. Provides Learn page structure and tone.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | docs-writer-learn |
| description | Use when writing or editing files in src/content/learn/. Provides Learn page structure and tone. |
Voice: Patient teacher guiding a friend through concepts Tone: Conversational, warm, encouraging
For tone, capitalization, jargon, and prose patterns, invoke /docs-voice.
---
title: Page Title
---
<Intro>
1-3 sentences introducing the concept. Use *italics* for new terms.
</Intro>
<YouWillLearn>
* Learning outcome 1
* Learning outcome 2
* Learning outcome 3-5
</YouWillLearn>
## Section Name {/*section-id*/}
Content with Sandpack examples, Pitfalls, Notes, DeepDives...
## Another Section {/*another-section*/}
More content...
<Recap>
* Summary point 1
* Summary point 2
* Summary points 3-9
</Recap>
<Challenges>
#### Challenge title {/*challenge-id*/}
Description...
<Hint>
Optional guidance (single paragraph)
</Hint>
<Sandpack>
{/* Starting code */}
</Sandpack>
<Solution>
Explanation...
<Sandpack>
{/* Fixed code */}
</Sandpack>
</Solution>
</Challenges>
For pages that introduce a chapter (like describing-the-ui.md, managing-state.md):
<YouWillLearn isChapter={true}>
* [Sub-page title](/learn/sub-page-name) to learn...
* [Another page](/learn/another-page) to learn...
</YouWillLearn>
## Preview Section {/*section-id*/}
Preview description with mini Sandpack example
<LearnMore path="/learn/sub-page-name">
Read **[Page Title](/learn/sub-page-name)** to learn how to...
</LearnMore>
## What's next? {/*whats-next*/}
Head over to [First Page](/learn/first-page) to start reading this chapter page by page!
Important: Chapter intro pages do NOT include <Recap> or <Challenges> sections.
For step-by-step tutorials (like tutorial-tic-tac-toe.md):
<Intro>
Brief statement of what will be built
</Intro>
<Note>
Alternative learning path offered
</Note>
Table of contents (prose listing of major sections)
## Setup {/*setup*/}
...
## Main Content {/*main-content*/}
Progressive code building with ### subsections
No YouWillLearn, Recap, or Challenges
Ends with ordered list of "extra credit" improvements
For pages with heavy API documentation (like typescript.md):
<YouWillLearn>
* [Link to section](#section-anchor)
* [Link to another section](#another-section)
</YouWillLearn>
## Sections with ### subsections
## Further learning {/*further-learning*/}
No Recap or Challenges
All headings require IDs in {/*kebab-case*/} format:
## Section Title {/*section-title*/}
### Subsection Title {/*subsection-title*/}
#### DeepDive Title {/*deepdive-title*/}
ID Generation Rules:
:, ?, !, ., parentheses)Examples:
{/*whats-react*/}{/*step-1-create-the-context*/}{/*conditional-ternary-operator--*/}Show broken/problematic code BEFORE the solution:
// 🔴 Avoid: comment// ✅ Good: commentBuild understanding in layers:
For multi-step processes:
As section headings:
### Step 1: Action to take {/*step-1-action*/}
### Step 2: Next action {/*step-2-next-action*/}
As inline lists:
To implement this:
1. **Declare** `inputRef` with the `useRef` Hook.
2. **Pass it** as `<input ref={inputRef}>`.
3. **Read** the input DOM node from `inputRef.current`.
After Sandpack examples, encourage experimentation:
Help readers build intuition:
"When you're not sure whether some code should be in an Effect or in an event handler, ask yourself why this code needs to run."
<Intro> - First after frontmatter<YouWillLearn> - After Intro (standard/chapter pages)<Note>, <Pitfall>, <DeepDive> placed contextually<Recap> - Before Challenges (standard pages only)<Challenges> - End of page (standard pages only)For component structure and syntax, invoke /docs-components.
For Sandpack file structure, naming conventions, code style, and pedagogical markers, invoke /docs-sandpack.
Link to /learn:
Link to /reference:
[concept name](/learn/page-name)
[`useState`](/reference/react/useState)
[section link](/learn/page-name#section-id)
[MDN](https://developer.mozilla.org/...)
Important: Learn pages typically do NOT use --- dividers. The heading hierarchy provides sufficient structure. Only consider dividers in exceptional cases like separating main content from meta/contribution sections.
Do:
Don't:
--- dividers between sections## Title {/*title-id*/}isChapter={true} and <LearnMore>/docs-components Callout Spacing RulesFor component patterns, invoke /docs-components. For Sandpack patterns, invoke /docs-sandpack.