designing-workflow-skills

ワークフロースキルの設計

文章ではなく、構造的なパターンに従って、確実に実行できるワークフローベースのスキルを構築します。

基本原則

<essential_principles>

**スキルを有効化するタイミングを制御するのは、`description` フィールドだけです。**

Claude は、フロントマターの description のみに基づいてスキルを読み込むかどうかを判断します。「使用するタイミング」や「使用しないタイミング」のセクションを含め、SKILL.md の本文は、スキルが有効になった後に初めて読み込まれます。トリガーとなるキーワード、ユースケース、対象外の条件は、説明に記載してください。不適切な説明では、本文に何を書いても、誤った有効化や有効化の見逃しが起こります。

「使用するタイミング」と「使用しないタイミング」のセクションにも、スキルが有効になった後の LLM の動作範囲を定める役割があります。「使用しないタイミング」では、具体的な代替手段を挙げてください。「単純なパターンマッチングには Semgrep を使用する」とし、「単純なタスクには使わない」といった表現は避けてください。

**フェーズには番号を付け、開始条件と終了条件を定めてください。**

番号のない文章形式の指示では、実行順序が不安定になります。すべてのフェーズには、以下が必要です。

• 番号（フェーズ 1、フェーズ 2、…）
• 開始条件（開始前に満たすべき条件）
• 番号付きのアクション（実行する内容）
• 終了条件（完了したと判断する方法）

**ツールは実行者に合わせてください。**

スキルではフロントマターに allowed-tools: を使用します。エージェントではフロントマターに tools: を使用します。サブエージェントは subagent_type からツールを取得します。そのコンポーネントが使用しないツールは、決して列挙しないでください。専用ツール（Glob、Grep、Read、Write、Edit）がある操作には、決して Bash を使用しないでください。

ほとんどのスキルとエージェントでは、ツールのリストに TodoRead と TodoWrite を含めてください。これらを使うと、複数ステップの実行中に進捗を追跡できます。明示的にタスクを管理しないスキルでも便利です。

**段階的な情報開示は構造上の要件であり、任意ではありません。**

SKILL.md は 500 行未満にしてください。すべての呼び出しで LLM が必要とする内容、つまり原則、振り分け、クイックリファレンス、リンクだけを記載します。詳細なパターンは references/ に記載します。手順ごとのプロセスは workflows/ に記載します。参照の階層は 1 段階にとどめ、参照を連鎖させないでください。

**指示によって、スケール可能なツール呼び出しパターンが生成されるようにしてください。**

実行時には、ワークフローの各指示がツール呼び出しに変換されます。ワークフローで N 個のファイルから M 個のパターンを検索する場合、N×M 回呼び出すのではなく、1 つの正規表現にまとめてください。項目ごとにサブエージェントを起動するワークフローでは、ファイルごとに 1 つ起動するのではなく、バッチ処理を使用してください。1 万ファイルのテストを行い、大規模なリポジトリでワークフローを実行する状況を想定して、ツール呼び出し数が一定の範囲に収まるか確認してください。AP-18 と AP-19 については、anti-patterns.md を参照してください。

**指示の具体性は、タスクの壊れやすさに合わせてください。**

すべての手順に同じ程度の細かさで指示する必要はありません。手順ごとに調整してください。

• 自由度：低（正確なコマンド、変更不可）：壊れやすい操作（データベース移行、暗号処理、破壊的な操作）。「このスクリプトを正確に実行してください。」
• 自由度：中（パラメーターを含む疑似コード）：推奨パターンで、多少の変更が許容される場合。「このテンプレートを使い、必要に応じてカスタマイズしてください。」
• 自由度：高（ヒューリスティックと判断）：変動するタスク（コードレビュー、調査、ドキュメント作成）。「構造を分析して、改善案を提示してください。」

1 つのスキルで、自由度の異なる手順を組み合わせることもできます。たとえば、セキュリティ監査スキルでは、発見フェーズでは自由度を高くして（「コードベースを調査し、認証パターンを見つけてください」）、レポートフェーズでは自由度を低くできます（「この重大度分類表をそのまま使用してください」）。

</essential_principles>

使用する場面

• 複数ステップのワークフローや段階的な実行を伴う新しいスキルを設計する場合
• 複数の独立したタスクを切り替えて処理するスキルを作成する場合
• 安全ゲート（破壊的な操作に確認を必須とする仕組み）を備えたスキルを構築する場合
• サブエージェントやタスク追跡を使用するスキルを構成する場合
• 既存のワークフロー型スキルの品質をレビューまたはリファクタリングする場合
• SKILL.md、references/、workflows/ の間でコンテンツをどう分割するか判断する場合

使用しない場面

