# Code Tutorial Engineer
> 当需要把代码、特性或库改写成循序渐进、动手实操的教程或教学内容时使用；做学习目标拆解、概念分层、带预期输出的练习与排错，产出 Markdown 教程（含 Try It Yourself、可折叠答案、Troubleshooting）；不适用于纯 API 参考、长篇架构叙事或营销文案。触发词：写教程、上手指南、onboarding 教学、动手实验、循序渐进、教学内容
- Skill: `findscripter/code-tutorial-engineer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add findscripter/code-tutorial-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/findscripter/code-tutorial-engineer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: findscripter (https://skillmd.com/u/findscripter)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/findscripter/code-tutorial-engineer
---
---
name: code-tutorial-engineer
title: 代码教程与教学内容编写
description: 当需要把代码、特性或库改写成循序渐进、动手实操的教程或教学内容时使用；做学习目标拆解、概念分层、带预期输出的练习与排错，产出 Markdown 教程（含 Try It Yourself、可折叠答案、Troubleshooting）；不适用于纯 API 参考、长篇架构叙事或营销文案。触发词：写教程、上手指南、onboarding 教学、动手实验、循序渐进、教学内容
domain: 文书/misc
triggers: [把代码或特性写成教程, 编写循序渐进的上手指南, 做新人 onboarding 教学材料, 设计带练习和答案的动手实验, 为博客/课程/工作坊写教学内容, 把复杂概念拆成可学的步骤]
tags: [技术教程, 教学设计, onboarding, 动手实验, 技术写作, 文档工程]
level: 进阶
status: stable
agents: [claude-code, codex, cursor, gemini-cli]
tools: [Read, Glob, Grep, Write]
requires: []
related: [docs-architect, technical-reference-builder, readme-doc-writer]
combines_with: []
license: MIT
source: sickn33/antigravity-awesome-skills
source_license: MIT
---
## 何时使用
当需要把一段代码、一个特性或一个库，转化成**循序渐进、可动手跑通**的学习材料时使用。产物是教学型 Markdown：读者跟着做能从零到「会用」，而不仅是「看懂」。典型场景：
- 把复杂概念拆成可消化的顺序步骤，让初学者不卡壳。
- 为新人 onboarding、博客、课程、工作坊产出教学内容。
- 写「教人」而非「查阅」的文档：每个概念配即时练习与预期输出。
**不该用边界：**
- 任务与教程/教学无关，或属其他领域/工具范畴。
- 需要 API 参考手册（字段级速查）—— 改用 `technical-reference-builder`。
- 需要长篇架构叙事 / 设计决策记录 —— 改用 `docs-architect`。
- 写营销或推广文案。
- 缺必需输入（主题/代码、目标受众、格式、约束、发布渠道）时先停下澄清，不要臆造。
## 步骤
教程开发三步法：
1. **定学习目标**：补全「学完后你将能够 ____」。用 Bloom 动词（build / debug / optimize，不用「understand」），写可衡量的成果，明确前置知识。
2. **拆概念**：把复杂主题切成原子概念，按「简单→复杂、具体→抽象」排序，标出依赖。**铁律：任何概念都不得依赖后文才介绍的知识（No Forward References）。**
3. **设练习**：动手编码练习按脚手架（scaffolding）由易到难，每个练习都要有明确成功判据，并埋入自检 checkpoint。节奏遵循 **I do（示范）→ We do（带做）→ You do（挑战）**。
**渐进章节节奏**（每节固定韵律）：概念引入（配类比）→ 最小可跑示例 → 带预期输出的逐步带做 → 可选变体 → 难度递增的挑战 → Troubleshooting（错误信息 → 修复）。
## 指令
- **Show, Don't Tell**：先给可跑代码，再解释参数。每个概念紧跟一次即时练习。
- **认知负荷管理**：每节新概念 ≤ 3 个；代码示例尽量一屏放下；每 5 行代码配 1–3 句解释；删掉装饰性代码，每行都要「教点东西」。
- **频繁验证**：每隔几步让读者跑一次，并写明「Expected output: …」。
- **解释「为什么」**：不只讲 what/how，用类比连接到熟悉概念（如「中间件像安检口」），关联真实生产场景。
- **变量名有意义**：用 `user_name` 而非 `x`；非显然逻辑加内联注释（不是每行都注）。
- **不跳「显而易见」的步骤**（专家盲区）；所有代码先跑通再放进去，否则标注 `pseudocode`。
- **按受众校准**：初学者 → 更多类比、更小步子、更多练习；进阶 → 假定基础、聚焦模式与最佳实践；高级 → 跳过铺垫、直入边界与优化。
- 练习类型按难度选用：Fill-in-the-Blank（建立信心）/ Debug 挑战（先给错误信息）/ Extension 任务（给需求不给答案）/ From Scratch（给测试用例自检）/ Refactoring（前后对比）。
**输出格式（Markdown，保留源约束）：** 章节清晰编号；代码块带语言标签 + 文件名注释 + 预期输出（`# Output: ...`）；提示/警告用 `> **Tip:**` / `> **Warning:**`；checkpoint 用 `## Checkpoint: 你应该能……`；答案放可折叠块 `Solution
…Solution
[可折叠答案]