Skill Creator

Skill / SubAgent の選択

作成に入る前に、Skill と SubAgent のどちらが要件に合うかを判断する。

Skill を選ぶ場面

• 作業プロセスを手順として残す必要がある
• 専門知識やスキーマをコンテキストに保持しながら作業したい
• スクリプトの実行など確定的な処理を含む
• 再利用可能なワークフローや手順を定義する

SubAgent を選ぶ場面

• タスクを委譲し、結果だけ受け取れれば十分
• 複数の方向を並行して調査したい
• プロセスの記録が不要

要件を分析
  ↓
プロセスを記録する必要がある / 専門知識をコンテキストに保持したい
  → Yes → Skill
  → No  → タスクを委譲して結果だけ受け取りたい？
            → Yes → SubAgent
            → No  → Skill

SubAgent が適切と判断した場合は skills/subagent-creator/SKILL.md を読み込んで指示に従う。

---

スキルの構造

スキルは SKILL.md を核とした自己完結型パッケージとして構成する。

skill-name/
├── SKILL.md           （必須）
│   ├── YAML frontmatter  name + description
│   └── Markdown body     手順・ガイダンス
├── scripts/           （任意）実行可能コード
├── references/        （任意）参照ドキュメント
└── assets/            （任意）出力に使うファイル

SKILL.md

• frontmatter: name と description の2フィールドのみ。description はスキルの発動条件を決める最重要テキストなので、何をするスキルか・どんな場面で使うかを具体的に書く
• body: スキルが発動した後に読み込まれる手順・ガイダンス。発動前には読まれないため、トリガー条件は body ではなく description に書く

scripts/

繰り返し書き直すコードや、確定的な処理が求められるタスクをスクリプトとして格納する。コンテキストに読み込まずに実行できるため、トークン効率が高い。

references/

作業中に必要に応じて参照するドキュメント。APIリファレンス、スキーマ定義、詳細ガイドなど。SKILL.md を簡潔に保ちつつ、必要な情報を参照可能にする。

assets/

コンテキストに読み込む必要はないが、出力生成時に使用するファイル。テンプレート、画像、フォントなど。

---

設計の指針

簡潔さを最優先する

コンテキストウィンドウはシステムプロンプト・会話履歴・他スキルのメタデータ・ユーザーの依頼で共有される有限のリソース。スキルに含める情報は、AI が既に知っている内容を除いた差分だけにする。

各段落について「この説明がなければ AI は誤った処理をするか？」と問い、No なら削る。冗長な説明より簡潔な例のほうがトークン効率も理解度も高い。

指示の具体度を調整する

タスクの性質に応じて、指示をどこまで具体的にするかを変える。

• 高自由度（テキスト指示）: 正解が複数あり、文脈で判断が変わる場面。「分析レポートを書く」など
• 中自由度（擬似コード・パラメータ付きスクリプト）: 推奨パターンがあるが多少の変動を許容する場面
• 低自由度（固定スクリプト）: 手順の逸脱がエラーに直結する場面。ファイル変換やバリデーションなど

壊れやすい処理ほど具体的に、判断が必要な処理ほど自由度を持たせる。

段階的に情報を開示する

スキルは3層で情報を管理する。

1. メタデータ層（name + description）: 常にコンテキストに存在する。約100語
2. SKILL.md 本文: スキルが発動した時に読み込まれる。500行以内を目安にする
3. バンドルリソース: SKILL.md から明示的に参照された時のみ読み込む。scripts/ は実行のみで読み込み不要な場合もある

SKILL.md が500行を超えそうな場合は references/ に分離する。分離した場合、SKILL.md 側にファイルパスと読み込みタイミングを必ず記載する。

参照ファイルの構成パターンについては references/output-patterns.md と references/workflows.md を参照。

---

作成の手順

Step 1: 用途の把握

スキルの使われ方を具体例で把握する。既に明確な場合はスキップ可。

• どんな依頼に対して発動するか
• 入力と出力は何か
• 繰り返しのパターンは何か

ユーザーに確認すべき点があれば、重要な質問から順に聞く。一度に大量の質問を投げない。

Step 2: リソースの設計

Step 1 の具体例を元に、再利用すべきリソースを洗い出す。

• 毎回書き直すコードがある → scripts/ にスクリプト化
• 毎回調べ直す情報がある → references/ にドキュメント化
• 毎回コピーするファイルがある → assets/ にテンプレート化

Step 3: 初期化

新規スキルの場合、初期化スクリプトでテンプレートを生成する。

python skills/skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>

既存スキルの更新であればこのステップは飛ばす。

Step 4: 実装

テンプレートから不要なファイルを削除し、リソースの実装と SKILL.md の執筆を行う。

frontmatter の書き方

• name: ハイフン区切りの小文字（例: data-analyzer）
• description: スキルの機能と発動条件を1文で書く。body には「いつ使うか」を書かない（発動前に body は読まれない）

body の書き方

• 命令形で書く
• AI が既知の常識は省く
• 詳細パターンは references/ に分離する

scripts/ に追加したスクリプトは実際に実行してバグがないことを確認する。

Step 5: パッケージ化

完成したスキルを .skill ファイルにまとめる。

python skills/skill-creator/scripts/package_skill.py <path/to/skill-folder> [output-directory]

バリデーションエラーが出た場合は修正して再実行する。

Step 6: 反復改善

実際にスキルを使い、非効率や不足に気づいたら SKILL.md やリソースを更新する。

1. 実タスクでスキルを使う
2. うまくいかない点、冗長な点を特定する
3. SKILL.md またはリソースを修正する
4. 再度テストする