SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdev-guide-writer

dev-guide-writer

Writing & research

View repository

Updated 11-06 16:21

About this skill

Tech Tutorial Builder

One topic → complete technical tutorial: Through a structured SOP process, transform a technical topic into a complete tutorial including prerequisites, environment setup, core steps, common error troubleshooting, and advanced extensions, with an accompanying cheat sheet.

Quick Start

The user only needs to provide a technical topic or operation goal, and the Agent automatically generates a complete tutorial according to the following process:

用户：帮我写一个 Docker 入门教程
Agent：[按 SOP 流程输出完整技术教程 + Cheatsheet]

SOP Process

Phase 1: Topic Positioning and Audience Analysis

Goal: Clarify the tutorial's technical topic, target readers, and scope boundaries.

Operation Steps：

  1. Parse the topic: Identify the core technology, operation goal, and expected deliverables from the user input
  2. Ask clarifying questions(up to 4 key questions):
    • What is the target reader's technical level? (zero foundation / some foundation / experienced developer)
    • What is the reader's operating system environment? (macOS / Windows / Linux / not limited)
    • What should the reader be able to do after completing the tutorial? (specific deliverable outcomes)
    • Are there any constraints on specific versions or tech stacks?
  3. If the user requests skipping clarification, continue based on the following default assumptions:
    • Reader: has basic programming experience but is unfamiliar with the technology
    • Environment: cover both macOS and Linux (note Windows differences when necessary)
    • Goal: be able to independently complete a minimal working example

Output: Tutorial metadata summary (topic, audience, goal, scope, no more than 150 characters)

Phase 2: Prerequisites Breakdown (Prerequisites)

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

Operation Steps：

  1. Knowledge dependency analysis：

    • List all technical concepts involved in this tutorial
    • Determine item by item: whether the concept is "explained in the tutorial" or "should already be mastered by the reader"
    • Judgment criterion: if explaining it would deviate from the topic by more than 200 characters, classify it as prerequisite knowledge

  2. Prerequisite knowledge list：

    • Classify into two levels: "must master" and "understand only"

    • Each item includes a one-sentence explanation of "why it is needed"

    • Format:

      **必须掌握**：
- [知识点]：[为什么需要它]（推荐学习资源名称）

**了解即可**：
- [知识点]：[在教程中会涉及哪些方面]

  3. Self-check rules：

    • If there are more than 5 prerequisite knowledge items, consider narrowing the tutorial scope or splitting it into a tutorial series
    • Each prerequisite knowledge item must have publicly available learning resources for reference

Output: Layered prerequisite knowledge list

Phase 3: Environment Setup (Environment Setup)

Goal: Provide a reproducible environment configuration path to ensure the reader's environment is ready before starting the core steps.

Operation Steps：

  1. Environment checklist: List all tools that need to be installed/configured and recommended versions

    • Format:工具名 版本要求（如 >= x.y）| 用途说明
    • Clearly distinguish between "required installation" and "optional installation"

  2. Installation steps: provide commands separately for each operating system

    • Before each command, use one sentence to explain "what this command does"

    • Installation commands must only use officially recommended methods or mainstream package managers

    • Format:

      **macOS**：
# 安装 xxx（通过 Homebrew）
brew install xxx

**Linux (Ubuntu/Debian)**：
# 安装 xxx（通过 apt）
sudo apt update && sudo apt install -y xxx

  3. Environment verification: after each tool is installed, provide a verification command and expected output

    • Format:

      # 验证安装
xxx --version
# 预期输出：xxx x.y.z

  4. Self-check rules：

    • All installation commands must come from official documentation or mainstream package managers; do not use third-party scripts
    • Do not include real values of any sensitive information such as API Keys, passwords, or tokens
    • When configuration files are involved, use placeholders (such as YOUR_API_KEY) and explain how to obtain them

Output: installation and configuration guide by operating system + verification commands

Phase 4: Core Steps

Goal: guide readers through the core operations from scratch in a progressive structure, with each step independently verifiable.