• ワークフローのない単純な単一目的のスキル（ガイダンスのみ）の場合 — SKILL.md を直接作成してください
• スキルのドメイン固有のコンテンツを実際に執筆する場合（ここでは構成を説明しており、ドメインの専門知識は扱いません）
• プラグインの設定（plugin.json、hooks、commands）の場合 — プラグイン開発ガイドを使用してください
• スキル以外の Claude Code 開発の場合 — これはスキルのアーキテクチャに特化しています

パターンの選択

スキルの構成に合ったパターンを選択してください。workflow-patterns.md で各パターンの詳細を確認してください。

How many distinct paths does the skill have?
|
+-- One path, always the same
|   +-- Does it perform destructive actions?
|       +-- YES -> Safety Gate Pattern
|       +-- NO  -> Linear Progression Pattern
|
+-- Multiple independent paths from shared setup
|   +-- Routing Pattern
|
+-- Multiple dependent steps in sequence
    +-- Do steps have complex dependencies?
        +-- YES -> Task-Driven Pattern
        +-- NO  -> Sequential Pipeline Pattern

パターンの概要

パターン	使用する場面	主な特徴
ルーティング	共通の受付から複数の独立したタスクに分岐する場合	ルーティングテーブルで意図とワークフローファイルを対応付けます
順次パイプライン	各ステップが次のステップに引き継がれる依存関係がある場合	部分的な進捗から自動検出によって再開できる場合があります
線形進行	毎回同じ単一の手順をたどる場合	開始条件と終了条件を定めた番号付きフェーズ
安全ゲート	破壊的または取り消せない操作の場合	実行前に2つの確認ゲートを設けます
タスク駆動型	複雑な依存関係があり、一部の失敗を許容する場合	依存関係の追跡に TaskCreate/TaskUpdate を使用します

構造の全体像

パターンにかかわらず、すべてのワークフロー型スキルには次の骨組みが必要です。

---
name: kebab-case-name
description: "Third-person description with trigger keywords — this is how Claude decides to activate the skill"
allowed-tools: Tool1 Tool2 Tool3  # space-delimited list of tool names
# Optional fields — see tool-assignment-guide.md for full reference:
# disable-model-invocation: true    # Only user can invoke (not Claude)
# user-invocable: false             # Only Claude can invoke (hidden from / menu)
# context: fork                     # Run in isolated subagent context
# agent: Explore                    # Subagent type (requires context: fork)
# model: [model-name]               # Switch model when skill is active
# argument-hint: "[filename]"       # Hint shown during autocomplete
---

# Title

## Essential Principles
[3-5 non-negotiable rules with WHY explanations]

## When to Use
[4-6 specific scenarios — scopes behavior after activation]

## When NOT to Use
[3-5 scenarios with named alternatives — scopes behavior after activation]

## [Pattern-Specific Section]
[Routing table / Pipeline steps / Phase list / Gates]

## Quick Reference
[Compact tables for frequently-needed info]

## Reference Index
[Links to all supporting files]

## Success Criteria
[Checklist for output validation]

スキルでは、3種類の文字列置換をサポートしています。引数とセッション ID に使うドル記号で始まる変数と、シェルの前処理に使う感嘆符とバッククォートの構文です。スキルローダーはこれらを Claude がファイルを見る前に処理するため、コードフェンス内も含め、ドキュメント本文では生の構文を使わないでください。変数の一覧と使用方法については、tool-assignment-guide.md を参照してください。

アンチパターンのクイックリファレンス

よくある間違いをまとめています。修正前後の例を含む完全な一覧は、anti-patterns.mdをご覧ください。

AP	アンチパターン	1 行での修正方法
AP-1	目標／対象外事項がない	「使用する場合」と「使用しない場合」のセクションを追加します
AP-2	SKILL.md が肥大化している（500 行超）	references/ と workflows/ に分割します
AP-3	参照が連鎖している（A -> B -> C）	すべてのファイルを SKILL.md から 1 段階で参照できるようにします
AP-4	パスがハードコードされている	内部パスにはすべて {baseDir} を使用します
AP-5	ファイル参照が壊れている	提出前にすべてのパスが解決できることを確認します
AP-6	フェーズに番号が付いていない	すべてのフェーズに開始／終了条件を付けて番号を振ります
AP-7	終了条件がない	すべてのフェーズで「完了」の定義を明確にします
AP-8	検証ステップがない	すべてのワークフローの最後に検証を追加します
AP-9	ルーティングキーワードが曖昧	ワークフローのルートごとに固有のキーワードを使用します
AP-11	作業に不適切なツールを使っている	Bash の代わりに Glob／Grep／Read を使用します
AP-12	ツールに過剰な権限を与えている	実際に使わないツールを削除します
AP-13	サブエージェントへの指示が曖昧	分析対象、確認事項、返却内容を明確に指定します
AP-15	参照資料をそのまま羅列している	生のドキュメントではなく、判断の仕方を教えます
AP-16	合理化への対処がない	監査スキルに「退けるべき合理化」を追加します
AP-17	具体例がない	重要な指示には入力 -> 出力の例を示します
AP-18	直積状のツール呼び出し	パターンを 1 つの正規表現にまとめて一度 grep し、その後絞り込みます
AP-19	サブエージェントを際限なく起動する	項目をグループにまとめ、バッチごとにサブエージェントを 1 つ起動します
AP-20	説明文がワークフローを要約している	説明文には起動条件のみを記載し、ワークフローの手順は記載しません

