Back to Details

scaffold-exercises

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scaffold Exercises

生成练习目录结构

Create exercise directory structures that pass linting validation for educational content.
创建可通过代码检查验证的教育内容练习目录结构。

When to use this skill

适用场景

  • Creating course sections and exercises for educational content
  • Scaffolding structured learning materials with problem/solution variants
  • Building content that must pass 
    pnpm ai-hero-cli internal lint
  • 为教育内容创建课程章节与练习
  • 生成包含问题/解答变体的结构化学习资料
  • 构建需要通过
    pnpm ai-hero-cli internal lint
    检查的内容

When not to use this skill

不适用场景

  • General project scaffolding → use 
    file-organization
  • Documentation writing → use 
    technical-writing
  • 通用项目结构搭建 → 请使用
    file-organization
    技能
  • 文档撰写 → 请使用
    technical-writing
    技能

Directory structure

目录结构

exercises/
├── 01-introduction/
│   ├── 01.01-getting-started/
│   │   ├── problem/
│   │   │   ├── readme.md     (required, non-empty, has title)
│   │   │   └── main.ts       (optional, >1 line if present)
│   │   └── solution/
│   │       ├── readme.md
│   │       └── main.ts
│   └── 01.02-basic-concepts/
│       └── explainer/
│           └── readme.md
exercises/
├── 01-introduction/
│   ├── 01.01-getting-started/
│   │   ├── problem/
│   │   │   ├── readme.md     (required, non-empty, has title)
│   │   │   └── main.ts       (optional, >1 line if present)
│   │   └── solution/
│   │       ├── readme.md
│   │       └── main.ts
│   └── 01.02-basic-concepts/
│       └── explainer/
│           └── readme.md

Naming conventions

命名规范

  • Sections: 
    XX-section-name/
    (two-digit number, lowercase, hyphens)
  • Exercises: 
    XX.YY-exercise-name/
    (section.exercise number, lowercase, hyphens)
  • Variants: 
    problem/
    , 
    solution/
    , 
    explainer/
  • 章节：
    XX-section-name/
    （两位数字，小写字母，连字符分隔）
  • 练习：
    XX.YY-exercise-name/
    （章节.练习编号，小写字母，连字符分隔）
  • 子目录变体：
    problem/
    、
    solution/
    、
    explainer/

Required files per variant

各子目录变体的必填文件

Every variant folder needs:
  • readme.md
    — non-empty, must have at least a title (
    # Title
    )
  • main.ts
    — optional, but must be >1 line if present
每个子目录变体需包含：
  • readme.md
    — 非空，至少包含一个标题（
    # 标题
    ）
  • main.ts
    — 可选，但如果存在则内容需超过1行

Workflow

工作流程

1. Parse requirements

1. 解析需求

Identify section names, exercise names, and which variants are needed (problem, solution, explainer, or combinations).
确定章节名称、练习名称，以及所需的子目录变体（problem、solution、explainer或组合）。

2. Create directory hierarchy

2. 创建目录层级

bash
mkdir -p exercises/01-section-name/01.01-exercise-name/problem
mkdir -p exercises/01-section-name/01.01-exercise-name/solution
bash
mkdir -p exercises/01-section-name/01.01-exercise-name/problem
mkdir -p exercises/01-section-name/01.01-exercise-name/solution

3. Add stub readme files

3. 添加占位README文件

bash
undefined
bash
undefined

Minimum valid readme

Minimum valid readme

echo "# Exercise: Getting Started\n\nComplete the task described below." > exercises/01-section-name/01.01-exercise-name/problem/readme.md
undefined
echo "# Exercise: Getting Started\n\nComplete the task described below." > exercises/01-section-name/01.01-exercise-name/problem/readme.md
undefined

4. Validate

4. 验证

bash
pnpm ai-hero-cli internal lint
bash
pnpm ai-hero-cli internal lint

5. Fix iteratively

5. 迭代修复

The linter checks:
  • Exercises have appropriate subfolders
  • Readmes are non-empty with titles
  • No broken links
  • No prohibited files (
    .gitkeep
    , 
    speaker-notes.md
    )
代码检查工具会验证以下内容：
  • 练习包含合适的子目录
  • README文件非空且包含标题
  • 无无效链接
  • 无禁用文件（
    .gitkeep
    、
    speaker-notes.md
    ）

Moving exercises

移动练习

Use 
git mv
(not 
mv
) to rename directories — preserves git history:
bash
git mv exercises/01-old-name exercises/01-new-name
使用
git mv
（而非
mv
）重命名目录 — 可保留Git历史记录：
bash
git mv exercises/01-old-name exercises/01-new-name

Instructions

操作指引

  1. Identify the task trigger and expected output.
  2. Follow the workflow steps in this skill from top to bottom.
  3. Validate outputs before moving to the next step.
  4. Capture blockers and fallback path if any step fails.
  1. 明确任务触发条件与预期输出。
  2. 按本技能中的工作流程步骤依次执行。
  3. 进入下一步前先验证输出结果。
  4. 记录执行过程中的障碍，以及步骤失败时的备选方案。

Examples

示例

  • Example: Apply this skill to a small scope first, then scale to full scope after validation passes.
  • 示例：先在小范围内应用本技能，验证通过后再扩展至完整范围。

Best practices

最佳实践

  • Keep outputs deterministic and auditable.
  • Prefer small reversible changes over broad risky edits.
  • Record assumptions explicitly.
  • 确保输出结果可预测、可追溯。
  • 优先选择小幅度、可回滚的修改，而非大范围高风险的编辑。
  • 明确记录所有假设条件。

References

参考资料

  • Project standards: 
    .agent-skills/skill-standardization/SKILL.md
  • Validator script: 
    .agent-skills/skill-standardization/scripts/validate_skill.sh
  • 项目标准：
    .agent-skills/skill-standardization/SKILL.md
  • 验证脚本：
    .agent-skills/skill-standardization/scripts/validate_skill.sh