normalize-skill-for-claude

すべての推奨事項は、好みではなく、Claude Code の実行時の動作に基づいて根拠を示す必要があります。

譲れないルール：

1. 計画や書き換えを行う前に、references/claude-skill-runtime.md を読んでください。
2. ユーザーが今すぐ書き換えるよう明示的に依頼しない限り、デフォルトで --mode plan を使用してください。
3. フロントマターは最も効果の大きい要素として扱ってください。Claude はまずメタデータに基づいてスキルのルーティングと予算配分を行います。
4. SKILL.md はワークフローに焦点を絞ってください。大きな例、フレームワークのバリエーション、エッジケースの一覧は references/ または scripts/ に移してください。
5. 明確な実行時の理由がない限り、context: fork、paths:、user-invocable: false を追加しないでください。
6. スキルにエージェント専用のフロントマターを追加してはいけません。tools、disallowedTools、skills、initialPrompt、permissionMode、maxTurns、background、memory、isolation、color、mcpServers はスキルではなくエージェントに属します。

Claude 向けにスキルを最適化する

入力

• $target：スキルディレクトリ、または SKILL.md への直接パス
• $mode：省略可能。plan または rewrite。デフォルトは plan

目標

自動呼び出しのしやすさ、プロンプト予算の節約、安全な実行を実現する、Claude Code 向けに最適化されたスキルを作成します。ユーザーが直接書き換えるよう明示的に依頼しない限り、必ず最初にスキルごとの DAG 計画を作成してください。

ステップ 1：対象を特定する

1. スキルディレクトリ、または SKILL.md への直接パスのどちらも受け付けます。
2. スキルのルートに正規化し、SKILL.md が存在することを確認します。
3. モードを決定します。
   • --mode rewrite は、まず計画を立て、同じ実行内で書き換えまで行います
   • モードが指定されていない場合は plan を使用します
4. 現在のスキルを調査します。
   • SKILL.md の行数
   • 既存のフロントマターフィールド
   • references/、scripts/、assets/ がすでに存在するか
   • スキルが内部専用か、ユーザーが呼び出せるか

成功基準：スキルの正確なルート、対象モード、現在のファイル構成、書き換えの想定範囲が把握できていること。

ステップ 2：Claude Code のスキル実行時に関する基準資料を読み込む

推奨事項を示す前に、references/claude-skill-runtime.md を最後まで読んでください。

この資料から、次の制約を確認します。

• Claude はまずフロントマターと短い説明に基づいて、スキルの検出予算を割り当てます。
• スキルの本文全体は呼び出し時に読み込まれ、一覧表示時には読み込まれません。
• paths: は、一致するファイルが操作されたときに条件付きスキルを有効にします。
• context: fork はスキルをフォークされたサブエージェントで実行するものであり、使用はまれにとどめるべきです。
• allowed-tools は、必要最小限の権限範囲にしてください。
• スキルの書き換えでは、エージェント固有のヘッダーではなく、スキル固有のフロントマターだけを使用してください。

このリポジトリに claude-code-source/ が含まれている場合、特殊なフロントマターを書き換える前に、資料内で指定されている正確なソースファイルを使ってエッジケースを検証してください。

成功基準：計画した変更すべてが、Claude の特定の実行時の動作に基づいて根拠付けられていること。

ステップ 3：現在のスキルを Claude のランタイムに照らして監査する

以下のチェックリストを使って、対象のスキルを評価してください。

1. 説明とトリガーの品質
   • description には、スキルの機能、使用するタイミング、トリガーとなるフレーズの例が記載されていますか？
   • when_to_use が欠けている、または不十分ではありませんか？
2. フロントマターの完全性
   • allowed-tools、arguments、argument-hint、user-invocable、paths、context、agent を指定すると、ランタイムの動作が改善されますか？
   • 削除するか、明示的に使用を避ける必要がある、エージェント専用のヘッダーはありますか？
3. 本文のサイズと構成
   • 本文に中核となるワークフローではなく、参照資料が含まれていませんか？
   • 巨大な例、重複したチェックリスト、または references/ に移すべきフレームワーク固有のセクションはありませんか？
   • 構造的なコンテンツの監査：スキルに、ルーティングテーブル（タスク→参照資料の対応表）、パーソナリティ／専門知識の定義、番号付きルールセット、またはゲートの分類が含まれていますか？これらはシグナル性の高いインラインコンテンツであり、大量の例ではありません。それぞれに PRESERVE-INLINE または EXTRACT-WITH-MANDATORY-LOAD のタグを付けてください。
4. 呼び出しの種類
   • これは公開スラッシュコマンド、内部ルーター、条件付きのパススコープヘルパーのどれですか？
5. 実行モデル
   • context: fork は役立ちますか？それとも作業が分断され、フローの途中でユーザーとのやり取りが必要になりますか？
6. 決定性を高める機会
   • 繰り返し使われるシェルスニペットや、壊れやすい変換処理のうち、scripts/ に移すべきものはありますか？

各問題を次のように分類してください。

• ROUTING：メタデータが弱く、自動呼び出しに適さない
• PROMPT：本文が長すぎる、または冗長である
• SAFETY：ツールのスコープまたは実行モードが広すぎる
• STRUCTURE：参照資料またはスクリプトを抽出すべきである

