skill-craft

スキルの設計

エージェントスキルを作成、編集し、調和させます。

使用する場面

• スキルをゼロから新規作成するとき
• 既存のスキルの SKILL.md またはフェーズを変更するとき
• スキルにフェーズを追加／削除するとき
• ユーザーがスキルの「調和」「整理」「標準化」を求めたとき

このスキルがある理由

規約がないと、スキルは徐々にばらばらになっていきます。一貫性のないフロントマターはスキルの検出を妨げ、単一の巨大なファイルは読み込むたびにトークンを浪費し、「落とし穴」のようなセクションがないと、エージェントは同じ間違いを繰り返します。このスキルでは、スキルの劣化を防ぐパターンを定めています。

落とし穴

• 説明文は検出に使われます：エージェントは description フィールドを使って、スキルを読み込むかどうかを判断します。説明が曖昧だと、スキルは起動しません。必ず説明文の定型に従ってください。
• 起動されにくいのが通常です：エージェントは、起動すべき場面でもスキルを起動しない傾向があります。説明文はやや「強め」にし、明白に思える場合でも、スキルを起動すべき状況や関連する言い回しを明記してください。
• 読み込まれることと使われることは別です：スキルが起動するたびに、SKILL.md はコンテキストに読み込まれます。含まれるトークンはすべて、会話履歴と競合します。500 行の SKILL.md は、単純なタスクでもコンテキストを消費します。
• フェーズファイルは読み込まれるまでコストがかかりません：フェーズファイルは、> Load: ディレクティブの後に読み込まれたときだけトークンを消費します。詳細な指示は SKILL.md ではなく、フェーズに記述してください。
• ファミリールールを重複させない：スキルがファミリーに属している場合、スキルとファミリールールの両方が読み込まれます。ルールを重複させると、トークンを二重に浪費します。
• Critical Rules はアンチパターンです：エージェントは Critical Rules セクションを過度に重視し、ほかの内容を軽視する傾向があります。事前チェックリストを使い、適切なタイミングで必要な事項を確認できるようにしてください。
• 条件付きの手順は省略されます：「X の場合は必須」と書かれた手順や、多数の小ステップ（5a、5b、5c など）に分割された手順は、エージェントが任意のものとして扱います。必ず実行させる必要がある手順には、条件付きの表現ではなく、(CHECKPOINT) マーカーと「絶対に省略しない」という命令形の指示を使ってください。
• スキルとエージェント設定の使い分け：スキルは、必要に応じて読み込むタスク固有のワークフロー向けです。エージェントの設定ファイル（例：CLAUDE.md、.cursorrules）は、常に適用するプロジェクトルール向けです。あらゆる会話に関係する知識（コーディング規約、命名規則など）は設定ファイルに記述してください。状況に応じて有効化される複雑なワークフローは、スキルにしてください。

基本原則

トークン効率

スキルの各トークンは会話履歴と競合します。エージェントには十分な能力があると考え、指示を書く前に「これがなければ、エージェントはこれをうまくできないだろうか？」と問いかけてください。答えが「いいえ」なら、省略してください。エージェントが本質的に知らないこと、つまりプロジェクト固有の規約、ドメイン知識、自明でないワークフロー、落とし穴だけを記述します。

❌ しないこと：「変更を git でコミットする」（エージェントは git を知っています） ✅ すること：「feat(scope): 形式でコミットする。scope には課題番号ではなく機能名を使う」

段階的な情報開示

SKILL.md はハブであり、巨大な一枚岩ではありません。詳細な指示は、エージェントが必要に応じて読み込むフェーズファイルや参照ファイルに記述してください。階層は最大 1 段階にしてください。参照ファイルからサブ参照ファイル、さらにその下位の参照ファイルへと連鎖させないでください。

サイズの目安：

