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

信頼性の高いワークフロースキルを構築するために、文章ではなく構造パターンに従う。

必須原則

<essential_principles>

<principle name="description-is-the-trigger"> **`description` フィールドが、スキルをアクティベートするかどうかを決める唯一の要素です。**

Claude はスキルの frontmatter description だけに基づいて、そのスキルを読み込むかどうかを判断します。SKILL.md の本文 — 「When to Use」や「When NOT to Use」セクションを含む — は、スキルが既にアクティブになった後でのみ読まれます。トリガーキーワード、ユースケース、除外項目を description に含めてください。悪い description は、本文に何が書いてあっても、誤ったアクティベーションや見落とされたアクティベーションを招きます。

「When to Use」と「When NOT to Use」セクションはまだ目的を果たします。それらはアクティブになった後の LLM の動作をスコープします。「When NOT to Use」では具体的な代替案を名前で挙げてください。「Semgrep を使う」のように「not for simple tasks」ではなく「簡単なパターンマッチングの場合は Semgrep を使う」と書いてください。 </principle>

<principle name="numbered-phases"> **フェーズは入入出出基準を含めて番号を付ける必要があります。**

番号付けなしの文章指示は実行順序の信頼性を欠きます。各フェーズには以下が必要です：

• 番号付け（Phase 1, Phase 2, ...）
• 入開始基準（開始前に何が真である必要があるか）
• 番号付けアクション（何をするか）
• 終了基準（完了をどのように知るか） </principle>

<principle name="tools-match-executor"> **ツールは実行エンティティと一致する必要があります。**

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

ほとんどのスキルとエージェントは、ツールリストに TodoRead と TodoWrite を含める必要があります — これらはマルチステップ実行中の進捗追跡を可能にし、タスクを明示的に管理しないスキルでも役立ちます。 </principle>

<principle name="progressive-disclosure"> **段階的開示は構造的であり、オプションではありません。**

SKILL.md は 500 行以下に留まります。これには、LLM がすべての呼び出しで必要とするもののみが含まれます：原則、ルーティング、クイックリファレンス、リンク。詳細なパターンは references/ に。ステップバイステップのプロセスは workflows/ に。1 段階深さ — 参照チェーンなし。 </principle>

<principle name="scalable-tool-patterns"> **指示はランタイムでスケールするツール呼び出しパターンを生成する必要があります。**

すべてのワークフロー指示はランタイムでツール呼び出しになります。ワークフローが N 個のファイルで M 個のパターンを検索する場合、N×M 呼び出しではなく 1 つの正規表現に統合してください。ワークフローがアイテムごとにサブエージェントをスポーンする場合、ファイルごとに 1 つのサブエージェントではなくバッチ処理を使用してください。10,000 ファイルテストを適用してください：大規模リポジトリに対してワークフローをメンタルで実行し、ツール呼び出し数が制限されたままであることを確認します。anti-patterns.md の AP-18 と AP-19 を参照してください。 </principle>

<principle name="degrees-of-freedom"> **指示の具体性をタスクの脆弱性に合わせる。**

すべてのステップが同じレベルの指定を必要とするわけではありません。ステップごとにキャリブレーションしてください：

• 自由度低（正確なコマンド、バリエーションなし）：脆弱な操作 — データベースマイグレーション、暗号、破壊的アクション。「このスクリプトを正確に実行する」
• 自由度中（パラメータ付きの疑似コード）：バリエーションが許容される推奨パターン。「このテンプレートを使用してカスタマイズする」
• 自由度高（ヒューリスティックと判断）：可変タスク — コードレビュー、探索、ドキュメント。「構造を分析し、改善を提案する」

スキルは自由度レベルを混在させることができます。セキュリティ監査スキルは、発見フェーズで高い自由度（「認証パターンのコードベースを探索する」）を使用し、レポートフェーズで低い自由度（「このセキュリティレベル分類表を正確に使用する」）を使用する場合があります。 </principle>

</essential_principles>

使用する場合

• マルチステップワークフローまたはフェーズ実行を含む新しいスキルを設計している
• 複数の独立したタスク間でルーティングするスキルを作成している
• 安全ゲート（確認が必要な破壊的アクション）を使用するスキルを構築している
• サブエージェントまたはタスク追跡を使用するスキルを構築している
• 既存のワークフロースキルを品質のために確認または再ファクタリングしている
• SKILL.md、references/、workflows/ の間でコンテンツを分割する方法を決定している

使用しない場合

• ワークフローなしの単純な単一目的スキル（ガイダンスのみ）— SKILL.md を直接書く
• スキルの実際のドメインコンテンツを書く（これは構造を教える、ドメイン専門知識ではない）
• プラグイン構成（plugin.json、フック、コマンド）— プラグイン開発ガイドを使用する
• スキル以外の Claude Code 開発 — これは特にスキルアーキテクチャ用です

パターン選択

スキルの構造に適したパターンを選択してください。workflow-patterns.md で完全なパターン説明を読んでください。

