scaffold-exercises

技能简介

scaffold-exercises 是一个用于创建练习目录结构的 Skill，它能自动生成包含章节（Sections）、问题（problem）、解决方案（solution）和讲解（explainer）的练习脚手架，并确保这些结构通过 Lint 校验。当用户需要搭建练习框架、创建练习存根或设置新的课程章节时，使用本技能可避免手动建目录和写基础文件的重复工作。

使用场景

• 根据课程计划批量生成章节和练习目录结构
• 为练习创建 problem/、solution/、explainer/ 等变体子文件夹
• 快速生成带非空 readme.md 的练习存根
• 移动或重命名练习时保持 git 历史，并确保 lint 通过
• 为需要代码的练习创建初始 main.ts 骨架

使用方法

本技能通过 AI CLI 触发，无需单独安装。核心命令如下：

# 在项目根目录运行 Lint 校验
pnpm ai-hero-cli internal lint

基本工作流：

1. 解析计划 — 从用户提供的计划中提取章节名、练习名和变体类型
2. 创建目录 — 使用 mkdir -p 按规范创建目录（例如 exercises/05-memory-skill-building/05.02-short-term-memory/explainer）
3. 创建存根 readme — 在每个变体目录下创建非空的 readme.md，可仅包含标题和描述
4. 运行 Lint — 执行 pnpm ai-hero-cli internal lint 校验结构
5. 修复错误 — 根据 lint 输出迭代直到全部通过

目录命名规范：

• 章节：XX-section-name/（如 01-retrieval-skill-building）
• 练习：XX.YY-exercise-name/（如 01.03-retrieval-with-bm25）
• 名称使用短横线连接的小写字母

移动或重命名练习时，务必使用 git mv 保留 git 历史：

git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings

注意事项

• 每个练习至少需要一个子文件夹（problem/、solution/、explainer/ 任一即可），默认优先创建 explainer/
• readme.md 必须存在且不能为空；若有代码，还需提供超过一行的 main.ts
• Lint 检查会拒绝 .gitkeep、speaker-notes.md、损坏链接以及包含 pnpm run exercise 命令的 readme
• 存根阶段允许只包含 readme，不要求代码文件