mcpField
S
scaffold-exercises

scaffold-exercises

github.com/akillness开发52240 次安装今天更新
代码仓库

关于 scaffold-exercises

scaffold-exercises 是一项 Agent 技能，用于创建带编号的练习目录，并添加问题、解答或讲解材料。它引导课程作者创建 readme 和可选代码框架，再运行项目检查器验证目录结构。

主要功能

  1. 01创建带编号的章节和练习
  2. 02添加问题、解答或讲解目录
  3. 03生成 readme 框架
  4. 04运行项目检查器验证结构
  5. 05用 `git mv` 重命名目录

适用场景

  1. 01建立新的课程章节
  2. 02根据计划创建练习框架
  3. 03调整练习编号或移动目录

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/akillness/jeo-skills --skill scaffold-exercises

安装后在 Claude Code 中输入/scaffold-exercises确认已加载。

详细介绍

搭建练习框架

创建包含章节、题目、解答和讲解的练习目录结构，并确保通过 lint 检查。当用户想要搭建练习框架、创建练习存根或设置新的课程章节时使用。

此技能源自 mattpocock/skills（MIT），并由上游的模型调用。

何时使用此技能

  • 创建包含章节、题目、解答和讲解的练习目录结构，并确保通过 lint 检查。
  • 当用户想要搭建练习框架、创建练习存根或设置新的课程章节时使用。

说明

搭建练习框架

创建能通过 pnpm ai-hero-cli internal lint 检查的练习目录结构，然后使用 git commit 提交。

目录命名
  • 章节：在 exercises/ 中使用 XX-section-name/（例如，01-retrieval-skill-building）
  • 练习：在章节目录中使用 XX.YY-exercise-name/（例如，01.03-retrieval-with-bm25）
  • 章节编号 = XX，练习编号 = XX.YY
  • 名称使用短横线分隔的小写格式（dash-case）
练习变体

每个练习至少需要以下子目录之一：

  • problem/ - 学生工作区，包含 TODO
  • solution/ - 参考实现
  • explainer/ - 概念性材料，不含 TODO

创建存根时，除非计划另有规定，否则默认使用 explainer/。

必需文件

每个子目录（problem/、solution/、explainer/）都需要一个 readme.md，且必须满足以下要求：

  • 非空（必须包含实际内容，即使只有一行标题也可以）
  • 不含失效链接

创建存根时，请创建包含标题和描述的最简 readme：

# Exercise Title

Description here

如果子目录中包含代码，还需要一个超过 1 行的 main.ts。不过，对于存根练习，只包含 readme 也可以。

工作流
  1. 解析计划 - 提取章节名称、练习名称和变体类型
  2. 创建目录 - 为每个路径执行 mkdir -p
  3. 创建 readme 存根 - 为每个变体目录创建一个 readme.md，并添加标题
  4. 运行 lint - 执行 pnpm ai-hero-cli internal lint 进行验证
  5. 修复错误 - 反复处理，直到 lint 通过
Lint 规则摘要

Lint 工具（pnpm ai-hero-cli internal lint）会检查：

  • 每个练习都包含子目录（problem/、solution/、explainer/）
  • 至少存在 problem/、explainer/ 或 explainer.1/ 之一
  • 主要子目录中存在非空的 readme.md
  • 不存在 .gitkeep 文件
  • 不存在 speaker-notes.md 文件
  • readme 中没有失效链接
  • readme 中没有 pnpm run exercise 命令
  • 每个子目录都需要 main.ts，除非其中只有 readme
移动或重命名练习

对练习重新编号或移动时：

  1. 使用 git mv（而非 mv）重命名目录，以保留 Git 历史记录
  2. 更新数字前缀以维持顺序
  3. 移动后重新运行 lint

示例：

git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
示例：根据计划创建存根

假设计划如下：

Section 05: Memory Skill Building
- 05.01 Introduction to Memory
- 05.02 Short-term Memory (explainer + problem + solution)
- 05.03 Long-term Memory

创建：

mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer

然后创建 readme 存根：

exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"

示例

  • 先将此技能应用于一个较小的范围，确认输出符合上述结构，再扩展到完整任务。
  • 如果某个步骤需要从代码库或环境中获取信息，请自行查找，而不是询问用户。

最佳实践

  • 保持上游流程不变；如有偏离，明确记录，而不是默默自行变通。
  • 在此技能标记为由用户决定的每个决策点，都应停下来交还控制权给用户。
  • 优先进行小幅、可逆的更改，并明确说明假设，不要将其隐去。

参考资料

  • 上游技能：mattpocock/skills skills/misc/scaffold-exercises/SKILL.md（提交 3cca18b，MIT）
  • 项目规范：.agent-skills/skill-standardization/SKILL.md
  • 验证脚本：.agent-skills/skill-standardization/scripts/validate_skill.sh

评论

支持 Markdown