Step-by-Step Tutorial

Authors an instructional, end-to-end tutorial for a specific technical task. Every step provides complete, runnable code and expected output screenshots/text.

1. Purpose

Enable a developer to successfully complete a single goal from start to finish without getting stuck. A "Tutorial" is a guided journey with prerequisites, sequential numbered actions, and self-checks.

2. When to Use

Use this skill when:

• Writing "Getting Started with Feature X" or "How to deploy Y" documentation.
• Explaining an onboarding workflow to developers.
• User requests: "Write a tutorial on how to do X."

3. When Not to Use

• Do not use for high-level repository documentation; use readme-writer.
• Do not use for autonomous task execution plans; use step-decomposer.

4. Required Inputs

• tutorial_topic: What the reader will build or achieve (string).
• prerequisites: Required tools, software versions, and existing credentials.
• verified_steps: Concrete sequence of actions to perform.

5. Missing-Input Behavior

1. If prerequisites are not specified: list minimum standard tools (e.g. terminal, Git, current LTS runtime).
2. Never write incomplete code snippets with placeholders like // TODO: implement logic.
3. If an API key or token is needed: instruct reader to set environment variable, never hardcode.

6. Procedure

Follow these numbered actions:

1. Action 1: Define Goal & Outcome
   • State what the user will achieve in 1 paragraph.
2. Action 2: State Prerequisites
   • List required software, OS compatibility, and background knowledge.
3. Action 3: Write Sequential Steps
   • Each step has: Context, Code/Command block, and Expected Terminal Output.
4. Action 4: Add Verification Step
   • Provide a final test or curl command to verify success.
5. Action 5: Emit Tutorial
   • Format using Section 8.

7. Decision Rules

• If a command can fail due to permissions: prepend guidance on non-root execution or virtual environments.
• Always provide copy-pasteable commands without leading $ prompts inside code blocks if multi-line.

8. Output Format

Emit the tutorial using this template:

# How to: [Tutorial Title]

[Brief explanation of what will be built and time required.]

## Prerequisites
- [Prerequisite 1]
- [Prerequisite 2]

---

### Step 1: [Action Title]
[Short context explaining what this step does.]

```bash
[Command to run]

Expected Output:

[What the reader should see]

Step 2: [Action Title]

[Complete code block]

Verification

Run the following check to verify your setup:

[Verification command]

Expected result: [Expected return]

Next Steps

• [Pointers to advanced configuration or related skills]

## 9. Verification Checklist
- [ ] Prerequisites list all required tools.
- [ ] Every code snippet is syntactically complete.
- [ ] Expected output is provided for every execution step.
- [ ] Final verification step tests the end-to-end workflow.

## 10. Common Failures and Recovery
| Failure Symptom | Cause | Recovery Action |
| :--- | :--- | :--- |
| Reader gets stuck on missing dependency | Unstated prerequisite | Add explicit installation command in Step 1. |
| Code block fails to run | Missing imports | Include all required import/require statements in snippets. |

## 11. Stop or Escalation Conditions
Stop and ask the user when:
- The tutorial workflow involves paid services or proprietary internal tools not documented.

## 12. Examples

### Example 1: Successful Execution
**Input:**
```text
Topic: Setting up Express with TypeScript
Audience: Junior developer
Steps: npm init, install express + ts-node + typescript, write basic server, run with ts-node.

Output:

# How to Set Up an Express Server with TypeScript

In this tutorial, you will create a minimal, type-safe Express HTTP server from scratch.

## Prerequisites
- Node.js >= 20.0.0
- A terminal with bash or zsh

---

### Step 1: Initialize the Project
Create a new directory and initialize package configuration:

```bash
mkdir express-ts-demo && cd express-ts-demo
npm init -y

Step 2: Install Dependencies

Install Express and the TypeScript developer tooling:

npm install express
npm install -D typescript @types/node @types/express ts-node

Step 3: Create Server Entry File

Create src/server.ts with the following code:

import express, { Request, Response } from 'express';

const app = express();
const PORT = 3000;

app.get('/health', (req: Request, res: Response) => {
  res.json({ status: 'ok' });
});

app.listen(PORT, () => {
  console.log(`Server listening on http://localhost:${PORT}`);
});

Step 4: Verification

Start the server using ts-node:

npx ts-node src/server.ts

In a second terminal, verify with curl:

curl http://localhost:3000/health

Expected Output:

{"status":"ok"}

Next Steps

• Add a tsconfig.json using npx tsc --init.
• Configure a production build script using tsc.

### Example 2: Ambiguous or Missing Input
**Input:**
```text
Write a tutorial about coding.

Output:

### Tutorial Generator: Halted - Ambiguous Topic

- **Status**: Halted

"Coding" is too broad for a step-by-step tutorial. Please specify:
1. The exact workflow or feature (e.g., "How to authenticate users with JWT in Python").
2. The framework or technology stack.
3. The reader's skill level.

Example 3: Expected Final Output

Output:

# How to Parse JSON in Python

Learn how to safely read and parse a JSON string using Python's standard library.

## Prerequisites
- Python >= 3.8

---

### Step 1: Write the Parsing Script
Create `parse_example.py`:

```python
import json

raw_data = '{"name": "Alice", "score": 95}'
parsed = json.loads(raw_data)

print(f"User: {parsed['name']}, Score: {parsed['score']}")

Verification

Run the script:

python3 parse_example.py

Expected Output:

User: Alice, Score: 95