scaffold-exercises

scaffold-exercises スキルの概要

scaffold-exercises は、厳格なトレーニング教材の規約に沿った演習用フォルダ構成を、エージェントが正しく作れるようにするスキルです。具体的には、番号付きセクション、番号付き演習、problem/・solution/・explainer/ のようなバリアント用サブフォルダ、さらに lint 系のチェックを通せる最低限の有効ファイルまでを含めて整えます。コース教材、ワークショップ演習、構造化された学習用リポジトリを作るなら、scaffold-exercises が解決するのはまさにこの実務です。

scaffold-exercises が最も向いている用途

scaffold-exercises を使うべきなのは、学習計画そのものはすでに決まっていて、あとはファイルシステム上の土台を正確・高速・一貫して作りたいときです。特に向いているのは次のようなケースです。

• exercises/ 配下に新しいコースセクションを追加する
• カリキュラムのアウトラインから複数の演習スタブをまとめて作る
• problem、solution、explainer の各バリアントを命名規則に迷わず追加する
• 後で repo の lint に落ちるような壊れたスターター構成を避ける

scaffold-exercises を導入すべき人

最も相性がいいのは、すでに演習ベースの教材構造を持つ repo で作業している人です。scaffold-exercises skill は、文章生成よりも正しいパスやプレースホルダーファイルを重視したいメンテナー、カリキュラム作成者、AI 支援の repo 編集者にとくに有用です。

汎用プロンプトと違う、scaffold-exercises の強み

通常のプロンプトでも AI に「演習用フォルダを作って」と頼むことはできますが、scaffold-exercises には repo 固有の規律があります。

• セクションフォルダは XX-section-name 形式
• 演習フォルダは XX.YY-exercise-name 形式
• 名前は dash-case
• 各演習には最低 1 つのバリアントフォルダが必要
• 各バリアントには空でない readme.md が必要
• main.ts のようなコードファイルは、実際にコードがある場合だけ必要

この前提があるので、不正なパス、空のプレースホルダー、生成後の後始末がかなり減ります。

最初に判断すべき導入ポイント

最大のリスクがコンテンツの独自性不足ではなく、構造のブレにあるなら scaffold-exercises を導入する価値があります。このスキルは、規約に沿った scaffolding に特化しています。単体でカリキュラム設計、レッスン執筆、コード生成まで担うものではありません。

scaffold-exercises スキルの使い方

scaffold-exercises の導入方法として一般的な流れ

リポジトリの抜粋を見る限り、SKILL.md 内に専用のインストーラーは公開されていません。そのため、使い方はあなたの skills runtime に依存します。Skills ベースの環境では、ソース repo を追加してから scaffold-exercises をスキル名で呼び出す構成が一般的です。環境が対応していれば、よくあるパターンは次のとおりです。

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

別の方法でスキルを読み込むエージェント基盤を使っている場合は、mattpocock/skills リポジトリを指定し、その中から scaffold-exercises を選んでください。

scaffold-exercises を使う前にまず読むべきファイル

最初に確認すべきなのは次です。

• scaffold-exercises/SKILL.md

このスキルはシンプルで自己完結しています。repo プレビュー上では rules/、resources/、補助スクリプトのような追加要素は見えていないため、実用上の挙動の大半はこの 1 ファイルに直接書かれていると考えてよいです。

scaffold-exercises に渡すべき入力情報

このスキルは、次の 4 点を含むプランを渡したときに最も安定して動きます。

1. セクション番号とタイトル
2. 演習番号とタイトル
3. 各演習に含めるバリアント
4. スタブだけ欲しいのか、実際のスターターコードも必要なのか

これらがなくてもエージェントは scaffold 自体はできますが、望まないデフォルトが入りやすくなります。とくに explainer/ と problem/ の扱いは曖昧なままだとズレやすいです。

最低限機能するプロンプト

大まかでも実用になる scaffold-exercises usage のプロンプト例は次のような形です。