AP-10（デフォルト／フォールバックルートがない）、AP-14（エージェントでツールの選定理由が不足している）、AP-20（説明文がワークフローを要約している）は、完全な一覧にあります。AP-20 は影響が大きいため、上のクイックリファレンスにも含めています。

ツール割り当てのクイックリファレンス

コンポーネントの種類に合ったツールセットを割り当てます。詳細なガイドはtool-assignment-guide.mdをご覧ください。

コンポーネントの種類	一般的なツール
読み取り専用の分析スキル	Read, Glob, Grep, TodoRead, TodoWrite
対話型の分析スキル	Read, Glob, Grep, AskUserQuestion, TodoRead, TodoWrite
コード生成スキル	Read, Glob, Grep, Write, Bash, TodoRead, TodoWrite
パイプラインスキル	Read, Write, Glob, Grep, Bash, AskUserQuestion, Task, TaskCreate, TaskList, TaskUpdate, TodoRead, TodoWrite
読み取り専用エージェント	Read, Grep, Glob, TodoRead, TodoWrite
アクションエージェント	Read, Grep, Glob, Write, Bash, TodoRead, TodoWrite

重要なルール：

• Glob（find ではなく）、Grep（grep ではなく）、Read（cat ではなく）を使用します。常に専用ツールを優先してください
• スキルでは allowed-tools:、エージェントでは tools: を使用します
• 指示で実際に参照するツールのみを列挙します
• 読み取り専用のコンポーネントに Write または Bash を含めてはいけません

退けるべき合理化

ワークフロースキルを設計する際は、次のような近道を避けてください。

合理化	誤りである理由
「次のフェーズは見れば分かる」	LLM は文章から順序を推測しません。フェーズに番号を付けてください。
「終了条件は暗黙に分かる」	暗黙の条件は見落とされます。明示的に記述してください。
「SKILL.md を 1 つにまとめたほうがシンプル」	書くのは簡単でも、実行には適しません。500 行を超えると LLM は集中力を失います。
「説明文はそれほど重要ではない」	スキルは説明文によって起動されます。説明文が不適切だと、誤って起動されたり、起動されなかったりします。
「Bash ですべてできる」	Bash によるファイル操作は不安定です。専用ツールのほうがエンコーディング、権限、書式設定を適切に扱えます。
「LLM が適切なツールを判断してくれる」	判断を誤ります。各操作にどのツールを使うか、正確に指定してください。
「詳細は後で追加すればいい」	不完全なスキルは不完全なままリリースされます。執筆前に設計を完成させてください。

リファレンス一覧

ファイル	内容
workflow-patterns.md	構造の骨組みと例を含む5つのパターン
anti-patterns.md	修正前と修正後の例を含む20のアンチパターン
tool-assignment-guide.md	ツール選択マトリックス、コンポーネントの比較、サブエージェントのガイダンス
progressive-disclosure-guide.md	コンテンツの分割ルール、500行ルール、サイズのガイドライン

ワークフロー	目的
design-a-workflow-skill.md	スコープ設定から自己レビューまでの6フェーズの作成プロセス
review-checklist.md	提出準備が整っているか確認するための、構造化された自己レビューチェックリスト

成功基準

適切に設計されたワークフロースキルは、次の条件を満たします。

• 「使用する場合」と「使用しない場合」のセクションがある
• 認識しやすいパターン（ルーティング、パイプライン、リニア、安全ゲート、またはタスク駆動型）を使用している
• すべてのフェーズに番号を付け、開始条件と終了条件を定めている
• 実際に使用するツールのみを記載している（最小権限）
• SKILL.mdを500行未満に抑え、詳細はreferences/workflowsに記載している
• ハードコードされたパスがない（{baseDir}を使用している）
• ファイル参照切れがない
• 参照の連鎖がない（すべてのリンクがSKILL.mdから1ホップで到達できる）
• ワークフローの最後に検証ステップがある
• 説明が適切にトリガーされる（第三者視点で、具体的なキーワードを含む）
• 重要な指示に具体例が含まれている
• 重要な原則について、WHATだけでなくWHYも説明している