scaffold-exercises

scaffold-exercises の概要

scaffold-exercises は、リポジトリの命名規則と lint 条件に合う演習ディレクトリを作るための、セットアップ重視の skill です。新しいセクションを追加したいとき、演習のひな形を作りたいとき、あるいは problem / solution / explainer のレイアウトを迷わず標準化したいときに特に役立ちます。実際の役割は単に「フォルダを作る」ことではなく、「内容投入、レビュー、そして pnpm ai-hero-cli internal lint にそのまま回せる、有効な演習スキャフォールドを作る」ことです。

scaffold-exercises は何のために使うか

すでに追加したい学習コンテンツは決まっているが、それを収めるきれいなディレクトリ骨組みが必要なときに scaffold-exercises skill を使います。コース作成者、メンテナー、そして複数セクションにまたがって再現可能な演習構造を作る必要があるエージェントに向いています。

どんな場面で特に役立つか

この skill が最も強いのは、リポジトリに厳格な規約がある場合です。たとえば、番号付きセクション、番号付き演習、各バリアントフォルダ内の必須 readme.md などがあるケースです。頻繁にひな形を起こすワークフローなら、scaffold-exercises の導入は特に価値があります。内容を書き始める前に、書式上のミスを減らせるからです。

事前にこちらから用意すべきこと

この skill は、セクション番号、演習番号、演習名、そして想定するバリアント種別を渡せることを前提にしています。依頼が曖昧でもスキャフォールド自体は作れますが、problem、solution、explainer の使い分けがはっきりしているほど、結果は良くなります。

scaffold-exercises skill の使い方

scaffold-exercises をインストールする

scaffold-exercises skill は次のコマンドでインストールします。

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

これが、この repo で使う実践的な scaffold-exercises の導入パスです。インストール後は、汎用的な文章作成プロンプトではなく、ディレクトリ作成のワークフローとして使ってください。

skill に構造化されたブリーフを渡す

scaffold-exercises の使い方で最も良いのは、対象セクション、演習、希望するバリアントを短く整理した計画から始める方法です。たとえば、「exercises/02-generation/02.01-rerank-basics/ に explainer/ と solution/ のひな形を作り、命名は dash-case に統一し、各 readme に内容を入れてください」という指定です。これは「レッスンをスキャフォールドして」とだけ言うよりずっと良い依頼です。作るべき path と、存在が必要な file を skill に明確に伝えられるからです。

先に読むべきファイルを読む

まず SKILL.md を読み、その後にセクション名の付け方、必須サブフォルダ、ひな形の内容など、repo の演習規約を確認してください。もし関連する案内が別の場所にもあるなら、生成を始める前にそれらの file も読んでください。scaffold-exercises では、重要な判断ポイントはディレクトリ形式、既定のバリアント、そして code file が必要か、それとも readme だけのひな形で足りるか、の 3 つです。

repo の最小有効パターンに従う

scaffold-exercises の安全な進め方は、先にディレクトリを作り、その後で空ではない readme.md を追加し、main.ts はそのバリアントに実際の code が入る場合だけ追加する、という流れです。ひな形を作る段階なら、未完成の学習者作業を暗示してしまう problem file を無理に捏造するより、explainer/ を既定にするほうがたいてい整理しやすくなります。タイトルは演習名と揃え、初回のプレースホルダーでは壊れた link を作らないようにしてください。

scaffold-exercises skill の FAQ

scaffold-exercises は新しい演習だけのためのものか

いいえ。scaffold-exercises skill は、新しいセクションを追加するときや、既存の演習シリーズを標準化したいときにも役立ちます。深い内容を書く前に、repo の演習構造を有効な形にしておく必要がある場面なら、いつでも有用です。

通常のプロンプトの代わりに skill を使う必要はあるか

構成の正確さが文章表現より重要なときに skill を使ってください。通常のプロンプトでもアイデアは説明できますが、命名規則、必須フォルダ、lint に通りやすいひな形を守る必要があるなら、scaffold-exercises のほうが適しています。

scaffold-exercises は初心者向けか

はい。演習名と対象フォルダを特定できるなら使えます。初心者がやりがちな主なミスは、バリアント種別の指定が足りないことや、セクション番号と演習番号の規則を無視することです。その結果、見た目はそれらしいが repo に合わない path になってしまいます。

scaffold-exercises を使わないほうがよいのはいつか

レッスン本文、ブレインストーミング、あるいはディレクトリ制約のない単発の markdown 下書きだけが必要な場合は、scaffold-exercises は使わないでください。これは repo 構造のための skill であり、内容生成の近道ではありません。

scaffold-exercises skill を改善する方法

より正確な path とバリアントの意図を伝える

品質を最も大きく上げるのは、正確な directory と各サブフォルダの役割を指定することです。強い依頼では、何を存在させるべきかを明示します。たとえば、「exercises/03-ranking/03.02-bm25-tuning/ に problem/、solution/、explainer/ の readme を作成し、problem/ には TODO を入れ、solution/ には reference outline を入れ、explainer/ は概念説明にとどめてください」という形です。これなら scaffold-exercises skill は最初の一回で適切な構造を作りやすくなります。

よくある失敗パターンに注意する

最も多い問題は、番号付けの誤り、readme.md の欠落、空のプレースホルダー、そしてひな形だけで十分な演習に code file を足してしまうことです。もう一つよくあるミスは、セクションレベルの名前と演習レベルの名前を同じ path に混ぜてしまうことです。scaffold-exercises のガイドは、命名規則と内容要件を切り分けて考えるときに最も効果を発揮します。

最初のスキャフォールドの後に反復する

生成後は、各フォルダに必要な file がそろっているか、各 readme の文言が実際の演習種別と合っているかを確認してください。あとから code が必要だと判断した場合は、学習体験が変わる場所にだけ main.ts を追加します。scaffold-exercises の改善サイクルで最も速いのは、スキャフォールド → lint → 名前修正 → 内容拡張、の順です。