dev-guide-generator

Files (2)

• LICENSE
• SKILL.md

SKILL.md (first lines)

# Dev Guide Generator

**One topic → complete technical tutorial**: Through a structured SOP workflow, transform a technical topic into a comprehensive tutorial covering prerequisites, environment setup, core steps, common error troubleshooting, and advanced topics — all accompanied by a cheatsheet.

## Quick Start

The user simply provides a technical topic or operational goal, and the Agent automatically generates a complete tutorial following this workflow:

```
User: Help me write a Docker beginner's tutorial
Agent: [Outputs complete technical tutorial + Cheatsheet following the SOP workflow]
```

## SOP Workflow

### Phase 1: Topic Scoping & Audience Analysis

**Goal**: Define the tutorial's technical subject, target audience, and scope boundaries.

**Steps**:

1. **Parse the topic**: Identify the core technology, operational goals, and expected deliverables from the user's input
2. **Ask clarifying questions** (up to 4 key questions):
   - What is the target audience's technical level? (Complete beginner / Some experience / Experienced developer)
   - What operating system will the reader be using? (macOS / Windows / Linux / Any)
   - What should the reader be able to do after completing the tutorial? (Specific deliverable)
   - Are there any version or tech stack constraints?
3. **If the user asks to skip clarification**, proceed with these default assumptions:
   - Audience: Has basic programming experience but is unfamiliar with the topic technology
   - Environment: Cover both macOS and Linux (note Windows differences where necessary)
   - Goal: Be able to independently complete a minimal working example

**Output**: Tutorial metadata summary (topic, audience, objective, scope — no more than 150 words)

---

### Phase 2: Prerequisites

**Goal**: List all knowledge and tools the reader needs before starting this tutorial, ensuring there are no knowledge gaps.

**Steps**:

1. **Dependency analysis**:
   - List all technical concepts involved in this tutorial
   - For each concept, determine whether it should be "explained within the tutorial" or "assumed as prior knowledge"
   - Decision rule: If explaining it would digress more than 200 words from the main topic, classify it as a prerequisite

2. **Prerequisites checklist**:
   - Categorize into "Must know" and "Nice to know" tiers
   - Attach a one-line explanation for each: "why you need it"
   - Format:

     ```
     **Must know**:
     - [Concept]: [Why you need it] (Recommended resource)

     **Nice to know**:
     - [Concept]: [What aspects of the tutorial it relates to]
     ```

3. **Self-check rules**:
   - If prerequisites exceed 5 items, consider narrowing the tutorial scope or splitting into a series
   - Every prerequisite must have a publicly available learning resource

**Output**: Tiered prerequisites checklist

---

### Phase 3: Environment Setup

**Goal**: Provide a reproducible environment configuration path so the reader is fully set up before starting the core steps.

**Steps**:

1. **Environment inventory**: List all tools to install/configure with recommended versions
   - Format: `Tool name  Version requirement (e.g., >= x.y) | Purpose`
   - Clearly distinguish "required" from "optional" installations

2. **Installation steps**: Provide commands for each operating system
   - Precede each command with a one-line explanation of what it does
   - Use only officially recommended methods or mainstream package managers
   - Format:

     ```
     **macOS**:
     # Install xxx (via Homebrew)
     brew install xxx

     **Linux (Ubuntu/Debian)**:
     # Install xxx (via apt)
     sudo apt update && sudo apt install -y xxx
     ```

3. **Environment verification**: Provide a verification command and expected output after each tool installation
   - Format:

     ```
     # Verify installation
     xxx --version
     # Expected output: xxx x.y.z
     ```

4. **Self-check rules**:
   - All installation commands must come from official documentation or mainstream package managers — no third-party scripts
   - Never include real API keys, passwords, tokens, or other sensitive values
   - When configuration files are involved, use placeholders (e.g., `YOUR_API_KEY`) and explain how to obtain the real value

**Output**: OS-specific installation and configuration guide + verification commands

---

### Phase 4: Core Steps

**Goal**: Walk the reader through the core operations in a progressive structure, where each step can be independently verified.

**Steps**:

1. **Step planning**:
   - Break the entire operation into 5–10 steps (each focused on one sub-goal)

From zebbern/claude-code-guide, MIT.

More from zebbern/claude-code-guide