Use scaffold-exercises to create section 03-search-fundamentals under exercises/. Add exercises 03.01-tokenization-basics and 03.02-bm25-ranking. Each should have problem/ and solution/ folders with non-empty readme.md files. Stub only, no code yet.

これで十分機能するのは、番号、名前、配置場所、バリアント種別が揃っているからです。

出力品質を上げる、より強いプロンプト

より良いプロンプトでは、デフォルト任せにせず条件を明示します。

Use scaffold-exercises for Skill Scaffolding in this repo. Create exercises/03-search-fundamentals/. Add:

• 03.01-tokenization-basics with explainer/
• 03.02-bm25-ranking with problem/ and solution/
• 03.03-query-expansion with problem/

For each variant, create a non-empty readme.md with the final exercise title and a one-sentence description. Do not add main.ts unless the variant includes code. Keep all names dash-case.

この形が優れている理由は次のとおりです。

• フォルダバリアントの曖昧さをなくせる
• 不要なコードファイルの生成を防げる
• 命名規則を最初から守らせやすい
• 「空でない」の具体的な中身をエージェントに伝えられる

プランが不完全なときの scaffold-exercises のデフォルト挙動

上流のスキルでとくに重要なのは、スタブ作成時に、指定がなければ explainer/ がデフォルトになる点です。概念説明だけの演習には便利ですが、学習者向けの作業用ワークスペースが必要な場合には不適切になりえます。手を動かす課題を作りたいなら、problem/ を明示してください。

scaffold-exercises が実際に作るもの

このスキルは、次のような繰り返し可能なディレクトリパターンを前提にしています。

• exercises/01-section-name/
• exercises/01-section-name/01.01-exercise-name/problem/readme.md
• exercises/01-section-name/01.01-exercise-name/solution/readme.md

スタブ用の scaffold では、readme.md だけのフォルダでも問題ありません。後からコードを入れる場合は、その時点で main.ts を追加し、1 行だけの形だけのプレースホルダーではなく、実体のある内容を入れるべきです。

実際の repo で scaffold-exercises を使う実務フロー

実運用では、次の流れがうまく機能します。

1. まずカリキュラムのアウトラインを平文でまとめる
2. それを番号付きのセクション名・演習名に落とし込む
3. 各演習のバリアントを指定する
4. エージェントに scaffold-exercises を実行させる
5. コンテンツを入れる前にパス名を確認する
6. repo の lint または検証ステップを回す
7. その後でコードや詳細ドキュメントを埋める

この順番が重要なのは、scaffold-exercises が最も得意なのはまず構造を整えることだからです。

手戻りを増やしやすい命名ミス

よくある入力ミスは次のとおりです。

• 数字プレフィックスがない
• dash-case ではなくスペースを使っている
• セクション番号と演習番号を取り違えている
• problem、solution、explainer のどれを作るかを書いていない

たとえば、プランが「BM25 についての演習を作って」だけだと、エージェントは多くを推測しなければなりません。一方で「01-retrieval-skill-building の中に 01.03-retrieval-with-bm25 を作り、problem/ と solution/ を入れて」と書けば、結果はかなり安定します。

Skill Scaffolding 向け scaffold-exercises の適性

scaffold-exercises for Skill Scaffolding は、repo の形と一貫性がボトルネックになっているなら非常に相性が良いです。逆に、豊かな教育設計、評価問題、自動生成された洗練された解説まで求める用途には向きません。これは教材設計そのものの代替ではなく、構造を強制するツールとして使うのが適切です。

scaffold-exercises スキル FAQ

scaffold-exercises は初心者にも使いやすいか

はい。ただし、作りたい演習構造が自分の中で分かっていることが前提です。スキル自体はシンプルで、主に命名、フォルダ構成、最低限必要なファイルを強制するものです。難しいのは、事前にカリキュラムやバリアントの選び方を決めておく部分です。

scaffold-exercises を使わないほうがよい場面

次のような場合は scaffold-exercises は見送ったほうがよいです。