スキルには何個の異なるパスがありますか？
|
+-- 1 つのパス、常に同じ
|   +-- 破壊的なアクションを実行しますか？
|       +-- はい -> Safety Gate Pattern
|       +-- いいえ  -> Linear Progression Pattern
|
+-- 共有設定からの複数の独立したパス
|   +-- Routing Pattern
|
+-- 複数の依存するステップが順序で
    +-- ステップは複雑な依存関係がありますか？
        +-- はい -> Task-Driven Pattern
        +-- いいえ  -> Sequential Pipeline Pattern

パターンサマリー

パターン	使用する場合	主な特徴
Routing	共有インテークからの複数の独立したタスク	ルーティングテーブルが意図をワークフローファイルにマップ
Sequential Pipeline	依存ステップ、各ステップが次のステップに供給	自動検出は部分的な進捗から再開できます
Linear Progression	単一パス、常に同じ	入出基準付き番号付きフェーズ
Safety Gate	破壊的/不可逆的アクション	実行前に 2 つの確認ゲート
Task-Driven	複雑な依存関係、部分的な失敗許容度	TaskCreate/TaskUpdate 依存関係追跡

構造的解剖

すべてのワークフロースキルはパターンに関係なく、このスケルトンが必要です：

---
name: kebab-case-name
description: "第三者視点の説明、トリガーキーワード付き — これが Claude がスキルをアクティベートする決定を下す方法"
allowed-tools: Tool1 Tool2 Tool3  # スペース区切りのツール名リスト
# オプションフィールド — tool-assignment-guide.md で完全なリファレンスを参照：
# disable-model-invocation: true    # ユーザーのみ起動可（Claude ではない）
# user-invocable: false             # Claude のみ起動可（/ メニューから非表示）
# context: fork                     # 分離されたサブエージェントコンテキストで実行
# agent: Explore                    # サブエージェントタイプ（context: fork が必要）
# model: [model-name]               # スキルアクティブ時にモデルを切り替え
# argument-hint: "[filename]"       # オートコンプリート中に表示されるヒント
---

# タイトル

## 必須原則
[WHY 説明付き 3～5 個の譲歩不可のルール]

## 使用する場合
[4～6 個の具体的なシナリオ — アクティベーション後の動作をスコープ]

## 使用しない場合
[3～5 個のシナリオ、名前付き代替案 — アクティベーション後の動作をスコープ]

## [パターン固有セクション]
[ルーティングテーブル / パイプラインステップ / フェーズリスト / ゲート]

## クイックリファレンス
[頻繁に必要な情報用コンパクトテーブル]

## リファレンスインデックス
[すべてのサポートファイルへのリンク]

## 成功基準
[出力検証用チェックリスト]

スキルは 3 種類の文字列置換をサポートします：引数とセッション ID 用のドル接頭変数、シェル前処理用の感嘆符バッティック構文。スキルローダーは Claude がファイルを見る前にこれらを処理します — コードフェンスの内側でも — ので、ドキュメントテキストで生の構文を使用しないでください。tool-assignment-guide.md で完全な変数リファレンスと使用ガイダンスを参照してください。

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

最も一般的な間違い。修正前後の完全なカタログは anti-patterns.md を参照してください。

AP	アンチパターン	ワンラインフィックス
AP-1	ゴール/アンチゴールを指定していない	When to Use AND When NOT to Use セクションを追加
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	根拠がない	監査スキルに「Rationalizations to Reject」を追加
AP-17	具体例がない	キー指示の入出力を表示
AP-18	直積ツール呼び出し	パターンを単一正規表現に統合、1 回 grep、フィルタ
AP-19	無制限のサブエージェントスポーン	アイテムをグループにバッチ、バッチあたり 1 サブエージェント
AP-20	Description がワークフローを要約	Description = トリガー条件のみ、ワークフローステップではない

AP-10（No Default/Fallback Route）、AP-14（Missing Tool Justification in Agents）、AP-20（Description Summarizes Workflow）は完全なカタログにあります。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 は文章から順序を推論しません。フェーズに番号を付けてください。
「終了基準は含まれている」	含まれた基準はスキップされた基準です。明示的に書いてください。
「1 つの大きな SKILL.md はシンプルだ」	書くのはシンプル、実行は悪い。LLM は 500 行を超えると焦点を失う。
「Description はそこまで重要ではない」	Description がスキルをトリガーする方法です。悪い description は誤ったアクティベーションを招きます。
「Bash はすべてできる」	Bash ファイル操作は脆弱です。専用ツールはエンコーディング、パーミッション、フォーマットを better に処理します。
「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	提出準備のための構造化された自己確認チェックリスト

成功基準

よく設計されたワークフロースキルは：

• When to Use AND When NOT to Use セクションがある
• 認識可能なパターン（ルーティング、パイプライン、線形、安全ゲート、またはタスク駆動）を使用
• 入出基準付きすべてのフェーズに番号を付けている
• 実際に使用するツールのみをリスト（最小権限）
• SKILL.md は 500 行以下、詳細は references/workflows に
• ハードコードされたパス（{baseDir} を使用）がない
• 破損したファイル参照がない
• 参照チェーン（SKILL.md からすべて 1 ホップ）がない
• ワークフロー終了に検証ステップがある
• Description は正しくトリガー（第三者視点、具体的キーワード）
• キー指示に具体例がある
• 必須原則で HOW ではなく WHY を説明