• フロントマターの説明文：約 100 語以内（常にコンテキストに含まれます）
• SKILL.md の本文：500 行未満（スキルの起動時に読み込まれます）
• 300 行を超える参照ファイル：目次を追加してください

カテゴリの単一化

すべてのスキルが、ひとつのカテゴリに明確に収まるようにしてください。複数のカテゴリにまたがるスキルは、保守が難しく、起動条件も分かりにくくなります。ひとつのスキルで二つのことを行うなら、二つのスキルに分けてください。

自由度の段階

タスクの壊れやすさに応じて、指示の具体性を調整してください。

自由度	使用する場面	例
高	有効な方法が複数ある場合	コードレビューのガイドライン
中	推奨パターンがあり、多少の違いが許容される場合	レポートのテンプレート
低	壊れやすく、エラーが起きやすく、一貫性が重要な場合	DB マイグレーションコマンド

自由度が高い場合は、目標を示します。自由度が低い場合は、手順を正確に指定します。ほとんどのスキルは両方を組み合わせます。低い自由度は、失敗しても気づきにくい箇所に限ってください。

規約

1. ディレクトリ構成

{skill-name}/
├── SKILL.md              # Always required — the hub
├── phases/               # For multi-step workflows (3+ steps)
│   ├── 01-{name}.md
│   ├── 02-{name}.md
│   └── ...
├── references/           # Deep knowledge, loaded on-demand
├── scripts/              # Executable code (shell, Python)
└── templates/            # Content generation templates

• フェーズファイル：ゼロ埋めの kebab-case（01-context-gathering.md）
• 単一ファイルのスキル（フェーズなし）は、単純なコマンドや背景知識に適しています
• スキルをほかのスキルの中にネストしないでください
• スクリプト：「実行する」ものか「参考資料として読む」ものかを SKILL.md に明記します（Run scripts/validate.py と See scripts/validate.py for the algorithm）

2. 言語

すべてのスキルファイルは英語で記述する必要があります。対象言語で記述できるのは、コンテンツの例（サンプル投稿や記事の抜粋など）のみです。

3. フロントマター（必須）

すべての SKILL.md には、少なくとも name と description を含む YAML フロントマターが必要です。

---
name: skill-name # kebab-case, matches directory name
description: "[What it does]. Use when [trigger conditions]."
---

命名方針： スキルの機能を説明する、アクション指向の名前を優先します。

❌ 避ける：helper、utils、tools、data（曖昧で、起動されることはありません） ✅ 推奨：processing-pdfs、reviewing-code、deploying-api（具体的なアクション）

説明の形式： 三人称で、アクションを中心に記述します。スキルの機能を述べたうえで、いつ呼び出すかを示します。説明は、エージェントがこのスキルを読み込むかどうかを判断するために使われます。キーワード照合ではなく、LLM による推論が使われます。「積極的すぎる」くらいに記述し、スキルを起動するべき関連フレーズや状況も含めてください。

❌ 避ける：「レビューを支援します」 ✅ 推奨：「変更されたファイルに対して、5 フェーズのセキュリティ監査を実行します。ユーザーがコードの脆弱性レビューを依頼した場合、PR のマージ前、またはセキュリティ関連ファイルが変更された場合に使用します。」

任意のフィールド：

フィールド	使用するタイミング	例
argument-hint	スキルが引数を取る場合	"[issue-number]"
disable-model-invocation	手動のみ（副作用、破壊的操作）	true
user-invocable	背景知識であり、コマンドではない場合	false
allowed-tools	ワークフローで実行するツールを事前承認する	Bash(gh issue view:*), Read, Grep

判断の指針：

• ユーザーが直接実行する → デフォルトのままにします（user-invocable: true）
• ほかのスキルからのみ読み込まれる → user-invocable: false
• 副作用がある（プッシュ、公開、削除） → disable-model-invocation: true
• 純粋な知識（音声プロファイル、ルール） → user-invocable: false

