# Tutorial Authoring

> 为本仓库新建、重写、扩充或审校 Rmd/Qmd 教程，并完成证据核验、教学结构、可运行代码、真实图件、导航与定向渲染。适用于 `doc/` 下统计方法、R 包、可视化、实用操作、机器学习和专题文章；与对应 `section-*` skill 配合使用。不用于只改网站前端或只回答一个简短知识问题。

- Skill: `kangwang42/tutorial-authoring` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add kangwang42/tutorial-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kangwang42/tutorial-authoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kangwang42 (https://skillmd.com/u/kangwang42)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kangwang42/tutorial-authoring

---


# 项目教程创作与重写

以“读者能理解、代码能复现、论断能核验、页面能正常打开”为完成标准。篇幅、代码比例和图片数量由教学目标决定，不使用固定行数、70/30 比例或“每篇至少一张示意图”代替质量判断。

## 开工

1. 读取仓库 `CLAUDE.md`、目标文章、同栏目相邻文章和对应 `section-*` skill。
2. 完整读取 [quality-standard.md](references/quality-standard.md) 与 [comparison-and-visuals.md](references/comparison-and-visuals.md)。根据文章类型再读取 [article-archetypes.md](references/article-archetypes.md)。
3. 新建文章前检查编号、文件名、主题重复和 `_quarto.yml` 位置；重写时保留稳定 URL，除非用户明确要求改名。
4. 把用户给出的文章、帖子或宣传文案视为线索，不视为事实单源。版本、函数、统计方法和当前功能必须回到官方文档、论文或实际环境核验。

## 写作合同

在编辑前锁定：目标读者、读完能完成的任务、必要前置知识、核心概念、最易误解之处、代码环境、需要的图件和验收页面。按 `comparison-and-visuals.md` 判断是否存在会妨碍当前任务的相邻方法或工具；只有确有混淆风险时才建立 2–4 个候选的辨析清单。若选错方法会使后续代码或解释跑偏，在正文前段先完成定位，再进入公式、参数或核心函数。缺少会改变方法、终点或工具选择的信息时先问；其余使用保守假设继续。

文章围绕学习问题组织，不机械套统一目录。完整教程通常应让读者依次知道：为什么需要、适用与不适用、关键原理、最小可运行例子、真实工作流、如何诊断、怎样解释、常见错误和进一步学习。

## 证据与代码

- 统计与流行病学方法先遵循 `biostat-principles`；需要方法、报告规范或最新功能时使用 `evidence-research`。
- R 包教程核对官方仓库或 CRAN/Bioconductor 元数据、当前版本、函数签名、返回对象和许可证。不要复述宣传数字而不核验。
- 所有声称可运行的代码必须实跑。模拟数据应具有与教程问题一致的生成机制，不能把暴露、事件或删失独立拼接后解释为方法效果。
- 示例输出只用于教学，不写成研究发现。随机过程设置种子，但不要求全站固定同一个种子。
- 外部依赖缺失时按项目规则处理；不得在教程构建中静默安装系统依赖，也不得为通过渲染换用不同方法。

## 图件

先按 `comparison-and-visuals.md` 判断应使用段落、表格、流程图、概念图、统计图还是真实截图，再为每个候选图位写一句“删除这张图会失去什么理解”。没有独立贡献就不生成；表格和图不能逐字重复。

- 统计关系、模型诊断和模拟结果：用真实代码输出，遵循 `publication-figures`。
- 软件界面、终端、Typst/PDF 页面和文档结果：运行或渲染真实产物后截图。
- 流程、机制和概念框架：遵循 `research-visuals`；不要把手写 SVG 当作默认捷径。
- 每张图提供准确替代文本，正文解释读图重点和方法边界。封面与文内图都不是强制数量指标。

## 验证

1. 运行 `python .claude/skills/tutorial-authoring/scripts/audit_tutorial.py <文章...>`。
2. 抽取并实跑所有可执行代码；检查完整输出中的 `error|warning|traceback|failed|nan`，逐项修复或解释。
3. 对 Typst、命令行或包接口运行实际示例；不把语法看起来合理当作验证。
4. 只渲染目标文章、受影响 section 和 `index.qmd`，禁止以教程修改为由全站渲染。
5. 更新 `_quarto.yml` 后运行 `doc/generate_sections.R`，不要手工维护生成的 section 内容。
6. 检查易混淆项是否在首次使用前得到定位，并检查桌面与移动端可读性：标题层级、表格宽度、代码换行、图中文字、替代文本和链接。
7. 用 `academic-humanizer` 终审正文，删除宣传腔、助手口吻、空泛总结和超出证据的断言。

## 完成条件

目标文章可渲染；示例代码和真实截图可复现；图件有信息贡献；版本、函数和引文有源；导航与 section 已同步；没有新增未解释 warning；只提交本任务文件且保留用户既有改动。