scaffold-exercises

scaffold-exercises 技能概览

scaffold-exercises 是一个偏配置与搭建的技能，用来创建符合仓库命名规范和 lint 规则的练习目录。当你需要新增一个章节、创建练习骨架，或在不猜目录结构的前提下统一 problem / solution / explainer 的布局时，它最有用。它真正做的事不只是“建文件夹”，而是“生成一个可用的练习骨架”，让内容、评审以及 pnpm ai-hero-cli internal lint 都能直接接上。

scaffold-exercises 适合做什么

当你已经知道要补充什么学习内容，但需要一个干净的目录骨架来承载它时，就该用 scaffold-exercises。它很适合课程作者、维护者，以及需要在多个章节中反复创建标准化练习结构的 agent。

scaffold-exercises 最能帮上忙的场景

当仓库有严格约定时，这个技能最有价值：例如章节编号、练习编号，以及每个变体文件夹里都必须有 readme.md。如果你的工作流里经常要先搭空壳再补内容，scaffold-exercises 的安装尤其有用，因为它能在写内容之前就减少格式错误。

scaffold-exercises 对你有什么要求

这个技能默认你能提供章节号、练习号、练习名称，以及目标变体类型。即使你的需求描述比较笼统，骨架也仍然可以生成；但如果输入能清楚区分 problem、solution 和 explainer 的用途，结果通常会更好。

如何使用 scaffold-exercises 技能

安装 scaffold-exercises

使用下面的命令安装 scaffold-exercises 技能：

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

这是仓库里实际使用的 scaffold-exercises 安装方式。安装完成后，把它当作一个目录创建工作流来用，而不是普通的写作提示词。

给技能一个结构化的需求说明

最好的 scaffold-exercises 用法，通常从一段简短但明确的计划开始，写清楚目标章节、练习名称，以及希望的变体类型。比如：“创建 exercises/02-generation/02.01-rerank-basics/，包含 explainer/ 和 solution/ 骨架；保持命名为 dash-case；确保每个 readme 都有内容。”这比“搭一个课程骨架”要好得多，因为它明确告诉技能要创建哪些路径、必须有哪些文件。

先读对的文件

先从 SKILL.md 开始，然后查看仓库里关于章节命名、必需子目录和骨架内容的练习约定。如果仓库在其他地方还有相邻说明，也要在生成前先读完。对 scaffold-exercises 来说，关键决策点是目录格式、默认变体，以及到底需不需要代码文件，还是只要一个 readme-only 骨架就够了。

遵循仓库的最小可用模式

一个稳妥的 scaffold-exercises 做法是：先建目录，再添加非空的 readme.md 文件，只有当某个变体确实包含代码时才添加 main.ts。如果只是做骨架，默认用 explainer/ 通常比虚构 problem 文件更干净，因为后者会暗示学生内容尚未完成。标题要和练习名称保持一致，第一版占位内容里也要避免断链。

scaffold-exercises 技能 FAQ

scaffold-exercises 只适用于新练习吗？

不是。scaffold-exercises 技能在你新增章节、或者想统一已有一组练习的结构时同样有帮助。只要在更深层内容写入前，需要先把仓库里的练习结构做成有效状态，它就有用。

我一定要用这个技能，而不是普通提示词吗？

当结构比文案更重要时，用这个技能。普通提示词可以描述想法，但如果输出必须服从命名规则、必需文件夹和适合 lint 的骨架，scaffold-exercises 会更合适。

scaffold-exercises 适合新手吗？

适合，只要你能明确练习名称和目标文件夹。新手最常见的错误，是把变体类型说得不够具体，或者忽略章节/练习的编号规则，结果生成的路径看起来合理，却不符合仓库约定。

什么时候不该用 scaffold-exercises？

如果你只需要课程文案、头脑风暴，或者一个不受目录约束的临时 markdown 草稿，就不要用 scaffold-exercises。它是一个仓库结构技能，不是内容生成捷径。

如何改进 scaffold-exercises 技能

提供更精确的路径和变体意图

最大的质量提升，来自把具体目录和每个子文件夹的职责说清楚。一个有力的请求会明确应该存在什么，例如：“创建 exercises/03-ranking/03.02-bm25-tuning/，包含 problem/、solution/ 和 explainer/ 的 readme；problem/ 文件夹应包含 TODO，solution/ 文件夹应包含参考大纲，explainer/ 应保持概念性。”这样能帮助 scaffold-exercises 技能第一次就搭出正确结构。

注意常见失败模式

最常见的问题包括：编号错误、缺少 readme.md、占位内容为空，以及在只需要骨架的练习里错误地加入代码文件。另一个常见失误，是把章节级命名和练习级命名混在同一路径里。scaffold-exercises 的指南在你把命名规范和内容预期分开处理时，效果最好。

在第一次骨架生成后继续迭代

生成完成后，检查每个文件夹是否都包含必需文件，并确认每个 readme 的措辞是否与实际练习类型一致。如果之后你决定这个练习确实需要代码，再只在会改变学习体验的地方加入 main.ts。对于 scaffold-exercises 来说，最快的改进闭环就是：先搭骨架，再 lint，接着调整命名，最后扩展内容。