• repo が番号付きセクション・番号付き演習フォルダを採用していない
• 必要なのが演習ツリーではなく単一の markdown レッスンだけ
• コース全体の構成を AI にゼロから考えさせたい
• プロジェクトが readme.md と任意の main.ts とは別のファイル契約で動いている

手作業でフォルダを作るのと scaffold-exercises は何が違うか

演習が 1 つだけなら手作業でも問題ありません。scaffold-exercises usage の価値が出るのは、複数演習をまとめて作り、一貫性が必要になる場面です。無効な名前、空の readme、フォルダ規約の混在によって後段のチェックが壊れるリスクを減らせます。

scaffold-exercises は演習の中身まで全部生成するか

いいえ。中核となる価値は scaffolding です。最低限の readme やプレースホルダー構造は作れますが、完全な教材執筆システムとして考えるべきではありません。

毎回 problem、solution、explainer のすべてが必要か

いいえ。上流ルールで必須なのは、そのうち最低 1 つです。スタブ作成では、何も指定しなければ explainer/ がデフォルトです。慣習で全部付けるのではなく、その演習の目的に合わせてバリアントを選ぶべきです。

scaffold-exercises は 1 つの repo 構成に固定されているか

かなり前提が強いスキルです。exercises/ の階層と特定の番号付け規約を前提にしています。そのパターンに沿った repo なら有用ですが、そうでない場合は前提と戦う時間が増えます。

scaffold-exercises スキルを改善するには

scaffold-exercises にはトピック一覧ではなく番号付きプランを渡す

scaffold-exercises の結果を最も早く改善できる方法は、テーマだけを投げるのをやめて、正確なターゲットパスを指定することです。比較すると違いが分かります。

Weak:

• “Add some exercises about retrieval.”

Strong:

• “Create exercises/01-retrieval-skill-building/01.01-keyword-search, 01.02-bm25, and 01.03-hybrid-search.”

後者のプロンプトでは、エージェントがフォルダ名を誤る余地がほとんどありません。

デフォルト任せにせず、バリアントの意図を明示する

バリアント種別を省略すると、スキルはスタブに explainer/ を選ぶことがあります。効率的ではありますが、教材設計の意図とはズレるかもしれません。次のように明示してください。

• 学習者の作業課題には problem/ を使う
• 参照用の解答には solution/ を使う
• 概念説明だけの教材には explainer/ を使う

この 1 点を明確にするだけで、scaffold の質はかなり変わります。

最低限でも有効な readme を要求する

よくある失敗は、ファイル自体は作られているのに使い物にならないプレースホルダーで終わることです。各 readme.md にタイトルと 1 文の説明を入れるようエージェントに指示してください。そうすればファイルが空にならず、後続の執筆もしやすくなります。

不要なコードファイルを増やさない

もう 1 つよくあるミスは、どこにでも main.ts を生成してしまうことです。上流のスキルでは、readme だけのスタブにそれは必須ではありません。軽量な scaffold が欲しいなら、「コードが明示的に必要な場合を除き readme-only」と伝えてください。最初の段階をすっきり保てます。

大量生成の前に名前を検証する

大きなバッチを作る場合は、いきなり生成させるのではなく、まず提案パスの一覧を出させ、承認後に作成させるのがおすすめです。これにより、番号の衝突や不自然な slug を、何十個ものフォルダをリネームする前に防げます。

最初の scaffold-exercises 実行後に 2 回目で整える

1 回目の実行後は、次の観点で見直すと改善しやすいです。

• 番号の連続性
• バリアントの不足がないか
• readme の実用性
• 各演習がそのセクションに本当に属しているか

そのうえで、修正だけに絞った 2 回目のパスをエージェントに依頼してください。生成とレビューを分けると、scaffold-exercises guide の最終品質は目に見えて上がります。

scaffold-exercises でも人の判断が必要な部分

scaffold-exercises skill は、適切な学習順序、演習難易度、教育上の網羅性までは判断してくれません。最も良い結果が出るのは、構造の自動化にはこのスキルを使い、カリキュラムの論理性については人がレビューする運用です。