# Technical Tutorials - Detailed Guide

> This file contains the detailed procedure and reference material extracted from `SKILL.md` for focused loading. The root skill defines activation, examples, safety constraints, and limitations.

## Before You Start

**Load your audience context first.** Read `.agents/developer-audience-context.md` to understand:

- Developer skill level (beginner, intermediate, senior)
- 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 or named skill is unavailable, infer the audience from the request and ask only for consequential missing requirements. Do not claim to have loaded absent context.

---


## 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
```

---


## 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):
```javascript
// Here's the complete file with everything
const express = require('express');
const { Pool } = require('pg');
const helmet = require('helmet');
const rateLimit = require('express-rate-limit');
const winston = require('winston');
// ... 200 more lines
```

**Right approach** (progressive):

**Step 1: Basic server**
```javascript
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000, "127.0.0.1", () => {
  console.log('Server running on http://localhost:3000');
});
```

**Step 2: Add your first route**
```javascript
// 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

Runnable examples must pass these tests. Clearly label incremental fragments and template placeholders with their file context; they are not standalone programs:

| 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:**

```javascript
// server.js - Add this to your existing file
const rateLimit = require('express-rate-limit');

// Add this BEFORE your routes
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per window
});

app.use(limiter);
```

**Show file structure:**

```
my-project/
├── src/
│   ├── index.js      ← You're editing this
│   ├── routes/
│   │   └── users.js
│   └── db/
│       └── connection.js
├── package.json
└── .env
```

**Highlight changes in context:**

```javascript
// src/index.js
const express = require('express');
const app = express();

// ✅ ADD THIS: Import your new route
const userRoutes = require('./routes/users');

// ✅ ADD THIS: Use the route
app.use('/api/users', userRoutes);

app.listen(3000, "127.0.0.1");
```

---


## "It Works!" Moments

### Checkpoints Create Motivation

Every 3-5 steps, give developers a win:

```markdown
## 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

```markdown
## 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

# Confirm it belongs to this tutorial, then stop it with Ctrl-C in its terminal.
# Do not terminate an unrelated service; choose another port instead.
\`\`\`

**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:

```markdown
⚠️ **Credentials:** Have the user enter the key through a non-echoed local prompt or an existing secret manager. Do not paste secret assignments into shell history, chat, screenshots or a committed tutorial. A PowerShell SecureString is not directly usable as an environment-variable value. Supply shell-specific non-echoed input instructions, and discard the temporary input after the request.

```

---


## Tutorial Templates

### Quickstart Template (5-10 minutes)

```markdown
# [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

Read the required credential from a non-echoed local input or existing secret manager; document its environment-variable name without putting a literal secret assignment in the tutorial. If a local `.env` is chosen, exclude it from Git and show the actual loader configuration.

## 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)

```markdown
# Build a [Thing] with [Technology]

Learn how to [outcome] by building [specific project].

| | |
|---|---|
| **Time** | 30 minutes |
| **Level** | Intermediate |
| **Prerequisites** | a supported Node.js LTS version verified against the project, 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 | supported project LTS | `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]
```

---


## Quality Checklist

Before publishing, verify:

### Code Quality
- [ ] Every claimed runnable final example was tested; fragments/placeholders are labeled
- [ ] All imports/requires are included
- [ ] Expected output is shown
- [ ] Error handling is included
- [ ] Environment variables use `.env` pattern

### Structure Quality
- [ ] Prerequisites are explicit
- [ ] Time estimate is accurate (test it!)
- [ ] Checkpoints every 3-5 steps
- [ ] Final complete code is provided
- [ ] Troubleshooting covers likely errors

### Accessibility
- [ ] Works on Mac, Linux, AND Windows
- [ ] Commands are labeled for the shells actually tested; provide equivalents where required
- [ ] File paths use correct separators
- [ ] No assumptions about installed tools

---


## Tools

| Tool | Use Case |
|------|----------|
| **[Octolens](https://octolens.com)** | Find common questions and errors developers encounter. Monitor Stack Overflow and GitHub issues for troubleshooting content. |
| **Replit/CodeSandbox** | Embed runnable examples |
| **Carbon/Ray.so** | Beautiful code screenshots |
| **Excalidraw** | Architecture diagrams |
| **Terminalizer** | Record terminal sessions |
| **Loom** | Quick video supplements |

---


## Related Skills

- `developer-audience-context` — Understand skill level and environment
- `devrel-content` — General technical writing principles
- `developer-onboarding` — Optimize time to first success
- `developer-seo` — Get tutorials found via search

Do not claim a tutorial was executed or cross-platform verified from inspection alone. These templates contain placeholders and are not a tested SDK integration. Use synthetic data and local-only demo listeners; avoid logging credentials or real user payloads.