scaffold-exercises

scaffold-exercises skill 概览

scaffold-exercises skill 的作用，是帮代理按照严格的训练内容约定创建练习目录结构：包括带编号的章节、带编号的练习、像 problem/、solution/、explainer/ 这样的变体子目录，以及最少但足以通过 lint 类检查的有效文件。如果你在搭课程内容、工作坊练习，或维护结构化学习仓库，它解决的就是这个非常具体的落地问题。

scaffold-exercises 最适合用来做什么

当你已经明确学习计划，只需要把文件系统骨架正确、快速、统一地搭出来时，就适合用 scaffold-exercises。它尤其适合：

• 在 exercises/ 下新建一个课程章节
• 根据课程大纲批量创建多个练习 stub
• 添加 problem、solution 或 explainer 变体，而不用自己猜命名规则
• 避免先搭出有问题的起始目录，后面再因为 repo lint 校验失败返工

谁适合安装 scaffold-exercises

最匹配的用户，是正在维护一个本来就采用练习式教学结构的 repo 的人。scaffold-exercises skill 对维护者、课程作者，以及借助 AI 编辑仓库的人尤其有用——前提是你更需要正确的路径和占位文件，而不是自动生成大段教学文案。

scaffold-exercises 和普通 prompt 的区别

普通 prompt 也能让 AI “建几个练习文件夹”，但 scaffold-exercises 多了一层面向仓库规范的约束力：

• 章节目录使用 XX-section-name
• 练习目录使用 XX.YY-exercise-name
• 名称统一为 dash-case
• 每个练习至少要有一个变体目录
• 每个变体都需要一个非空的 readme.md
• 像 main.ts 这样的代码文件，只有在确实有代码内容时才需要

这意味着路径格式错误更少、空占位文件更少、生成后需要手动清理的地方也更少。

采用 scaffold-exercises 前最该先回答的问题

如果你最大的风险是结构跑偏，而不是内容创意不足，那就该安装 scaffold-exercises。这个 skill 的重点是生成符合约定的脚手架；它本身并不是完整的课程规划器、讲义写作器，也不是代码生成器。

如何使用 scaffold-exercises skill

scaffold-exercises 一般怎么安装

仓库摘录里并没有在 SKILL.md 中提供它自己的专用安装方式，所以具体用法取决于你的 skills runtime。在基于 Skills 的环境中，团队通常会先添加源仓库，再按名称调用 scaffold-exercises skill。如果你的环境支持，常见模式是：

npx skills add mattpocock/skills --skill scaffold-exercises

如果你的代理平台通过别的方式加载 skills，那就把它指向 mattpocock/skills 仓库，并选择 scaffold-exercises。

使用 scaffold-exercises 前先看这个文件

先从这里开始：

• scaffold-exercises/SKILL.md

这个 skill 很简单，也比较自包含。从仓库预览来看，没有额外暴露出 rules/、resources/ 或辅助脚本，所以大部分关键行为都直接写在这个文件里。

scaffold-exercises 需要你提供哪些输入

当你给出的计划包含下面四项时，这个 skill 表现最好：

1. 章节编号和标题
2. 练习编号和标题
3. 每个练习要包含哪些变体
4. 你想要的只是 stub，还是需要真实的 starter code

如果这些信息不全，代理仍然可以搭脚手架，但它会自行补默认值，而这些默认值不一定符合你的预期，尤其是在 explainer/ 和 problem/ 的选择上。

能跑起来的最小 prompt

一个粗糙但可用的 scaffold-exercises usage prompt 可以这样写：

Use scaffold-exercises to create section 03-search-fundamentals under exercises/. Add exercises 03.01-tokenization-basics and 03.02-bm25-ranking. Each should have problem/ and solution/ folders with non-empty readme.md files. Stub only, no code yet.

之所以这样就够用，是因为它已经给出了编号、名称、位置和变体类型。

能明显提升结果质量的更强 prompt

更好的 prompt 会把默认行为说清楚：

Use scaffold-exercises for Skill Scaffolding in this repo. Create exercises/03-search-fundamentals/. Add:

• 03.01-tokenization-basics with explainer/
• 03.02-bm25-ranking with problem/ and solution/
• 03.03-query-expansion with problem/

For each variant, create a non-empty readme.md with the final exercise title and a one-sentence description. Do not add main.ts unless the variant includes code. Keep all names dash-case.

这个写法更好，原因在于：

• 它消除了目录变体上的歧义
• 它避免生成不必要的代码文件
• 它从一开始就锁定了命名规范
• 它明确告诉代理，“non-empty” 在实际执行里该怎么做

计划不完整时，默认行为会是什么

上游 skill 里有一个非常关键的细节：如果你是在做 stub，而计划里没说明变体，默认会用 explainer/。这对概念型练习很方便，但如果你实际需要的是学生动手操作空间，那就会出错。只要你想要 hands-on task，就要明确写出 problem/。

scaffold-exercises 会创建什么

这个 skill 围绕一套可重复的目录模式工作，例如：

• exercises/01-section-name/
• exercises/01-section-name/01.01-exercise-name/problem/readme.md
• exercises/01-section-name/01.01-exercise-name/solution/readme.md

对于 stub 脚手架来说，只有 readme 的目录也是可以接受的。等你后面补上代码时，再添加 main.ts，并且文件内容要不止是一行敷衍占位。