Operation steps：

  1. Step planning：

    • Split the entire operation into 5-10 steps (each step focuses on one sub-goal)
    • Order the steps strictly according to dependencies
    • Each step includes: step number, title, and goal description

  2. Step writing format：

    #### 步骤 N：[步骤标题]

**目标**：[这一步完成后达到什么状态]

**操作**：
[代码块或操作说明]

**解释**：
- [逐行/逐段解释关键部分的含义]

**验证**：
[运行什么命令/检查什么结果来确认这一步成功]
预期输出：[具体的预期结果]

  3. Writing standards：

    • Code blocks must specify the language type (such as bash、python）
    • Placeholders use all-uppercase + underscore format (such as YOUR_PROJECT_NAME), and their meaning is explained when they first appear
    • Each code block must not exceed 30 lines; if it does, split it and explain it in sections
    • Use relative paths for file paths, and state the project root directory at the beginning
    • Each step must end with a verification step

  4. Progressive complexity：

    • First 1-3 steps: minimal runnable example (Hello World level)
    • Middle steps: gradually add features for real scenarios
    • Last 1-2 steps: combine everything into a complete example

Output: numbered step list, each step includes operation + explanation + verification

Phase 5: Common Errors and Troubleshooting

Goal: anticipate problems readers may encounter and provide a direct path from error messages to solutions.

Operation steps：

  1. Error collection: based on the technical topic, list 5-8 of the most common error scenarios

    • Sources: environment configuration errors, version incompatibility, permission issues, typos, network issues, etc.

  2. Error entry format：

    **报错 N：[错误信息摘要]**

完整错误信息：
[实际错误输出]

原因：[一句话解释为什么会出现这个错误]

解决方案：
[具体的修复命令或操作步骤]

验证修复：
[运行什么来确认问题已解决]

  3. Writing standards：

    • Error messages must be real (do not fabricate error messages)
    • Solutions must correspond to specific operations; do not use vague guidance such as "please check the configuration"
    • If an error has multiple possible causes, arrange them from highest to lowest probability
    • When permission issues are involved, explain why the permission is needed instead of directly giving sudo or chmod 777

  4. Self-check rules：

    • Solutions must not include operations that may cause security risks (such as chmod 777, disabling the firewall, etc.)
    • Readers are not advised to disable security features to "solve" the problem

Output: Structured troubleshooting table for errors

Phase 6: Advanced Topics

Goal: Point readers who have completed the basic tutorial toward advanced directions, providing a learning path from beginner to in-depth.

Steps：

  1. Recommended advanced topics(3-5 directions):

    • For each direction, explain in one paragraph: what it is, why it is worth learning, and what scenarios it applies to

    • Mark the difficulty level: Intermediate / Advanced

    • Format:

      **方向 N：[主题名称]** ｜ 难度：[中级/高级]

[一段话说明]

推荐资源：
- [资源名称]（[类型：文档/书籍/课程]）

  2. Hands-on project suggestions：

    • Provide 2-3 small projects that can be completed independently using the knowledge from this tutorial
    • Each project includes: project name, one-sentence description, and the knowledge points involved

  3. Best practice tips(3-5 items):

    • Key differences between production environments and tutorial environments
    • Security considerations
    • Performance optimization directions

Output: Advanced learning roadmap + hands-on project suggestions + best practices

Phase 7: Cheatsheet

Goal: Distill the essence of the tutorial into a one-page cheatsheet for readers' daily reference.

Steps：

  1. Cheatsheet structure：

    # [技术名称] Cheatsheet

## 环境信息
| 项目 | 命令/路径 |
|------|-----------|
| 安装 | `命令` |
| 版本检查 | `命令` |
| 配置文件位置 | `路径` |

## 常用命令
| 操作 | 命令 | 说明 |
|------|------|------|
| xxx  | `xxx` | xxx |

## 常用代码片段
[最多 5 个高频使用的代码片段，每个不超过 10 行]

## 快速排错
| 症状 | 可能原因 | 快速修复 |
|------|----------|----------|
| xxx  | xxx      | `xxx`    |

  2. Writing guidelines：

    • Keep the total length of the cheatsheet within 2 printable A4 pages
    • Commands must be complete and directly copy-pasteable for execution
    • Do not include explanatory text; keep only the "what to do → how to do it" mapping
    • Order items by frequency of use, from high to low

Output: One-page Cheatsheet

Phase 8: Document Assembly and Output

Goal: Assemble the outputs of the first seven phases into a complete tutorial document.

Tutorial document template：

# [技术主题] 完整教程

> 最后更新：[当前日期] | 适用版本：[版本号]
> 难度：[入门/中级/高级] | 预计耗时：[N 小时/分钟]

## 教程概览

[Phase 1 的教程元信息摘要，说明学完能做什么]

## 1. 前置知识

[Phase 2 的前置知识清单]

## 2. 环境搭建

[Phase 3 的安装配置指南]

## 3. 核心步骤

[Phase 4 的编号步骤列表]

## 4. 常见报错与排查

[Phase 5 的报错排查表]

## 5. 进阶拓展

[Phase 6 的进阶路线图和实战项目]

## 6. Cheatsheet 速查表

[Phase 7 的速查表]

## 附录

- 术语表（如有领域专业术语，用表格列出：术语 | 解释）
- 参考链接（官方文档、社区资源等）

Document output requirements：

  • Label the language type for all code blocks
  • All commands must be directly copy-pasteable for execution (without distracting characters such as line numbers and prompts)
  • Use for all placeholders YOUR_XXX format and explain on first occurrence
  • Configuration files must not contain real keys or tokens
  • Use the current actual date for dates

Flow control rules

Interaction mode selection

Select the mode based on the level of detail in the user's input:

User input Mode Behavior
Only a technology name (e.g., "Docker tutorial") Guided mode Execute Phase 1 questions and continue after the user answers
Has a specific goal (e.g., "Deploy a Node.js app with Docker") Semi-automatic mode Ask 1-2 key questions while starting to plan the steps
Detailed description (including audience, environment, and goal) Fully automatic mode Start output directly from Phase 2
The user says "just write it / no need to ask" Quick mode Output the complete tutorial directly based on default assumptions

Quality checklist

Before outputting the final tutorial, check each item:

  • The prerequisites list is complete, with no knowledge gaps
  • Every command in the environment setup steps has a verification method
  • Each core step contains all three parts: "operation + explanation + verification"
  • The dependencies between steps are correct (no situation where an uninstalled tool is used)
  • There are no fewer than 5 common errors, and the solutions are specific and actionable
  • There are at least 3 advanced directions, with recommended resources
  • The Cheatsheet can be used independently and includes common commands and troubleshooting information
  • All code blocks are labeled with a language type
  • It does not contain any hardcoded keys, tokens, or personal paths
  • It does not contain operational suggestions that may cause security problems (such as chmod 777）
  • It does not depend on any paid API or tool that requires a paid subscription (unless that tool itself is the tutorial topic)

Iterative optimization

If the user provides feedback on the tutorial:

  1. Locate the Phase involved in the feedback
  2. Re-execute from that Phase
  3. Cascade updates downward to all affected content (e.g., environment changes require synchronously updating subsequent steps and the Cheatsheet)
  4. Maintain the continuity of step numbering

Applicable scenarios

This tutorial generator is suitable for the following types of technical tutorials:

  • Tool usage: Tutorials on using tools such as Git, Docker, Kubernetes, Vim, etc.
  • Environment setup: Development environments, CI/CD pipelines, server configuration, etc.
  • Programming introductions: Language introductions, framework onboarding, library usage, etc.
  • Operations and maintenance procedures: Operation manuals for deployment, monitoring, logging, backup and recovery, etc.
  • Data processing: Database operations, ETL processes, data analysis tool usage, etc.