allowed-tools は事前承認するものであり、制限するものではありません。 スキルが有効な間、指定したパターンは新たな許可確認なしで実行できます。ただし、ユーザーの該当する ask ルールと deny ルールは引き続き適用され、一覧にないツールには現在の許可設定が適用されます。ネットワークや VCS の包括的なパターン（Bash(curl:*)、Bash(git:*)、Bash(gh:*)）は絶対に指定しないでください。エージェントが信頼できないコンテンツ（API 応答、Issue 本文）を読み込んでいる間に、任意のホストへのアップロード、強制プッシュ、gh auth token の実行などが可能になります。コマンドグループのプレフィックスも包括的な指定になります。Bash(gh issue:*) は gh issue delete と gh issue transfer も承認します。ワークフローで実行する読み取りサブコマンドを正確に指定し（Bash(gh issue view:*)、Bash(gh label list:*)）、書き込み操作は許可確認を求めるようにしてください。

4. 推奨セクション

すべての SKILL.md に、次の内容を含めることをおすすめします。

セクション	必須？	目的
## When to Use	はい	起動条件 — エージェントがこのスキルを読み込むべきタイミング
## Why This Exists	推奨	動機 — 使用すべきでない場面をエージェントが判断しやすくなります
## Gotchas	推奨	分かりにくい落とし穴、エッジケース、気付かないうちに問題を起こす要因
## Phase N: Name	複数ステップの場合	各フェーズの概要と読み込み指示

「Gotchas」セクションは特に有用です。このスキルがなければエージェントが誤る点を記録します。これがトークン効率の要です。エージェントが知っていることは省き、知らないことに集中してください。

5. 例の書式

良い例と悪い例は、必ず次の書式を使用してください。

❌ Don't: "example of what not to do"
✅ Do: "example of what to do"

6. 読み込み指示

フェーズやほかのスキルを参照するには、> Load: 形式を使用してください。

> Load: [Phase Name](phases/01-phase-name.md)
> Load: [Shared Rules](../other-skill/SKILL.md)

• SKILL.md の場所からの相対パスを必ず使用してください
• 読み込み指示は独立した行に記述してください

7. スキルファミリー

共通のプレフィックス（例：blog-*、email-*）を持つ関連スキルでは、共通設定用の {prefix}-rules スキル（user-invocable: false）を共有してください。スキルとファミリールールの間でルールを重複させないでください。どちらもコンテキストに読み込まれます。

8. 動作ルール