在真实 repo 里使用 scaffold-exercises 的实用工作流

比较稳妥的流程是：

1. 先用自然语言写出课程大纲。
2. 把它整理成带编号的章节名和练习名。
3. 为每个练习指定变体。
4. 让代理运行 scaffold-exercises。
5. 在填内容之前，先检查路径名称。
6. 运行 repo 的 lint 或校验步骤。
7. 之后再补代码和更完整的文档。

这个顺序很重要，因为这个 skill 最擅长的是“先把结构搭对”。

最容易引发返工的命名错误

最常见的错误输入有这些：

• 缺少数字前缀
• 用空格而不是 dash-case
• 把章节编号和练习编号混在一起
• 没说明目录应该是 problem、solution 还是 explainer

如果你的计划只写“Create an exercise on BM25”，那代理仍然需要自己脑补太多内容。可如果你写的是“Create 01.03-retrieval-with-bm25 inside 01-retrieval-skill-building with problem/ and solution/”，结果通常就会可靠得多。

用于 Skill Scaffolding 时，scaffold-exercises 的适配性判断

如果你的瓶颈是 repo 结构和一致性，那 scaffold-exercises for Skill Scaffolding 很合适；但如果你需要自动生成丰富教学设计、评估题目或高质量讲解内容，它就不太匹配。更准确地说，它是一个结构约束器，不是 instructional design 的替代品。

scaffold-exercises skill 常见问题

scaffold-exercises 对新手友好吗

友好，前提是你已经清楚自己想要什么样的练习结构。这个 skill 本身并不复杂：它主要是在强制命名规则、目录布局和最基本的必需文件。真正更难的部分，是你要提前想清楚课程结构和变体选择。

什么情况下不该用 scaffold-exercises

如果符合下面这些情况，就不建议用 scaffold-exercises：

• 你的 repo 并不是按带编号的章节和练习目录组织的
• 你只需要一个 markdown 课程页面，而不是一整棵练习目录树
• 你希望 AI 从零发明整套课程结构
• 你的项目文件约定不是 readme.md 加可选的 main.ts

scaffold-exercises 和手动建文件夹有什么区别

如果只是单个练习，手动搭目录完全没问题。scaffold-exercises usage 的价值，主要体现在你要一次建很多练习、又必须保持一致的时候。它能减少无效命名、空 readme、以及目录约定混乱导致的下游检查失败。

scaffold-exercises 会生成完整的练习内容吗

不会。它的核心价值是脚手架。它可以创建最简 readme 和占位结构，但不应该把它当成完整的课程写作系统。

每次都必须有 problem、solution 和 explainer 吗

不需要。上游规则只要求三者中至少有一个。对于 stub，如果你没特别说明，默认会用 explainer/。变体应该根据练习目标来选，而不是机械地每次都全配。

scaffold-exercises 只能用于一种 repo 布局吗

它是有明确偏好的。这个 skill 默认假设你有一个 exercises/ 层级，以及固定的编号规则。如果你的 repo 就是这个模式，它会很好用；如果不是，你会花不少时间和它的假设对着干。

如何把 scaffold-exercises skill 用得更好

给 scaffold-exercises 编号化计划，而不是主题列表

想让 scaffold-exercises 出结果更准，最快的方法就是别再只给主题，而是直接给出准确目标路径。对比一下：

弱：

• “Add some exercises about retrieval.”

强：

• “Create exercises/01-retrieval-skill-building/01.01-keyword-search, 01.02-bm25, and 01.03-hybrid-search.”

第二种写法几乎不给代理留下把目录名写错的空间。

明确变体意图，不要把决定权交给默认值

如果你不写变体类型，这个 skill 可能会在 stub 场景里默认选 explainer/。这样做效率是高，但未必符合你的教学设计。最好直接说明：

• 学生任务用 problem/
• 参考答案用 solution/
• 纯概念材料用 explainer/

只补上这一点，脚手架质量通常就会明显提升。

要求最简但有效的 readme

一个常见失败模式是：文件虽然建出来了，但只是在技术上“存在”，实际一点也不好用。你应该明确要求代理在每个 readme.md 里都写上标题和一句描述。这样既能保证文件非空，也能让后续正式编写更顺手。

避免生成没必要的代码文件

另一个常见问题，是到处都生成 main.ts。但上游 skill 并不要求 readme-only stub 必须带这个文件。如果你想要更轻量的脚手架，就明确写上：“readme-only unless code is explicitly needed.” 这样第一版结构会干净很多。

批量生成前，先验证命名

如果一次要生成很多练习，先让代理列出准备创建的路径，等你确认后再真正创建。这样能在你还没开始大规模生成前，就发现编号冲突和不顺手的 slug，避免后面一口气重命名几十个目录。

第一轮 scaffold-exercises 之后要再迭代一轮

第一次运行后，可以重点检查这些方面来继续优化结果：

• 编号是否连续
• 变体是否完整
• readme 是否真的有用
• 每个练习是否确实属于当前章节

然后再让代理跑第二轮，但只处理修正项。把生成和审查拆开之后，scaffold-exercises guide 的最终质量通常会明显提升。

哪些地方 scaffold-exercises 仍然需要人工判断

scaffold-exercises skill 没法替你判断最合适的教学顺序、练习难度，也无法决定课程覆盖面是否合理。最佳用法是：用它自动化结构搭建，把课程逻辑和教学判断保留给人工审核。