---
name: learn-by-running-code
description: 将一个 Python 学习主题设计成按 01_、02_ 编号的渐进式可运行代码仓库；每章先讲清最小必要知识，再通过 worked example 映射到代码，并用运行、修改、检索和自我解释完成学习。用户只要提到“做一个学习仓库”“按章节用代码学”“边运行边学”“把某个 Python 主题拆成可运行示例”或希望用项目化方式系统学习 Python 库、框架、协议和工程概念，就应使用本 Skill。它负责从主题调研、课程大纲确认到 uv 仓库生成、AGENTS.md 导师指南与逐章验证；不用于单纯讲解已有仓库或把现有项目改造成作业课程。
---

# Learn by Running Code

把一个待学习的 Python 主题变成一套小而完整的代码课程。每章先讲清一个最小知识块，再把知识映射到可运行代码，并通过修改与解释完成实践；每章只增加一个认知负担。

## 边界

使用本 Skill：

- 从一个知识主题创建新的教学仓库；
- 把 Python 库、框架、协议或工程概念拆成渐进章节；
- 生成能够独立运行、便于修改和观察的极简代码。

不要使用本 Skill：

- 用户只想理解一个现有仓库：改用项目学习类 Skill；
- 用户要从现有源码提炼讲义、作业和判题：改用课程化或 ProMentor 类 Skill；
- 用户只问一个可以直接回答的概念问题，不需要创建仓库。

## 按需加载的资源

- 规划大纲前读取 [references/curriculum-design.md](references/curriculum-design.md)。
- 设计 agent 的逐章教学节奏前读取 [references/teaching-method.md](references/teaching-method.md)。
- 创建文件前读取 [references/repository-contract.md](references/repository-contract.md)。
- 生成仓库时复用 `assets/` 中的模板，但要按主题替换占位符，不要原样复制；`AGENTS.template.md` 必须据课程实情填充为根目录 `AGENTS.md`。
- 生成后运行 `scripts/validate_learning_repo.py <repo>` 做确定性检查。

## 工作流

### 1. 明确学习任务

先从对话中提取以下信息，已有答案就不要重复询问：

- 主题和明确排除的内容；
- 学习者已有知识；
- 学完后希望能构建、解释或调试什么；
- 是否允许联网、调用付费 API、使用数据库或安装本地服务；
- 目标目录。

只有会改变课程结构的信息缺失时才提问。默认值为：懂基础 Python、不熟悉目标主题、Python 3.12、uv、5～7 章、中文教学说明、英文代码标识符、优先离线免费示例。

### 2. 用一手资料校准内容

第三方库和快速变化的 API 不能只凭记忆设计课程：

1. 查看官方文档、官方仓库、发布说明或当前安装版本；
2. 确认推荐 API、最低 Python 版本和安装包名；
3. 区分“官方事实”“根据资料做出的课程设计”和“尚未验证的假设”；
4. 记录资料链接、核对日期和最终选用版本，供根 README 使用。

不要为了堆砌资料扩大主题。调研的目的只是保证示例不过时、命令能运行。

### 3. 先提交课程大纲

创建任何仓库文件之前，先在对话中给出：

- 一句话课程目标；
- 学习者画像和完成标准；
- 统一贯穿案例；
- 章节表：序号、章节名、本章唯一新增概念、开始实践前必须讲清的最小知识块、前置章节、运行后能观察到什么、是否需要网络或凭据；
- 最终项目和明确不包含的内容；
- 计划采用的 Python 与关键依赖版本。

必要时用 Mermaid 表示非线性依赖，不要用字符树。等待用户明确确认这份具体大纲。用户只说“帮我创建一个学习仓库”不等于确认；用户已经提供并明确确认过完整大纲时可以直接进入下一步。

### 4. 安全地创建仓库

用户确认后再写文件：

1. 检查目标路径；目标不存在时创建，目标为空时使用，目标非空时先报告冲突，不覆盖已有文件；
2. 按仓库契约创建 uv 项目和连续编号的章节目录；
3. 用同一个小型场景贯穿课程，但每章必须能从仓库根目录直接运行，不能依赖先执行上一章产生的状态；
4. 先用“解决什么问题 → 输入 → 处理 → 输出 → 边界”讲清本章最小知识块，再用 worked example 把知识映射到关键代码；随后让学习者预测、运行和修改。代码用于验证知识，不替代知识讲解；保留能解释“为什么”的注释，删除逐字复述语法的注释；
5. 不在关键路径使用 `...`、伪代码或未定义占位函数；
6. 仅把真正跨章稳定的配置和假数据放入 `shared/`，不要为了追求目录层次拆散小示例；
7. 需要密钥时只提交 `.env.example`，示例值必须是假值；在 README 标注网络、费用和数据外发风险；
8. 生成根目录 `AGENTS.md` 教学指令文件（内容契约见 repository-contract.md）：课程的最终消费者通常是给学习者当导师的 agent，该文件必须让任何进入仓库的 LLM 获得导师角色、逐章教学卡、教学节奏与环境边界。

### 5. 验证而不是声称

从干净状态验证：

1. 运行 `uv lock` 和 `uv sync`；
2. 运行本 Skill 自带的结构验证脚本；
3. 逐章运行所有不需要凭据或外部服务的命令，并核对 README 中的预期现象；
4. 对在线章节至少完成 Python 语法、导入和缺少配置时的错误提示检查；
5. 不把“读过代码”写成“运行通过”。分别报告已运行、仅静态检查和因何未验证。

遇到失败时先修复最小示例或文档，再交付。不要把失败命令留给学习者自行猜测。

### 6. 交付学习路线

最终简洁报告：

- 仓库位置；
- 30 秒启动命令；
- 推荐从哪一章开始；
- 实际运行通过的章节；
- 需要用户自行提供凭据或服务的章节；
- 采用的主要资料与版本；
- 提示用户：让支持 `AGENTS.md` 的 agent 进入仓库并说“教我这个课程”即可开课。

不要一次性把所有章节重新讲一遍，仓库本身就是主要教学产物。

## 完成标准

只有同时满足以下条件才算完成：

- 用户确认过课程大纲；
- 章节编号连续，每章只承担一个主要新增概念；
- 根 README 中的每条章节运行命令都存在；
- `uv.lock` 已生成，离线章节在同一干净环境中实际运行通过；
- 根目录存在 `AGENTS.md`，逐章教学卡覆盖全部章节且与 README、实际验证结果一致；
- 外部依赖、费用、凭据和未验证项均已明确说明；
- 没有覆盖用户原有文件，也没有写入真实密钥。