AGENT SKILL

scaffold-exercises

创建包含章节、题目、解答与讲解的练习目录结构,且能通过 lint。在用户想搭建练习、创建练习桩,或设置新课程章节时使用。

License 许可
MIT
最近更新
2026-08-19
Stars
★ 0
Forks
0

01 前言 Front Matter

name
scaffold-exercises
description
创建包含章节、题目、解答与讲解的练习目录结构,且能通过 lint。在用户想搭建练习、创建练习桩,或设置新课程章节时使用。

02 资源文件 1

03 SKILL.md 正文

搭建练习

创建能通过 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

如果子文件夹有代码,还需要一个 main.ts(多于 1 行)。但对于桩,仅有 readme 的练习也可以。

工作流

  1. 解析计划 - 提取章节名、练习名和变体类型
  2. 创建目录 - 为每条路径执行 mkdir -p
  3. 创建桩 readme - 每个变体文件夹一个带标题的 readme.md
  4. 运行 lint - 用 pnpm ai-hero-cli internal lint 校验
  5. 修复任何错误 - 迭代直到 lint 通过

Lint 规则摘要

linter(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"

04 同仓库更多 Skills