This skill scaffolds a complete content track — the full set of files needed to add a new learning path to the tutorial, following the exact patterns established by Foundation, Advanced, and Terminal tracks.
When to Use This Skill
- When adding a new learning path (e.g., "Mobile", "Data", "Enterprise")
- When expanding the tutorial with a new series of modules
- When cloning the architecture for a related tutorial site
- When understanding how the existing tracks are wired together
Architecture Overview
A track consists of 7 coordinated file groups:
1. Content files → src/content/<track>/module-*.md
2. Data parser module → src/data/<track>Content.ts
3. Home page → src/pages/<Track>HomePage.tsx
4. Lesson page → src/pages/<Track>LessonPage.tsx
5. Summary page → src/pages/<Track>SummaryPage.tsx
6. Routes → src/App.tsx (lazy imports + Route entries)
7. Navigation links → src/components/SiteHeader.tsx (header nav)
Existing Tracks Reference
| Track | Route | Content Dir | Data Module | Step Prefix | Modules |
|---|---|---|---|---|---|
| Foundation | /learn/foundation/… |
tutorial/ |
tutorialContent.ts |
Step N: |
Parts 0-8 |
| Advanced | /learn/agentic/… |
advanced/ |
advancedContent.ts |
Step A1: |
Modules A-E |
| Terminal | /learn/terminal/… |
terminal/ |
terminalContent.ts |
Step F1: |
Modules F-H |
Legacy routes (
/lesson/,/advanced/,/terminal/) still work via redirects inApp.tsxbut should not be used in new code.
Key Differences Between Tracks
| Feature | Foundation | Advanced | Terminal |
|---|---|---|---|
| Template variables | {{projectName}} etc. |
None (isAdvanced=true) | None |
| Prompt type | Single per step | Multiple per step | Multiple + metaPrompt |
| Prompt number format | 1, 2, 3 |
A1, B2, C3 |
F1, G2, H3 |
| Step interface | Step (number prompt) |
Step (string prompt) |
TerminalStep |
| Module interface | Part |
Module |
TerminalModule |
| Meta-prompts | No | No | Yes (=== separator) |
| Home page theme | Default theme | Gradient/glass theme | Terminal green CRT |
Step-by-Step: Creating a New Track
Step 1: Plan the track identity
Decide on:
| Decision | Convention | Example |
|---|---|---|
| Track name | PascalCase | Cloud |
| Route prefix | lowercase | /cloud/ |
| Content directory | lowercase | src/content/cloud/ |
| Module letter prefix | Sequential after H | I, J, K |
| Step prefix | Letter + number | Step I1: |
| Prompt prefix | Same letter | I1, I2, J1 |
Step 2: Create content markdown files
Create src/content/<track>/module-<letter>-<slug>.md:
---
id: module-<letter>
number: <N>
title: Module Title
subtitle: X minutes — What you'll learn
---
## step: why-this-matters
### title: Why This Module Matters
Introductory content explaining motivation.
## step: first-concept
### title: Step <L>1: First Concept Title
Content explaining the concept.
:::prompt
number: <L>1
title: Prompt Title
---
The actual prompt text that users will copy.
:::
## step: checkpoint
### title: ✅ Checkpoint
Verification section.
Module letter conventions:
- Use
import.meta.globpattern:module-*.md - Number field in frontmatter determines sort order
- Step IDs must be globally unique across the track (not across all tracks)
Step 3: Create the data parser module
Create src/data/<track>Content.ts. Use advancedContent.ts as the base template since it supports multiple prompts per step:
export interface <Track>Step {
id: string
title: string
content: string
prompt?: {
number: string
title: string
code: string
metaPrompt?: string // Include if track supports meta-prompts
}
prompts?: {
number: string
title: string
code: string
metaPrompt?: string
}[]
}
export interface <Track>Module {
id: string
number: number
title: string
subtitle: string
steps: <Track>Step[]
}
const moduleFiles = import.meta.glob<string>('../content/<track>/module-*.md', {
eager: true,
query: '?raw',
import: 'default'
}) as Record<string, string>
The rest of the module follows the exact same parsing pipeline:
normalizeLF()— normalize\r\nto\nparseKeyValueBlock()— parsekey: valuelinesparseFrontmatter()— extract YAML frontmatter and bodyparsePromptBlocks()— extract:::promptblocks, replace with:::prompt-placeholder:::parseSteps()— split on## step:, extract titlesparseModuleMarkdown()— combine frontmatter + steps into moduleload<Track>Data()— cached async loader<track>SummaryContent— workflow, quickReference, troubleshooting, learned objects
If the track uses meta-prompts (like Terminal), include the === separator parsing in parsePromptBlocks():
const metaSeparator = '\n===\n'
const metaSepIndex = codeBlock.indexOf(metaSeparator)
let metaPrompt: string | undefined
if (metaSepIndex !== -1) {
metaPrompt = codeBlock.slice(metaSepIndex + metaSeparator.length).trim()
codeBlock = codeBlock.slice(0, metaSepIndex)
}
If the track uses template variables (like Foundation), import resolveContent from tutorialContent.ts or replicate the applyTemplate() function.
Step 4: Create page components
4a. Home page — src/pages/<Track>HomePage.tsx
import { Link } from 'react-router-dom'
import { Card } from '@/components/ui/card'
import { Badge } from '@/components/ui/badge'
import { Button } from '@/components/ui/button'
import { load<Track>Data, <Track>Module } from '@/data/<track>Content'
import { ArrowRight, ArrowLeft } from '@phosphor-icons/react'
import { useEffect, useState } from 'react'
export function <Track>HomePage() {
const [modules, setModules] = useState<<Track>Module[]>([])
const [isLoading, setIsLoading] = useState(true)
useEffect(() => {
load<Track>Data().then((data) => {
setModules(data)
setIsLoading(false)
})
}, [])
return (
<div className="min-h-[calc(100vh-56px)] bg-background">
<div className="mx-auto max-w-4xl px-6 py-12 lg:px-12 lg:py-16">
{/* Hero, back link, module cards, summary link, start button */}
</div>
</div>
)
}
Key patterns:
- Async data loading with
useState+useEffect - Module cards are
<Link>to/<track>/module/${module.id} - Summary link points to
/<track>/summary - Back link returns to
/(Foundation) or previous track
4b. Lesson page — src/pages/<Track>LessonPage.tsx
Clone from AdvancedLessonPage.tsx and update:
- Data import:
load<Track>Dataand<Track>Module - Route param:
moduleIdfromuseParams() - Step deep-linking via optional
:stepIdparam IntersectionObserverfor tracking visible steps- NavigationSidebar with parts/modules mapped
- StepCard rendering with
isAdvanced={true}(unless the track uses template variables) - Progress calculation and previous/next navigation
4c. Summary page — src/pages/<Track>SummaryPage.tsx
Clone from AdvancedSummaryPage.tsx and update:
- Import
<track>SummaryContentfrom data module - Render workflow steps, quick reference, troubleshooting, learned sections
- Back link to track home
Step 5: Add routes to App.tsx
Add lazy imports and routes:
// In lazy import section:
const <Track>HomePage = lazy(() => import('@/pages/<Track>HomePage').then(m => ({ default: m.<Track>HomePage })))
const <Track>LessonPage = lazy(() => import('@/pages/<Track>LessonPage').then(m => ({ default: m.<Track>LessonPage })))
const <Track>SummaryPage = lazy(() => import('@/pages/<Track>SummaryPage').then(m => ({ default: m.<Track>SummaryPage })))
// In Routes — use /learn/:pathId routing pattern:
<Route path="/learn/<track>" element={<<Track>HomePage />} />
<Route path="/learn/<track>/:moduleId" element={<<Track>LessonPage />} />
<Route path="/learn/<track>/:moduleId/:stepId" element={<<Track>LessonPage />} />
<Route path="/learn/<track>/summary" element={<<Track>SummaryPage />} />
Register the path in
src/data/paths.ts(official) orsrc/content/community/<id>/path.json(community) so it appears in the catalog.
Step 6: Add header navigation
In src/components/SiteHeader.tsx, add a link to the new track in the navigation menu, following the existing pattern for Advanced/Terminal links.
Step 7: Create instruction file (optional)
If the track has special content conventions, create .github/instructions/<track>-content.instructions.md with an applyTo: src/content/<track>/** pattern.
Summary Content Template
Every track needs a summary content object with 4 sections:
export const <track>SummaryContent = {
workflow: {
title: 'The <Track> Workflow',
description: "Here's what you've mastered:",
steps: [
'STEP 1 description',
'STEP 2 description',
// 5-10 items summarizing the complete workflow
]
},
quickReference: {
title: 'Quick Reference: <Track> Prompts',
items: [
{ when: 'Activity description', prompts: 'PROMPT I1, I2' },
// One entry per logical activity
]
},
troubleshooting: {
title: '<Track> Troubleshooting',
items: [
{
problem: 'Problem description',
prevention: 'How to prevent it',
solution: 'How to fix it'
},
// 5-10 common issues
]
},
learned: {
title: "What You've Mastered",
items: [
'Key concept 1',
'Key concept 2',
// One item per major learning
],
closing: 'Motivational closing paragraph.'
}
}
Validation
PowerShell: Verify track wiring
param(
[string]$TrackName = "cloud",
[string]$TrackPascal = "Cloud"
)
Write-Host "`n=== TRACK AUDIT: $TrackPascal ===" -ForegroundColor Cyan
# 1. Content files
$contentFiles = Get-ChildItem "src/content/$TrackName/module-*.md" -ErrorAction SilentlyContinue
Write-Host "`n[Content Files]" -ForegroundColor Yellow
if ($contentFiles) {
$contentFiles | ForEach-Object { Write-Host " $_" }
} else {
Write-Host " NONE FOUND" -ForegroundColor Red
}
# 2. Data module
$dataFile = "src/data/${TrackName}Content.ts"
Write-Host "`n[Data Module]" -ForegroundColor Yellow
if (Test-Path $dataFile) {
Write-Host " $dataFile exists" -ForegroundColor Green
$exports = Select-String -Path $dataFile -Pattern "export (const|interface|function|async)"
$exports | ForEach-Object { Write-Host " $($_.Line.Trim())" }
} else {
Write-Host " $dataFile MISSING" -ForegroundColor Red
}
# 3. Page components
Write-Host "`n[Page Components]" -ForegroundColor Yellow
@("HomePage", "LessonPage", "SummaryPage") | ForEach-Object {
$page = "src/pages/${TrackPascal}$_.tsx"
$exists = Test-Path $page
$color = if ($exists) { "Green" } else { "Red" }
$status = if ($exists) { "exists" } else { "MISSING" }
Write-Host " $page — $status" -ForegroundColor $color
}
# 4. Routes
Write-Host "`n[Routes in App.tsx]" -ForegroundColor Yellow
$appContent = Get-Content "src/App.tsx" -Raw
$routePattern = "/$TrackName"
if ($appContent -match [regex]::Escape($routePattern)) {
Write-Host " Routes for /$TrackName found" -ForegroundColor Green
} else {
Write-Host " Routes for /$TrackName MISSING" -ForegroundColor Red
}
# 5. Header navigation
Write-Host "`n[Header Navigation]" -ForegroundColor Yellow
$headerContent = Get-Content "src/components/SiteHeader.tsx" -Raw
if ($headerContent -match [regex]::Escape("/$TrackName")) {
Write-Host " SiteHeader links to /$TrackName" -ForegroundColor Green
} else {
Write-Host " SiteHeader MISSING link to /$TrackName" -ForegroundColor Red
}
# 6. Build
Write-Host "`n[Build Check]" -ForegroundColor Yellow
Write-Host " Run: npm run build"
Write-Host "`n=== END AUDIT ===" -ForegroundColor Cyan
Checklist
Before completing a new track:
- Content markdown files created in
src/content/<track>/ - Each file has valid frontmatter (
id,number,title,subtitle) - Steps follow
## step:/### title:format - Prompts use letter-prefixed numbers (
I1,J1, etc.) - Data parser module created with proper interfaces
-
load<Track>Data()exports cached async loader - Summary content object has all 4 sections
- Home page shows module list with links
- Lesson page renders steps with navigation
- Summary page renders all summary sections
- All 3 pages are lazy-loaded in
App.tsx - All 4 routes added (
home,module/:id,module/:id/:stepId,summary) - Header navigation updated
-
npm run buildsucceeds - All modules render correctly in the browser
- Navigation between modules works
- Deep-linking to steps works (
/<track>/module/<id>/<stepId>)