• ユーザー入力：質問をプレーンテキストで表示しないでください。ユーザーが応答するまで実行をブロックするインタラクティブツールを使用してください（Claude Code：AskUserQuestion）。
• チェックポイント：エージェントが次に進む前にユーザー入力を必ず待つステップには、ステップのタイトルに (CHECKPOINT) を付け、「このステップを省略してはいけません。完了する前に次のフェーズへ進んではいけません。」という指示を明記してください。こうしないと、特にサブステップに含まれている場合や、「有効な場合」のような条件付きの表現で示されている場合に、エージェントは対話型のステップを任意のものと見なして省略しがちです。
• タスクの追跡：サブステップが3つ以上あるフェーズでは、ユーザー向けではなく、AI の自己追跡のためにタスク追跡を使用してください（Claude Code：TodoWrite）。
• 逐次実行：4つ以上のフェーズからなるワークフローでは、テキストベースの事前条件ではなく、プランモードと TodoWrite を使って逐次実行を徹底してください。まずプランモードで開始し、ユーザーがパイプライン全体を確認して承認できるようにします。TodoWrite をすべてのフェーズが保留中の状態で初期化してください。各フェーズの開始時に in_progress、完了時に completed にします。一度に in_progress にできるフェーズは1つだけです。各フェーズファイルに「事前条件：フェーズNが完了していること」というテキストを記載するよりも堅牢です。TodoWrite では進捗を視覚的に追跡でき、プランモードによってユーザーの承認が必須になるためです。
• フェーズタイトルに所要時間を記載しない：所要時間の見積もり（「約30分」「約1時間」）は不要な情報です。常に不正確で、ツールの複雑さによって異なり、パイプラインを煩雑にします。所要時間ではなく、フェーズで行う内容を記載してください。
• 公開前チェックリスト：公開直前の最後のフェーズでは、## Critical Rules を検証可能なチェックリストに置き換えてください。各項目は曖昧ではなく、テスト可能でなければなりません。
• 共有コンテンツへの書き込み：他の人が読むもの（イシュー、PR、ドキュメント、メッセージ）を作成または編集する前に、(CHECKPOINT) で完成形（本文全体または差分）を正確に提示し、承認された内容だけを書き込んでください。承認後に変更を加える場合は、公開前の修正も含め、再度提示してください。本文はファイルとして渡してください（--body-file）。バッククォートや $ をシェルが展開するインラインのシェル文字列は使用しないでください。
• 重要な出力：ユーザーが承認する出力や、判断の根拠となる出力（差分、ログ、一覧）は、エージェントが全体を受け取れるようにしてください。コマンドプロキシや出力を圧縮するフック（例：rtk）は、diff、git diff／log／show／status／branch、gh pr diff、cat、head、tail を、行が省かれる切り詰められた要約や読み取りに書き換えたり、curl の応答を値のない JSON スキーマ（id: int）や途中で切れた HTML ページに書き換えたりすることがあります。これらは終了コード 0 を返すこともあり、find のアクション（-delete、-exec）を拒否する場合もあります。これはガードではなく制限であり、処理は何も起きずに終わります。ファイルは Read ツールで読み込み、重要なコマンドはフックを明示的にバイパスして実行してください（RTK_DISABLED=1 git --no-pager diff --no-index -- a b、RTK_DISABLED=1 git --no-pager log、エージェントが本文を読む必要のあるすべての応答（POST 応答を含む）には RTK_DISABLED=1 curl -s <url>、削除が必要な find はディレクトリ1つと名前パターン1つに対象を限定して RTK_DISABLED=1 command find "<dir>" -maxdepth 1 -name '*.tmp' -delete）。今日のところ認識されないだけの形式（git --no-pager … など）は、フックの次のバージョンで書き換えられる可能性があります。この変数はフックがない環境では無害です。また、接頭辞を付けたコマンドはフックによる自動許可の対象でも、allowed-tools のプレフィックスとの照合対象でもなくなるため、確認を求められます。環境にフックがある場合は、フックに対するコマンドの動作を確認してください（rtk rewrite '<command>'）。このルールはエージェントが実行するコマンドに適用されます。!`…` のプリロードはフックの外で実行され、書き換えられず、allowed-tools との照合を維持するため接頭辞も付けないでください。

### N. Pre-flight checklist

**Verify every item below.** Display pass/fail status. Fix failures before proceeding.

[ ] Item 1 — what to verify
[ ] Item 2 — what to verify

新しいスキルの作成

ステップ 1：スキルのカテゴリを決める

スキルが何についてのものかではなく、何をするのかで分類します。すべてのスキルは、次のいずれかのカテゴリに当てはまる必要があります。

カテゴリ	役割	特徴	例
ライブラリ／API リファレンス	ツール、SDK、内部ライブラリの正しい使い方をまとめます	user-invocable: false、必要に応じて読み込み	brand-voice、writing-style
プロダクトの検証	出力が正しいかテストまたは検証します	スクリプトと組み合わせ、明確な合否判定がある	content-audit、security-review
データ取得と分析	データソースに接続し、クエリを実行します	MCP サーバーまたは API を使用し、構造化データを返す	analytics-report、metrics-check
ビジネスプロセス	繰り返し行うワークフローを自動化します	複数のステップがあり、チェックポイントに基づいて進行する	standup-post、release-notes
コードのひな形生成	プロジェクトのパターンに沿ったボイラープレートを生成します	テンプレートを使用し、規約を考慮する	new-feature、add-connector
コード品質	標準を徹底し、コードをレビューします	サブエージェントを起動し、問題がなくなるまで反復する	code-review、lint-check
CI/CD とデプロイ	ビルド、テスト、デプロイを行います	副作用があるため、disable-model-invocation: true を設定する	deploy、publish
ランブック	既知の問題を診断し、解決します	判断ツリーと症状の照合を行う	debug、incident-response
共通設定	規約と設定を提供します	user-invocable: false、ファミリー単位で読み込み	family-rules、shared-config

