scaffold-exercises

演習のひな型作成

リンティングに合格する、セクション、問題、解答、解説を含む演習のディレクトリ構成を作成します。ユーザーが演習のひな型作成、演習のスタブ作成、新しいコースセクションの設定を希望している場合に使用します。

このスキルは mattpocock/skills（MIT）からインポートされており、上流ではモデルによって呼び出されます。

このスキルを使用するタイミング

• セクション、問題、解答、解説を含む、リンティングに合格する演習のディレクトリ構成を作成します。
• ユーザーが演習のひな型作成、演習のスタブ作成、新しいコースセクションの設定を希望している場合に使用します。

手順

演習のひな型作成

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
• 名前はダッシュケース（小文字、ハイフン区切り）にします

演習のバリエーション

各演習には、次のサブフォルダーのうち少なくとも1つが必要です。

• problem/ - TODO がある学生用ワークスペース
• solution/ - 参照実装
• explainer/ - TODO のない概念的な教材

スタブを作成する場合、計画で別途指定がなければ explainer/ をデフォルトにします。

必須ファイル

各サブフォルダー（problem/、solution/、explainer/）には、次の条件を満たす readme.md が必要です。

• 空ではないこと（タイトル1行だけでも、実際の内容が必要です）
• リンク切れがないこと

スタブを作成する場合は、タイトルと説明を含む最小限の readme を作成します。

# Exercise Title

Description here

サブフォルダーにコードがある場合は、main.ts（2行以上）も必要です。ただし、スタブの場合は readme だけの演習で問題ありません。

ワークフロー

1. 計画を解析する - セクション名、演習名、バリエーションの種類を抽出します
2. ディレクトリを作成する - 各パスに対して mkdir -p を実行します
3. スタブ用の readme を作成する - 各バリエーションのフォルダーに readme.md を1つ作成し、タイトルを付けます
4. リンティングを実行する - pnpm ai-hero-cli internal lint で検証します
5. エラーを修正する - リンティングに合格するまで繰り返します

リンティングルールの概要

リンター（pnpm ai-hero-cli internal lint）では、次の項目がチェックされます。

• 各演習にサブフォルダー（problem/、solution/、explainer/）があること
• problem/、explainer/、explainer.1/ のいずれかが存在すること
• メインのサブフォルダーに、空ではない readme.md があること
• .gitkeep ファイルがないこと
• speaker-notes.md ファイルがないこと
• readme にリンク切れがないこと
• readme に pnpm run exercise コマンドがないこと
• readme だけのサブフォルダーを除き、各サブフォルダーに main.ts があること

演習の移動／名前変更

演習の番号を振り直したり、移動したりする場合：

1. ディレクトリ名の変更には mv ではなく git mv を使用します（Git の履歴を保持できます）
2. 順序を維持できるよう、数字のプレフィックスを更新します
3. 移動後にリンティングを再実行します

例：

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