| name | lesson-smith-upskill-forge |
| description | 为当前这个 upskill 教学仓库锻造出 "学这门课" 的工具链. 扫一遍 examples 渐进序列, 向创作者问清学习素材与考法, 写出 docs/upskill/ 下的 3 份文档 (learn, runbook, quiz), 并落下 upskill-learn 与 upskill-quiz 两个子 skill. 接手或刷新一个 upskill repo 的学习工具时用. 关键词, forge upskill, 生成 upskill 学习 skill, 刷新 upskill 文档. |
lesson-smith-upskill-forge
你是 upskill 学习工具链的锻造者. 对着当前这个 upskill 教学仓库跑一次, 产出两样东西:
docs/upskill/ 下 3 份文档 (学习索引 + 跑起来 + quiz 薄壳)..claude/skills/ 下 2 个子 skill (upskill-learn, upskill-quiz).
产出后, 创作者与任何学员都能用 /upskill-learn 带着学, /upskill-quiz 自测.
第 0 步: 先加载 lesson-smith skill (不可跳过)
所有规范都住在 lesson-smith skill 里, 本 skill 只是薄包装, 自己不复制规范. 这是所有 lesson-smith-* skill 的通例: 默认先加载 lesson-smith, 再附带自己这一层的东西. 开工前先加载 lesson-smith skill, 之后从它的 ref/ 按需读规范.
必读规范 (都在 lesson-smith skill 的 ref/ 下)
按用途从 lesson-smith skill 读这些文件, 不要一次全读:
ref/upskill/upskill-repo-layout.md — upskill 的目录结构特化, 先读它对齐整体布局.ref/upskill/docs-upskill-learn-spec.md — 写 01-upskill-learn.md 的规范.ref/upskill/docs-upskill-runbook-spec.md — 写 02-upskill-runbook.md 的规范.ref/upskill/docs-upskill-quiz-spec.md — 写 03-upskill-quiz.md 的规范.ref/upskill/examples-quiz-readme-spec.md — 题库真身 (quiz mini task 的 README) 的格式, 用来定位它并写好 03 的指针.ref/upskill/upskill-learn.SKILL.md, ref/upskill/upskill-quiz.SKILL.md — 两个子 skill 的近乎静态模板, 直接拷.ref/agent-skill-interaction-pattern.md — 通用交互模式 (英文权威版), 生成子 skill 时拷一份进各自的 ref/ 下.
参数
把 $ARGUMENTS 解析成 <mode> < 自由说明...>. 第一个 token 若是下列 mode 就用它, 否则整段当自由说明, mode 默认 init.
- (空) 或
init: 全量生成. 若 docs/upskill/ 已有目标文件, 停下让用户改用 refresh.
refresh: 覆盖式重跑 (先跟用户确认).learn | runbook | quiz: 只重生成那一份 doc (以及对应的 skill).
自由说明是创作者对本次生成的额外指示 (例如 "学习素材以 src/ 下的代码为主", "quiz 偏重 concurrency"). 有的话在 Phase 3 一并采纳.
工作流
Phase 1 — Preflight (不可跳过)
- 确认是 upskill repo: 读根目录
lm.json, type 必须是 upskill; examples/ 必须存在. 不满足就停下问用户.
- 定课程名 (从
README-ORIGINAL.md 或根 README.md).
- 列出
docs/upskill/ 现有内容. init 模式下若目标文件已存在, 停下让用户确认改用 refresh.
Phase 2 — 扫 examples (轻量, 不派 Explore subagent)
upskill 的内容是创作者手写的 mini task, 不用像扫陌生代码那样重. 直接:
- 读
examples/README 与各 examples/NN-title/README 顶部的 description (或 docs/tasks/SYLLABUS), 拼出引导路径 (即 learn 文档的 #2).
- 按
examples-quiz-readme-spec.md 的特征 (H1 下有固定句, 每题一个 H2, 四段结构) 定位那个 quiz 环节 mini task (通常在倒数第 2 到第 3).
- 顺带记下 examples 之外看起来是学习素材的东西 (根目录代码, 其它文档,
mise.toml), 作为 #1 学习素材 的候选.
读 examples 时只读英文版 (无后缀的 .md), 跳过本地化变体 examples/*-<lang>.md 与 examples/*/*-<lang>.md (例如 -cn.md): 它们内容和英文版一致, 两份都读是浪费 token; 反正产出都是英文文件, 索引的也是英文文件. 但 examples 之外的脚本, 数据, 配置等要照常通读, 不受此限.
Phase 3 — 问创作者 (交互 gate, 机器猜不出的部分)
把下面三样问清, 回显确认后再动笔:
- 学习素材 (#1): 把 Phase 2 找到的候选列出来, 请创作者确认或增删, 并说清是情况 A (教程本身就是要学的东西) 还是情况 B (真东西在 examples 之外).
- runbook 隐性步骤: 开始前的一次性 setup, 以及推进中导师默认懂, 学生却不懂的操作 (cd, 环境变量, 注册账号, 浏览器里 setup 等).
- quiz 考法自定义:
03-upskill-quiz.md 里对 upskill-quiz 行为的特殊要求 (没有就按默认).
自由说明里已经给到的直接采纳, 只补没给的.
Phase 4 — 写 3 份 doc
按各自规范写到 docs/upskill/:
01-upskill-learn.md (依 docs-upskill-learn-spec): #1 学习素材 + #2 引导路径.02-upskill-runbook.md (依 docs-upskill-runbook-spec): 一次性 setup + 推进中操作, 把隐性步骤显式化.03-upskill-quiz.md (依 docs-upskill-quiz-spec): 指向 Phase 2 定位到的题库真身, 加上考法自定义.
溯源一律用 markdown 链接加 header 或关键字, 不用 line no. 先写 cn, 定稿后按创作铁律 translate-to-en. 猜不准的地方显式标注请创作者确认, 不许凭空编.
Phase 5 — 落 2 个子 skill
把两个模板拷成真正的 skill, 并让它们自包含 (学生 repo 里没有 lesson-smith, 每个 skill 必须自带交互模式):
ref/upskill/upskill-learn.SKILL.md → .claude/skills/upskill-learn/SKILL.mdref/upskill/upskill-quiz.SKILL.md → .claude/skills/upskill-quiz/SKILL.mdref/agent-skill-interaction-pattern.md (英文权威版) → 各拷一份到 .claude/skills/upskill-learn/ref/agent-skill-interaction-pattern.md 和 .claude/skills/upskill-quiz/ref/agent-skill-interaction-pattern.md.
模板近乎全静态, 落地时只需核对: 每个 SKILL.md 都固定加载它自己 ref/ 下那份交互模式 (路径已写死在模板里), 且对 docs/upskill/ 的引用路径正确.
Phase 6 — Verify 与汇报
- 列出创建或更新的文件 (3 份 doc + 2 份 SKILL.md).
- sanity check: 每个 SKILL.md 都引到
docs/upskill/ 下的文件; 每个生成的 skill 的 ref/ 下都有 agent-skill-interaction-pattern.md, 且 SKILL.md 固定加载了它; 3 份 doc 都非空.
- 跑
lesson-smith lint 看仓库结构是否仍合规.
- 告诉用户: 用
/upskill-learn 开始学, /upskill-quiz 自测; docs/upskill/ 里哪里不对直接改, 或 refresh <name> 重生成一份.
约束
- 只写
docs/upskill/ 与 .claude/skills/upskill-{learn,quiz}/; 不碰源码, 不动 examples 内容.
- 题目本身不在这里出: 题库真身由创作者在 quiz mini task 里手写 (可另有 skill 辅助), forge 只负责定位它并写好
03 的指针.
- 遵循 lesson-smith 的创作铁律与 markdown-style, chinese-english-punctuation 两个 Agent Skill.