成功基準：ソースに基づく具体的な監査結果を示し、変更が必要な点とその理由を明確にすること。

ステップ 4：スキルごとの DAG 計画を作成する

次の両方の成果物を作成してください。

• .ulpi/plans/skills/<skill-name>-normalize-for-claude.md
• .ulpi/plans/skills/<skill-name>-normalize-for-claude.json

計画には、次の項目を含めてください。

1. 現在の状態
   • 行数
   • 既存のフロントマター
   • 現在のフォルダー
   • 最も大きな肥大化要因
2. Claude ランタイムの調査結果
   • 各調査結果を references/claude-skill-runtime.md の参照箇所に対応付ける
3. 目標の状態
   • 最終的なフロントマターの構成
   • 維持、書き換え、作成、または分割するファイル
4. DAG タスク
   • フロントマターの書き換え
   • 本文の圧縮
   • 参照資料の抽出
   • 任意のスクリプト抽出
   • 検証
5. ガードレール
   • 変更してはならないもの
   • 自動化しすぎてはならないもの
6. 検証
   • スキルの構造が適切であることを確認する具体的なコマンドまたはチェック

各 DAG タスクには、次の項目を含めてください。

• id
• title
• rationale
• filesToModify
• filesToCreate
• dependencies
• validation

成功基準：Markdown と JSON の計画に同じ作業が記載されており、安全に実行できること。

ステップ 5：依頼された場合にのみ書き換える

モードが plan の場合は、DAG の成果物を書き終えた時点で停止します。

モードが rewrite の場合：

1. まずフロントマターを書き換えます。
2. 本文は次の内容に絞ります。
   • 入力
   • 目標
   • ワークフローの手順
   • ガードレール
   • 出力契約
3. 大量の内容は references/ に移しますが、内容の分類に従ってください。
   • 大量の内容（references に移動）：巨大な例、フレームワークのバリエーション、エッジケースの一覧、詳細なチェックリスト、変更前後のコード例
   • 構造上重要な内容（インラインに残すか、必須の読み込み指示を付けて抽出）：ルーティングテーブル（タスク→リファレンスの対応表）、EXTREMELY-IMPORTANT 内の番号付きガードレールルール、ゲートの分類（BLOCK/CONCERN/OBSERVATION）、パーソナリティ／専門知識に関するセクション
   • タスクの種類とリファレンスファイルを対応付けるルーティングテーブルは、必ずインラインに残してください。これはスキルの主要なナビゲーション手段です。
   • 具体的なガードレール一覧（番号付きルール、必ず行うこと／決して行わないこと）は、EXTREMELY-IMPORTANT ブロック内に残すか、必要な手順に必須の読み込み指示を追加してください。「references を参照してください」といった任意の提案にしてはいけません。
   • パーソナリティ／専門知識をリファレンスファイルに抽出する場合は、「References の読み込み時期」に記載するだけでなく、セッション開始時に必須の読み込み指示を追加してください。
4. 決定論的な処理の繰り返しが明らかに妥当な場合に限り、scripts/ を作成します。
5. 今後の編集が容易になるよう、最終的な SKILL.md は簡潔に保ちます。

推奨される書き換え結果：

• description と when_to_use は、トリガーを明確にした内容にする
• 内部ルーターのスキルは user-invocable: false にする
• ファイル変更に応じた有効化が明らかに役立つ場合に限り、ドメインスキルに paths: を追加する
• context: fork は、自己完結した分析／調査ワークフローに限って使用する
• 書き換えたスキルに、エージェント専用のヘッダーを新たに追加しない

成功基準：構造がより簡潔で、ルーティングが明確になり、Claude の実行時の挙動に即したものになっていること。

ステップ 6：結果を検証する

計画または書き換えの後、次の項目を確認します。

1. 最終的な SKILL.md を読み直します。
2. 本文の内容がリファレンスファイルと重複していないことを確認します。
3. フロントマターのフィールドが意図的に選ばれており、慣例の模倣で追加されていないことを確認します。
4. エージェント専用のヘッダーが新たに追加されていないことを確認します。
5. references/ 内のすべてのファイルが SKILL.md から直接リンクされていることを確認します。
6. ルーティングテーブル、番号付きガードレールルール、ゲートの分類が、代替となる内容なしに削除されていないことを確認します。
7. 計画または書き換えの要約に、主要な判断の根拠となった Claude のソースアンカーが記載されていることを確認します。

成功基準：人間または後続のエージェントが、推測することなくすぐに利用できる出力であること。

出力契約

常に次の項目を報告します。

1. Skill: 対象パスと正規化されたルート
2. Mode: plan または rewrite
3. Top runtime issues: Claude との不一致のうち、特に重要なもの
4. Artifacts: 計画または書き換えたファイルの正確なパス
5. Guardrails applied: Claude の実行時の挙動に関連する箇条書き 3～5 項目

rewrite モードを使用した場合は、さらに次の項目も報告します。

• references/ に移動したセクション
• 追加、削除、または意図的に省略したフロントマターのフィールド