Learn Page Writer
Overview
The Learn Page Writer skill serves as a comprehensive guide for creating educational content within the src/content/learn/ directory. This skill ensures consistent structure, tone, and formatting across all learning materials, making complex technical concepts accessible to readers at various skill levels.
As a patient teacher, the agent guides users through concepts with a conversational and warm approach. The skill emphasizes progressive complexity, problem-first teaching methodologies, and interactive learning experiences that encourage reader engagement and experimentation.
Usage
To utilize this skill effectively, invoke the appropriate documentation endpoints based on your content needs:
- Voice & Style: Call
/docs-voicefor tone, capitalization, jargon, and prose patterns - Component Patterns: Call
/docs-componentsfor component structure and syntax guidelines - Sandpack Integration: Call
/docs-sandpackfor file structure, naming conventions, and code style
When creating new content, follow the established page structure variants to maintain consistency across the learning platform.
Guidelines
Operational Mode
This section outlines the core operational guidelines for content creation and maintenance.
Page Structure Variants
Standard Learn Page (Most Common)
---
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>
Chapter Introduction Page
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.
Tutorial Page
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
Reference-Style Learn Page
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
Heading ID Conventions
All headings require IDs in {/*kebab-case*/} format:
## Section Title {/*section-title*/}
### Subsection Title {/*subsection-title*/}
#### DeepDive Title {/*deepdive-title*/}
ID Generation Rules:
- Lowercase everything
- Replace spaces with hyphens
- Remove apostrophes, quotes
- Remove or convert special chars (
:,?,!,., parentheses)
Examples:
- "What's React?" →
{/*whats-react*/} - "Step 1: Create the context" →
{/*step-1-create-the-context*/} - "Conditional (ternary) operator (? :)" →
{/*conditional-ternary-operator--*/}
Teaching Patterns
Problem-First Teaching
Show broken/problematic code BEFORE the solution:
- Present problematic approach with
// 🔴 Avoid:comment - Explain WHY it's wrong (don't just say it is)
- Show the solution with
// ✅ Good:comment - Invite experimentation
Progressive Complexity
Build understanding in layers:
- Show simplest working version
- Identify limitation or repetition
- Introduce solution incrementally
- Show complete solution
- Invite experimentation: "Try changing..."
Numbered Step Patterns
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`.
Interactive Invitations
After Sandpack examples, encourage experimentation:
- "Try changing X to Y. See how...?"
- "Try it in the sandbox above!"
- "Click each button separately:"
- "Have a guess!"
- "Verify that..."
Decision Questions
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."
Component Placement Order
<Intro>- First after frontmatter<YouWillLearn>- After Intro (standard/chapter pages)- Body content with
<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.
Code Examples
For Sandpack file structure, naming conventions, code style, and pedagogical markers, invoke /docs-sandpack.
Cross-Referencing
When to Link
Link to /learn:
- Explaining concepts or mental models
- Teaching how things work together
- Tutorials and guides
- "Why" questions
Link to /reference:
- API details, Hook signatures
- Parameter lists and return values
- Rules and restrictions
- "What exactly" questions
Link Formats
[concept name](/learn/page-name)
[`useState`](/reference/react/useState)
[section link](/learn/page-name#section-id)
[MDN](https://developer.mozilla.org/...)
Section Dividers
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's and Don'ts
Do:
- Use "you" to address the reader
- Show broken code before fixes
- Explain behavior before naming concepts
- Build concepts progressively
- Include interactive Sandpack examples
- Use established analogies consistently
- Place Pitfalls AFTER explaining concepts
- Invite experimentation with "Try..." phrases
Don't:
- Use "simple", "easy", "just", or time estimates
- Reference concepts not yet introduced
- Skip required components for page type
- Use passive voice without reason
- Place Pitfalls before teaching the concept
- Use
---dividers between sections - Create unnecessary abstraction in examples
- Place consecutive Pitfalls or Notes without separating prose (combine or separate)
Critical Rules
- All headings require IDs:
## Title {/*title-id*/} - Chapter intros use
isChapter={true}and<LearnMore> - Tutorial pages omit YouWillLearn/Recap/Challenges
- Problem-first teaching: Show broken → explain → fix
- No consecutive Pitfalls/Notes: See
/docs-componentsCallout Spacing Rules
For component patterns, invoke /docs-components. For Sandpack patterns, invoke /docs-sandpack.
Examples
Example 1: Creating a New Tutorial Page
When developing a new tutorial, follow the tutorial page structure variant. Begin with a clear introduction that outlines the learning objectives and expected outcomes.
Example 2: Building Reference Documentation
For API documentation, utilize the reference-style learn page format with comprehensive section links and detailed component documentation.
Example 3: Implementing Interactive Learning
Incorporate Sandpack examples throughout the content to enable hands-on learning experiences. Encourage readers to experiment with provided code samples.
Note: This skill operates as a continuous learning companion, adapting to evolving content requirements while maintaining consistent quality standards across all learning materials.