HOWILLMAKEIT Learn by Running Code
把一个待学习的 Python 主题变成一套小而完整的代码课程。学习者先看到可运行结果，再从代码中理解概念；每章只增加一个认知负担。
边界
使用本 Skill：
- 从一个知识主题创建新的教学仓库；
- 把 Python 库、框架、协议或工程概念拆成渐进章节；
- 生成能够独立运行、便于修改和观察的极简代码。
不要使用本 Skill：
- 用户只想理解一个现有仓库：改用项目学习类 Skill；
- 用户要从现有源码提炼讲义、作业和判题：改用课程化或 ProMentor 类 Skill；
- 用户只问一个可以直接回答的概念问题，不需要创建仓库。
按需加载的资源
- 规划大纲前读取 references/curriculum-design.md。
- 创建文件前读取 references/repository-contract.md。
- 生成仓库时复用
assets/中的模板，但要按主题替换占位符，不要原样复制。 - 生成后运行
scripts/validate_learning_repo.py <repo>做确定性检查。
工作流
1. 明确学习任务
先从对话中提取以下信息，已有答案就不要重复询问：
- 主题和明确排除的内容；
- 学习者已有知识；
- 学完后希望能构建、解释或调试什么；
- 是否允许联网、调用付费 API、使用数据库或安装本地服务；
- 目标目录。
只有会改变课程结构的信息缺失时才提问。默认值为：懂基础 Python、不熟悉目标主题、Python 3.12、uv、5～7 章、中文教学说明、英文代码标识符、优先离线免费示例。
2. 用一手资料校准内容
第三方库和快速变化的 API 不能只凭记忆设计课程：
- 查看官方文档、官方仓库、发布说明或当前安装版本；
- 确认推荐 API、最低 Python 版本和安装包名；
- 区分“官方事实”“根据资料做出的课程设计”和“尚未验证的假设”；
- 记录资料链接、核对日期和最终选用版本，供根 README 使用。
不要为了堆砌资料扩大主题。调研的目的只是保证示例不过时、命令能运行。
3. 先提交课程大纲
创建任何仓库文件之前，先在对话中给出：
- 一句话课程目标；
- 学习者画像和完成标准；
- 统一贯穿案例；
- 章节表：序号、章节名、本章唯一新增概念、前置章节、运行后能观察到什么、是否需要网络或凭据；
- 最终项目和明确不包含的内容；
- 计划采用的 Python 与关键依赖版本。
必要时用 Mermaid 表示非线性依赖，不要用字符树。等待用户明确确认这份具体大纲。用户只说“帮我创建一个学习仓库”不等于确认；用户已经提供并明确确认过完整大纲时可以直接进入下一步。
4. 安全地创建仓库
用户确认后再写文件：
- 检查目标路径；目标不存在时创建，目标为空时使用，目标非空时先报告冲突，不覆盖已有文件；
- 按仓库契约创建 uv 项目和连续编号的章节目录；
- 用同一个小型场景贯穿课程，但每章必须能从仓库根目录直接运行，不能依赖先执行上一章产生的状态；
- 代码先展示核心机制，再解释抽象。保留能帮助理解“为什么”的注释，删除逐字复述语法的注释；
- 不在关键路径使用
...、伪代码或未定义占位函数； - 仅把真正跨章稳定的配置和假数据放入
shared/，不要为了追求目录层次拆散小示例； - 需要密钥时只提交
.env.example，示例值必须是假值；在 README 标注网络、费用和数据外发风险。
5. 验证而不是声称
从干净状态验证：
- 运行
uv lock和uv sync； - 运行本 Skill 自带的结构验证脚本；
- 逐章运行所有不需要凭据或外部服务的命令，并核对 README 中的预期现象；
- 对在线章节至少完成 Python 语法、导入和缺少配置时的错误提示检查；
- 不把“读过代码”写成“运行通过”。分别报告已运行、仅静态检查和因何未验证。
遇到失败时先修复最小示例或文档，再交付。不要把失败命令留给学习者自行猜测。
6. 交付学习路线
最终简洁报告：
- 仓库位置；
- 30 秒启动命令；
- 推荐从哪一章开始；
- 实际运行通过的章节；
- 需要用户自行提供凭据或服务的章节；
- 采用的主要资料与版本。
不要一次性把所有章节重新讲一遍，仓库本身就是主要教学产物。
完成标准
只有同时满足以下条件才算完成：
- 用户确认过课程大纲；
- 章节编号连续，每章只承担一个主要新增概念；
- 根 README 中的每条章节运行命令都存在；
uv.lock已生成，离线章节在同一干净环境中实际运行通过；- 外部依赖、费用、凭据和未验证项均已明确说明；
- 没有覆盖用户原有文件，也没有写入真实密钥。