When the user wants to create step-by-step technical tutorials, quickstarts, or code walkthroughs. Trigger phrases include "tutorial," "quickstart," "getting started guide," "walkthrough," "step by step," "how to guide," "hands-on guide," or "code tutorial."
When the user wants to create step-by-step technical tutorials, quickstarts, or code walkthroughs. Trigger phrases include "tutorial," "quickstart," "getting started guide," "walkthrough," "step by step," "how to guide," "hands-on guide," or "code tutorial."
Use this skill when you need when the user wants to create step-by-step technical tutorials, quickstarts, or code walkthroughs. Trigger phrases include "tutorial," "quickstart," "getting started guide," "walkthrough," "step by step," "how to guide," "hands-on guide," or "code tutorial.".
This skill helps you create step-by-step tutorials that actually work. Covers prerequisite handling, progressive complexity, troubleshooting sections, and creating those satisfying "it works!" moments.
Before You Start
Load your audience context first. Read .agents/developer-audience-context.md to understand:
Tech stack familiarity (what can you assume they know?)
Environment (macOS, Linux, Windows, cloud)
Why they're learning (job, side project, curiosity)
If the context file doesn't exist, run the developer-audience-context skill first.
Tutorial Types
Type
Length
Purpose
Example
Quickstart
5-10 min
First success ASAP
"Make your first API call"
Tutorial
20-45 min
Learn a concept deeply
"Build a REST API with Node.js"
Workshop
1-3 hours
Comprehensive project
"Build a full-stack app"
Code walkthrough
Varies
Explain existing code
"Understanding our SDK architecture"
The Tutorial Structure
Anatomy of a Great Tutorial
1. Title & Meta
- What you'll build
- Time estimate
- Prerequisites
2. Overview
- What you'll learn
- Final result preview
3. Prerequisites Check
- Environment setup
- Verification commands
4. The Build (Progressive Steps)
- Step 1: Simplest foundation
- Step 2: Add one concept
- Step 3: Add complexity
- [Checkpoint: "It works!" moment]
- Step 4: Continue building
- ...
- [Final checkpoint]
5. What You Built
- Recap
- Complete code
6. Troubleshooting
- Common errors
- Debugging tips
7. Next Steps
- Where to go from here
- Related tutorials
Prerequisites Handling
The Prerequisites Section
Be explicit. Don't make developers guess what they need.
## Prerequisites
Before starting, make sure you have:
| Requirement | Version | Check Command |
|-------------|---------|---------------|
| Node.js | 18+ | `node --version` |
| npm | 9+ | `npm --version` |
| Git | Any | `git --version` |
You should also be comfortable with:
- Basic JavaScript (variables, functions, async/await)
- Command line basics (cd, mkdir, running commands)
- REST API concepts (HTTP methods, JSON)
**New to any of these?** Check out [link to prerequisite tutorial].
Environment Setup Section
Make setup foolproof:
## Setting Up Your Environment### 1. Create Project Directory
\`\`\`bash
mkdir my-awesome-project
cd my-awesome-project
\`\`\`
### 2. Initialize the Project
\`\`\`bash
npm init -y
\`\`\`
You should see output like:
\`\`\`json
{
"name": "my-awesome-project",
"version": "1.0.0",
...
}
\`\`\`
### 3. Install Dependencies
\`\`\`bash
npm install express dotenv
\`\`\`
### 4. Verify Installation
\`\`\`bash
node -e "require('express'); console.log('Express installed!')"
\`\`\`
Expected output: `Express installed!`
Progressive Complexity
The Layer Cake Approach
Build up in understandable layers:
Layer
What It Does
Example
1. Skeleton
Minimum viable code that runs
"Hello World" server
2. Core feature
Primary functionality
Add one API endpoint
3. Real data
Replace hardcoded values
Connect to database
4. Error handling
Production-ready patterns
Add try/catch, validation
5. Polish
Nice-to-haves
Logging, config, tests
Show Progress, Not Perfection
Wrong approach (overwhelming):
// Here's the complete file with everythingconst express = require('express');
const { Pool } = require('pg');
const helmet = require('helmet');
const rateLimit = require('express-rate-limit');
const winston = require('winston');
// ... 200 more lines
// Add this below your existing route
app.get('/api/users', (req, res) => {
res.json([{ id: 1, name: 'Jane' }]);
});
Copy-Paste Friendly Code
The Copy-Paste Checklist
Every code block must pass these tests:
Test
How to Verify
Runs standalone
Copy into new file, execute, it works
Imports included
All require/import statements present
No undefined variables
No references to code from other steps without showing it
Environment agnostic
Works on Mac/Linux/Windows
Comments explain why
Not what (code shows what), but why
Code Block Patterns
File context is critical:
// server.js - Add this to your existing fileconst rateLimit = require('express-rate-limit');
// Add this BEFORE your routesconst limiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15 minutesmax: 100// limit each IP to 100 requests per window
});
app.use(limiter);
// src/index.jsconst express = require('express');
const app = express();
// ✅ ADD THIS: Import your new routeconst userRoutes = require('./routes/users');
// ✅ ADD THIS: Use the route
app.use('/api/users', userRoutes);
app.listen(3000);
"It Works!" Moments
Checkpoints Create Motivation
Every 3-5 steps, give developers a win:
## Checkpoint: Test Your API
Let's make sure everything works before continuing.
**Start your server:**
\`\`\`bash
node server.js
\`\`\`
**In a new terminal, test the endpoint:**
\`\`\`bash
curl http://localhost:3000/api/users
\`\`\`
**You should see:**
\`\`\`json
[{"id": 1, "name": "Jane"}]
\`\`\`
🎉 **It works!** Your API is returning data.
If you don't see this output, check the [Troubleshooting](#troubleshooting) section.
Visual Confirmation
When possible, show what success looks like:
Output Type
How to Show
Terminal output
Code block with expected text
Browser result
Screenshot or description
API response
Formatted JSON
Logs
Code block with log output
Troubleshooting Sections
Common Error Template
## Troubleshooting### "Error: Cannot find module 'express'"**Cause:** Dependencies weren't installed.
**Fix:**
\`\`\`bash
npm install
\`\`\`
---
### "EADDRINUSE: address already in use :::3000"**Cause:** Another process is using port 3000.
**Fix (macOS/Linux):**
\`\`\`bash
# Find the process
lsof -i :3000
# Kill it (replace PID with actual number)
kill -9 PID
\`\`\`
**Or use a different port:**
\`\`\`javascript
app.listen(process.env.PORT || 3001);
\`\`\`
---
### "SyntaxError: Unexpected token"**Cause:** Likely a typo or missing bracket.
**Debug steps:**1. Check the line number in the error
2. Look for missing `,`, `}`, or `)`3. Verify all strings are closed with matching quotes
Proactive Error Prevention
Add warnings before common pitfalls:
⚠️ **Windows users:** Use `set` instead of `export`:
\`\`\`bash
# macOS/Linux
export API_KEY=your_key
# Windows Command Prompt
set API_KEY=your_key
# Windows PowerShell
$env:API_KEY="your_key"
\`\`\`
Tutorial Templates
Quickstart Template (5-10 minutes)
# [Product] Quickstart: [What You'll Do] in 5 Minutes
Get [specific outcome] in under 5 minutes.
## Prerequisites- [Requirement 1]
- [Requirement 2]
## Step 1: Install
\`\`\`bash
npm install your-package
\`\`\`
## Step 2: Configure
Create a `.env` file:
\`\`\`
API_KEY=your_key_here
\`\`\`
## Step 3: Write Code
Create `index.js`:
\`\`\`javascript
// Complete, working code
\`\`\`
## Step 4: Run It
\`\`\`bash
node index.js
\`\`\`
Expected output:
\`\`\`
[Output here]
\`\`\`
## 🎉 You Did It!
You just [accomplished thing].
**Next steps:**
- [Link to full tutorial]
- [Link to API docs]
- [Link to examples repo]
Full Tutorial Template (20-45 minutes)
# Build a [Thing] with [Technology]
Learn how to [outcome] by building [specific project].
| | |
|---|---|
| **Time** | 30 minutes |
| **Level** | Intermediate |
| **Prerequisites** | Node.js 18+, basic JavaScript |
## What You'll Build
[Screenshot or diagram of final result]
By the end, you'll have:
- ✅ [Capability 1]
- ✅ [Capability 2]
- ✅ [Capability 3]
## Prerequisites### Required Software
| Tool | Version | Verify |
|------|---------|--------|
| Node.js | 18+ | `node -v` |
### Required Knowledge- [Concept 1] — [link to learn]
- [Concept 2] — [link to learn]
## Step 1: Project Setup
[Setup instructions with verification]
**Checkpoint:** You should see `[expected output]`.
## Step 2: [First Feature]
[Instructions]
**Checkpoint:** Test with `[command]`.
## Step 3: [Second Feature]
[Instructions]
## Step 4: [Third Feature]
[Instructions]
**Checkpoint:** Your app should now [do thing].
## Complete Code
Here's everything together:
\`\`\`javascript
// Full final code
\`\`\`
## Troubleshooting### [Common Error 1]
[Solution]
### [Common Error 2]
[Solution]
## What You Learned- [Key concept 1]
- [Key concept 2]
- [Key concept 3]
## Next Steps-**Go deeper:** [Link to advanced tutorial]
-**Explore:** [Link to related feature]
-**Get help:** [Link to Discord/community]