1 つのスキルが 2 つのカテゴリにまたがる場合は、分割してください。

ステップ 2：ディレクトリをひな形から作成し、SKILL.md を記述する

1. name、説明の書式に従った description を含むフロントマター
2. 1 行の説明ブロック
3. ## When to Use セクション（トリガー条件）
4. ## Why This Exists セクション（目的、これがない場合に起きる問題）
5. ## Gotchas セクション（見落としやすい注意点）
6. フェーズと依存関係の読み込みディレクティブ

ステップ 3：フェーズファイルを記述する（複数のステップがある場合）

各フェーズファイルは # 見出しから始め、実行可能な指示を記載します。SKILL.md では、読み込みディレクティブと、そのフェーズで作成されるものの簡単な説明を添えて、各フェーズを参照します。

ステップ 4：現実的なプロンプトで検証する

実際にユーザーが入力しそうな、自然な表現と文脈を含む現実的なプロンプトを 2～3 個使ってスキルをテストします。スキルが正しく起動し、期待どおりの動作をすることを確認してください。起動が不安定な場合は、説明をより「強く」してください。

既存のスキルを編集する

1. 変更を加える前に、現在の SKILL.md とすべてのフェーズを読む
2. フロントマターが有効で、最新の状態であることを確認する
3. 読み込みディレクティブが正しいパスを参照していることを確認する
4. 編集後に、以下の規約チェックを実行する

アンチパターン

スキルを記述する際は、次のよくある間違いを避けてください。

アンチパターン	問題点	修正方法
エージェントがすでに知っていることを繰り返す	トークンを浪費し、会話のコンテキストと競合します	プロジェクト固有の知識や、分かりにくい知識だけを記載します
ファイルパスをハードコードする	プロジェクト構成が変わると壊れます	{baseDir} のプレースホルダーを使うか、パターンを説明します
深くネストされた参照	参照をたどるうちにエージェントがコンテキストを失います	SKILL.md からの参照は最大1階層にします
時間の経過で変わる情報	古くなり、誤った動作につながります	日付はスキルではなく、エージェントの設定ファイルに記載します
プルリクエストや課題への参照（「PR #16」、「gustav-app#1521」）	次の読者には意味がなく、マージ後は古くなります	現在のルールを記載します。過去の事例が説明に役立つ場合は、文章で説明します
既定値のない複数の選択肢	エージェントがどれを選ぶべきか推測しなければなりません	常に既定値を指定し、代替案も記載します
厳格な ALWAYS／NEVER コマンド	エージェントが考えずにチェック項目を埋めるようになります	ルールの 理由 を説明します。エージェントは厳格な命令より、理由に基づく説明によく反応します
用語の不統一	セクション間でエージェントが混乱します	概念ごとに用語を1つ選び、一貫して使用します（例：「route」、「URL」、「path」を混在させず、常に「endpoint」を使う）
巨大な SKILL.md（500行以上）	毎回読み込まれ、トークンを浪費します	phases/ と references/ に分割します
テキストによる前提条件（「前提条件：フェーズNが完了していること」）	エージェントは読んでも実行を強制されないため、コンテキストの余裕がないと簡単に飛ばされます	順序を強制するために、計画モードと TodoWrite を使います
フェーズのタイトルに時間の見積もりを入れる（「約30分」）	常に不正確で、複雑さによって変わり、パイプラインが煩雑になります	時間ではなくフェーズの内容を示し、時間の記載は削除します
サブスキルのルールを書き換えるオーケストレータースキル	ルールが重複し、元の内容から乖離し、トークンを浪費します	指示をコピーせず、サブスキルを名前で参照します（「/humanizer を実行する」）
手作業のチェックリストの隣にサブスキルの呼び出しを置く	エージェントがチェックリストを手動で実行し、スキルを飛ばします。「/seo-auditor を実行する」の下にチェック項目を5つ並べると、エージェントは自分で5項目を確認し、スキルを呼び出しません	サブスキルの呼び出しは、CHECKPOINT とともに、手動チェックより前の番号付き手順にします。手動チェックはその後に、サブスキルが対応しない項目だけを対象に行います

規約チェック（作成／編集後に実行）

• Frontmatter に name と description がある（どちらも空でない）
• description が次の形式に従っている：「[機能]. Use when [trigger].」
• description が、トリガー不足を防ぐのに十分な強さで記述されている
• name がディレクトリ名（kebab-case）と一致している
• スキルが1つのカテゴリに明確に収まっている（複数のカテゴリにまたがっていない）
• ## When to Use セクションがある
• エージェントが本来知っている内容は記述していない（トークン効率のため）
• SKILL.md の本文が500行未満である
• phases/ がある場合、フェーズファイルに番号が付いている（01-、02- など）
• 読み込み指示が相対パスを使い、既存のファイルを指している
• スキルとそのファミリーのルール間に重複するルールがない
• SKILL.md からの参照が最大1階層である
• ハードコードされた絶対パスがなく、相対パスまたはパターンベースのパスを使用している
• ユーザー入力には対話型質問ツールを使用している（ワークフロー／コンテンツ系スキル）
• スキルに副作用がある場合、disable-model-invocation: true が設定されている
• 背景知識を提供するスキルの場合、user-invocable: false が設定されている
• すべての内容が英語である（例のみ対象言語を使用してよい）
• 例が ❌ Don't:／✅ Do: 形式になっている
• ## Critical Rules セクションがない — ルールは実行前チェックリストで適用する
• 副作用のあるワークフロー系スキルに実行前チェックリストがある
• ユーザー入力が必要な手順に (CHECKPOINT) と「Do NOT skip」の指示が付いている
• ブロックする手順に条件付きの表現（「必須の場合は...」など）がない — 命令形を使用する
• 用語が全体を通して一貫している（概念ごとに用語を1つに統一）
• name がアクションを示している（helper や utils のような曖昧な名前ではない）
• 現実的なプロンプトを2〜3件使って検証している
• 複数フェーズのワークフローでは、テキストによる事前条件ではなく、プランモードと TodoWrite を使用している
• フェーズのタイトルに所要時間の見積もりが含まれていない
• オーケストレータースキルは、ルールを重複して記述せず、サブスキルを名前で参照している
• サブスキルの呼び出しが、手動チェックリスト内の注釈ではなく、CHECKPOINT を含む番号付きの手順になっている
• allowed-tools に、包括的なネットワークまたはVCSパターン（curl:*、git:*、gh:*）や、コマンドグループのプレフィックス（gh issue:*）が含まれていない — 読み取り用のサブコマンドのみを正確に指定する
• 承認用に表示する出力やチェックに使用する出力（diff、ログ、ステータス、読み戻したファイル）は、Read ツール、またはフックで明示的に許可されているバイパスを付けたコマンド（RTK_DISABLED=1 …）から取得している。curl のレスポンス本文も含む。!`…` のプリロードにはプレフィックスを付けない
• 共有コンテンツへのすべての書き込みが、正確な結果を示す CHECKPOINT に従っている。本文はファイルとして渡す