repair-skill

スキルの修復

ゴールドスタンダードに照らして、既存のスキルを監査し、改善します。ゼロから生成する create-skill とは異なり、このスキルでは違反を診断するだけでなく、何が壊れているか、何が不足しているか、品質を高めるには何が必要かを特定します。すべての項目を網羅した、構造化された改善計画を出力します。

フェーズ 1：スキルを読み込む

$ARGUMENTS を、スキルディレクトリまたは SKILL.md ファイルへのパスとして読み込みます。

• ディレクトリの場合：SKILL.md を読み込み、references/、examples/、scripts/、assets/ のうち存在するものと、SKILL.md から参照されているものを一覧にして記録します
• ファイルの場合：ファイルを直接読み込み、同階層のリソースディレクトリを確認します

パスが存在しない、または曖昧な場合は、先に AskUserQuestion を使って確認してください。

フェーズ 2 の前に、以下の 3 つの参照ファイルをすべて読み込んでください。

1. ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/skill-anatomy.md — 正しい構成、3 段階の読み込みモデル、ディレクトリの種類の定義、自由度、命名規則、本文の規則に関するゴールドスタンダードです。次元 5、6、7 に必要です。
2. ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/frontmatter-options.md — frontmatter のフィールド一覧、有効な値、ツール一覧、ツール選択の枠組みです。次元 1 と 2 に必要です。
3. ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/audit-calibration.md — 違反に見えても違反ではない既知のパターンです。D2（allowed-tools がない場合）、D4（Task/Skill に関する説明文）、D5（概要説明と振り分け）の過剰な指摘を防ぎます。

フェーズ 2 に進む条件：SKILL.md を読み込み、同階層のディレクトリを一覧化し、3 つの参照ファイルをすべて読み込んでいること。

フェーズ 2：監査

各次元を個別に評価します。指摘事項ごとに、次元コード、問題または不足の内容、違反している原則または満たしていないゴールドスタンダード、および必要な具体的変更を記録します。7 つすべての次元を評価したら、フェーズ 3 に進みます。

指摘の種類：

• 違反 — 存在する内容がルールに反している
• 不足 — 存在しないが、ゴールドスタンダードに照らしてスキルを改善する内容
• 改善 — 機能しているものの、意味のある改善が可能な内容

重大度：

• critical — トリガーを妨げる、または呼び出しのたびに大量のコンテキストを無駄にする
• major — 汎用性、信頼性、ワークフローの正確性を損なう
• minor — 仕上げの問題。スキルは機能するものの、さらに改善できる

ディメンション 1 — フロントマターの品質

説明は、常にコンテキストに含まれるスキルの唯一の部分です。ここで使うトークンは、すべてのセッションで予算を消費します。違反と不足の両方を確認してください。

違反:

• 人称と表現: 説明は三人称（「このスキルは、〜の場合に使用します」）になっていますか？　一人称や命令形の表現は、評価すべきトリガー条件ではなく、実行するための指示として受け取られます。誤っている場合は重大です。
• スカラー型: 説明に >（折りたたみスカラー）を使用していますか？　| のリテラルスカラーは改行を保持し、解析時に予期しない空白が生じることがあります。軽微です。
• トリガー句の真正性: 引用されたフレーズは、ユーザーが実際に入力するそのままの言葉ですか？　言い換え（「フック作成タスク」など）は、自然な表現（「フックを作成して」など）よりもルーティングの一致率が低くなります。言い換えられている場合は重大です。
• トークン密度: 説明でスキル名を繰り返したり、スキルとは何かを説明したり、メタコメントを含めたりしていませんか？　このようなトークンはすべて予算の無駄です。個々の場合は軽微ですが、全体に及ぶ場合は重大です。

不足:

• トリガー句の網羅性: 多様なフレーズが3〜5個以上ありますか？　フレーズが1つだけでは、同義語の範囲をカバーできません。このスキルについて聞いたことがないユーザーが使いそうな、素朴な表現も含まれていますか？　網羅性が乏しい場合は重大です。
• argument-hint の欠落: スキルが $ARGUMENTS または $1／$2 を読み取るのに、argument-hint フィールドがありませんか？　このヒントはオートコンプリートに表示されるため、ないとユーザーは何を渡せばよいかわかりません。軽微です。
• 名前の妥当性: スキル名は小文字で、ハイフンのみを使い、最大64文字になっていますか？　コマンドの場合は動詞で始まっていますか？　ルーティングの明確さに役立つ場合は、名前空間を付けていますか？　これらの制約により、ファイルシステムとの互換性、コマンドラインの使いやすさ、明確なルーティングを確保できます。誤っている場合は軽微です。
• トリガーの正確さ: このスキルをトリガーすべきプロンプトを3つ、隣接する領域からトリガーすべきでないプロンプトを3つ、頭の中で作ってみてください。説明はトリガーすべき内容を網羅し、トリガーすべきでない内容を除外していますか？　網羅性の不足や、誤ってトリガーされる範囲の広さは、ルーティング品質の不足です。網羅性が乏しい場合は重大です。
• トークン予算: 説明が100トークンを超えていませんか？　インストール済みのすべてのスキルについて、説明の長さに応じてセッションごとのコストが増加します。150トークンを超える場合は違反（重大）で、100〜150トークンの場合は不足（軽微）です。説明を引き締め、文章よりもトリガー句を優先してください。
• 否定トリガーの欠落: 複数のスキルの関心領域が重なる、スキルが密集した領域では、「Xには使用しない」という明示的な除外を説明に含めていますか？　否定トリガーによって、ルーティングの判断境界が明確になります。軽微です。

ディメンション 2 — 実行修飾子

デフォルトのままの修飾子はエラーではありません。デフォルトが適用される場合、省略するのが正しい動作です。不一致（違反）と設定の不足（欠落）を監査してください。

フィールドの全一覧、モデル選択表、ツール選択の枠組みについては、frontmatter-options.mdを参照してください。

違反：

• スコープを絞ったパターン（Bash(git:*)）で対応できるのに、スキルでBashが無制限に許可されていませんか？
• スキルのallowed-toolsに、実際には使われないツールが含まれていませんか？未使用の項目はノイズになります。

不足：

• allowed-toolsにSkillまたはTaskが含まれていないのに、スキルが他のスキルを呼び出したり、エージェントを起動したりしていませんか？

• ワークフローの途中でユーザーの判断が必要なのに、allowed-toolsにAskUserQuestionが含まれていませんか？

• スキルが$1からファイルパスを読み取るのに、インライン注入の@$1ではなく、Readツールを呼び出していませんか？ツール呼び出しの往復が無駄になっています。軽微です。

• ツール呼び出しの代わりに、動的コンテンツ構文（感嘆符＋バッククォートで囲んだコマンド）を使って、リアルタイムデータ（git のステータス、環境変数、ファイルツリー）を注入できませんか？エラー処理が不要な確実なプローブ（git ブランチ、ファイルツリー、環境変数）からワークフローが始まる場合は重大です。失敗する可能性がある、または終了コードによる分岐が必要なコマンドの場合は軽微です。

  変更前（ツール呼び出しの往復が無駄になります）：

  1. Run `git log --oneline -5` using Bash
  2. Run `git diff --name-only` using Bash
  3. Analyze the results...
  

  変更後（呼び出し時に注入され、ツール呼び出しはゼロです）。 以下のように、該当するBash呼び出しを置き換えます。

  • 最近のコミット：!`git log --oneline -5`
  • 変更されたファイル：!`git diff --name-only`

  続けて、「結果を分析してください……」のような文章を記述します。

  注： バックスラッシュはバッククォートをエスケープしているため、このドキュメント内では実行されません。実際のスキルでは、バックスラッシュを付けずに!`cmd`と記述してください。

---

ディメンション 3 — 内包的指示と外延的指示

理由を添えて述べたルールは、あらゆる入力に一般化できます。ルールを暗示するだけの例では、読み手であるモデルがルールを逆算する必要があり、推論の段階が1回ではなく2回になります。また、適用範囲もその例の形に限られます。

違反：

• 良い例と悪い例を対比させ、原則を暗黙のままにしていませんか？まず原則を明示し、対比はそれを補強するものにしてください。原則の代わりにしてはいけません。
• 「よくある間違い」や「悪い例／良い例」のセクションで、本来なら1文の原則で効率よく説明できる内容を扱っていませんか？重大です。
• 例を削除してもルールが成り立ち、引き続き実行可能ですか？そうであれば、例は冗長です。そうでなければ、ルールがまだ明示されていないため、ルールを記述してください。

不足：

• Claudeに何をすべきかだけを伝え、理由を説明していない指示ブロックはありませんか？理由を加えることで、現在の例では網羅されないエッジケースにも指示を一般化できます。該当するブロックごとに重大です。

---

ディメンション 4 — エージェント型と決定論型の分担

このディメンションを監査する前に、${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md を読み込んでください。 ここには、 スクリプト候補を見分けるための5つのシグナルパターン、CLI 設計の慣例、 一般的なアーキタイプ（init、validate、transform、package、query）、および create-cli を使ってインターフェースを設計する委任パターンが記載されています。

スキルには、LLM によるガイド付き推論（エージェント型）とスクリプト実行（決定論型）が混在します。この分担は 意図的に行う必要があります。skill-anatomy.md の自由度テーブルを参照してください。

違反事項：

• 呼び出しのたびに繰り返される、または同一のコードブロック — これらは 毎回再生成されている決定論的な操作です。scripts/ に配置してください。 インラインで記述すると、実行のたびにコンテキストトークンを消費します。スクリプトは読み込まずに実行できます。
• 決定論的な手順を説明する文章 — 入力にかかわらず手順が常に同じなら、 モデルに再現を求めるより、スクリプトのほうが信頼性に優れています。
• 存在するものの SKILL.md から参照されていないスクリプト — Claude はそれを使用しません。 SKILL.md に、いつ、どのように呼び出すかを指定する参照がないスクリプトは、 スキルのワークフローから見えません。重大。
• 曖昧なスクリプト参照 — 「必要に応じて検証スクリプトを実行してください」では、実行可能な指示になりません。 参照では、実行条件、正確な呼び出し方法、出力の解釈方法を明記する必要があります。軽微。

不足事項 — script-patterns.md の5つのシグナルパターンを各ワークフローの手順に適用してください：

• シグナル 1（生成の繰り返し）： ある手順で、呼び出しのたびに異なるパラメーターを使って同じ構造を生成していませんか？→ パラメーター化されたスクリプトの候補。重大。
• シグナル 2（ツール選択の不明確さ）： ある手順で、単一の関数として自然に表現できる処理を実現するために、複数の標準ツールを脆弱な順序で組み合わせる必要がありませんか？→ 手順をスクリプト化します。重大。
• シグナル 3（明確な契約）： ある手順の入出力形式は、今すぐ --help のテキストを書けるほど明確ですか？→ CLI の候補です。設計を create-cli に委任してください。
• シグナル 4（二重用途の可能性）： スキルのワークフロー外で、ターミナルから単独で実行しても役立つ手順がありますか？→ 最初から適切な CLI として設計します。
• シグナル 5（一貫性が重要）： ある手順で、同一の入力に対して「類似」ではなく、再現可能な同一の出力を生成する必要がありますか？→ LLM に生成させず、スクリプトにします。
• 基準のない判断手順 — 「状況を分析してください」はエージェント型ですが、判断の拠り所がありません。エージェント型の手順には、 考慮すべき事項と、望ましい結果の条件を明示する必要があります。基準が示されていない各手順につき重大。

Dimension 5 — 冗長さとコンテキスト効率

スキルが起動すると、SKILL.md のすべてのトークンがコンテキストに読み込まれます。成果の向上につながらず予算を消費するトークンと、代わりに references/ に置くべき内容を監査してください。

深刻度の判断には、skill-anatomy.md のサイズ不変条件テーブルを参照してください。

違反:

• セクション見出しを言い換えただけの文章 — 「## Validation」の後に「この セクションでは検証を行います……」と続けるのは、まったくの冗長です。1 件ごとに軽微。
• 曖昧な表現 — 「検討するとよいでしょう」「役立つ可能性があります」 「一般的に言えば」など。直接的な命令文に置き換えるか、削除してください。1 件ごとに軽微。
• 一文で述べられる原則を説明するコードブロック — 適切な YAML と不適切な YAML の対比は、多くの場合、意図を示す 1 つのルールにまとめられます。パターンが頻出する場合は重大。
• 変数の割り当てを失う形で、コードブロックを文章にまとめる — ワークフロー変数（BASE=...、BRANCH=...）を割り当て、その後の手順で使うコードブロックには、操作を示すことと状態を設定することの 2 つの役割があります。割り当てを保持せずに文章にまとめると、後続の $VAR 参照が未定義になります。まとめる際は、文章内で各変数を明示的に割り当てる「作業用変数の導出」前置きを追加してください。割り当てが失われるごとに重大。
• セクション間で同じ指針を繰り返す — 「ベストプラクティス」セクションと 「よくある間違い」セクションで同じルールを示すなど。1 か所にまとめてください。軽微。
• 本文内の「このスキルを使う場面」セクション — 本文はスキルの起動後にのみ読み込まれます。この中のルーティング指針がルーティング判断で読まれることはありません。呼び出しのたびに無駄なトークンが発生します。重大。
• H3 を超える深さの見出し — references/ に置くべき内容であることを示しています。軽微。
• 約 500 行を超える SKILL.md — references/ への移動が必要です。重大。
• 余分なドキュメントファイル（README.md、CHANGELOG.md、INSTALLATION.md）が スキルディレクトリにある — コンテキストには読み込まれず、パッケージにノイズを加えます。ファイルごとに軽微。

不足:

• references/ ファイルで SKILL.md のサイズを削減できますか？ 特定のサブタスクでしか必要ないセクションを特定し、移動候補として挙げてください。SKILL.md が 300 行を超える場合は重大。
• ドメイン固有データ用の references/ ファイルが役立ちますか？ ルックアップテーブル、オプションカタログ、フィールド定義などは、指示ではなく参照データです。重大。

---

Dimension 6 — ワークフローの明確さ

スキルのプロセスは順序立てて完結しており、各フェーズに明示的な終了条件が必要です。ワークフローの破綻と、役立つ構造の不足の両方を監査してください。

違反:

• プロセスは、明確な名前を付けた番号付きフェーズとして構成されていますか？明示的なフェーズがなければ、モデルは進捗を追跡したり、現在どのステップにいるかを把握したりできません。構成されていない場合は重大。
• 各フェーズに明示的な終了条件がありますか？終了条件がなければ、モデルはフェーズの反復をいつ止めるべきかがわからず、ループしたり、早まって次に進んだりする可能性があります。欠落している場合は重大。
• 考えが途中で止まっているステップはありますか？意図を述べるだけで、何をするのか、結果をどう評価するのかが指定されていないフェーズです。対象となるフェーズごとに重大。
• 入力が欠落している、不明瞭、または不正な形式の場合に対処していますか？

不足:

• 変数の継続性: ステップで参照されるすべての $VAR は、先行ステップまたは事前確認／前置きセクションで明示的に割り当てられていますか？スキル本文にあるすべての $VARNAME トークンを確認し、それぞれの由来を追跡してください。未定義の変数はワークフローの破綻です。エージェントは無効なコマンドで停止するか、気づかれないまま空文字列に置き換えます。未定義の変数ごとに重大。
• Claude が何をどの形式で作成するのかを示す成果物作成フェーズはありますか？多くのスキルはプロセスを明確に説明していても、出力形式は暗黙のままです。欠落している場合は重大。
• ワークフロー末尾の検証チェックリストで、文章による指示では見落としやすいエラーを検出できますか？軽微。
• 期待される出力の例をユーザーが理解するうえで、examples/ ディレクトリが役立ちますか？軽微。

---

ディメンション 7 — 構成要素の完全性

標準的なディレクトリ構成とギャップ分析チェックリストについては、skill-anatomy.md を参照してください。このディメンションでは、スキルの構成が複雑さの段階に合っているか、また、より高い段階に引き上げるために何が欠けているかを確認します。

skill-anatomy.md のギャップ分析チェックリストをそのまま使用してください。 「はい」と回答した項目ごとに、適切な重大度でギャップを記録します。

違反事項：

• スキルに scripts/ ディレクトリがあり、SKILL.md で参照されていないスクリプトが含まれていますか？ 重大 — 参照するか削除します。
• スキルに references/ ディレクトリがあり、SKILL.md から参照されていないファイルが含まれていますか？ 重大 — 参照するか削除します。
• 命名規則に違反していますか（大文字、アンダースコア、64 文字超）？ 軽微。

ギャップ — 存在しない各ディレクトリについて確認します：

• scripts/ がない： スクリプト化すると、より確実に実行できる決定論的な操作はありますか？ 同じコードブロックが複数回の呼び出しで登場していますか、あるいは登場する可能性がありますか？
• references/ がない： SKILL.md は 300 行を超えていますか？ 特定のサブタスクでのみ必要なセクションはありますか？ ドメイン固有の参照データはありますか？
• examples/ がない： スキルはユーザーが調整して使う出力を生成しますか？ 動作する例があれば、文章よりも明確になる曖昧な指示はありますか？
• SKILL.md にリソースへの参照がない： ディレクトリは存在するのに参照されていないため、Claude が見に行くことを推測しない限り認識できないものはありますか？

---

フェーズ 3：改善レポート

調査結果を構造化されたレポートとして提示します。違反事項とギャップを分けてください。違反事項は誤っているもの、ギャップはスキルを改善するために欠けているものです。

SKILL IMPROVEMENT REPORT: <skill-name>
Current tier: [simple / standard / complex] — [lines] lines, [directories present]

VIOLATIONS
──────────
CRITICAL
  [D1] Description uses first-person — routing model reads as instruction, not trigger.
       Fix: rewrite as "This skill should be used when the user asks to..."

MAJOR
  [D3] Body teaches frontmatter quality by bad/good contrast; principle never stated.
       Fix: state the rule ("quoted phrases must be verbatim user speech because routing
       matches on literal tokens") then keep the contrast as confirmation.
  [D5] "When to Use This Skill" section in body — dead tokens every invocation.
       Fix: move routing guidance to frontmatter description, delete body section.

MINOR
  [D1] Description uses | scalar instead of >.
       Fix: change to >.

GAPS (what would improve this skill)
─────────────────────────────────────
MAJOR
  [D7] SKILL.md is 420 lines with no references/ directory. Three sections (option catalog,
       field definitions, examples table) are only needed for specific sub-tasks.
       Improvement: extract to references/; add load pointer in SKILL.md for each.
  [D4] File-path validation logic is inlined but must produce consistent output.
       Improvement: move to scripts/validate-input.py; reference from Phase 2.

MINOR
  [D2] Skill reads $1 as a file path but uses Read tool — @$1 injection would save a
       tool round-trip.
       Improvement: replace Read call with @$1 inline injection.
  [D7] No examples/ directory; skill produces config output users adapt.
       Improvement: add examples/ with one representative output file.

まず重大度ごとに違反事項をまとめ、次に重大度ごとにギャップをまとめます。それぞれについて、ディメンションコード、誤りまたは不足している内容、満たしていない原則または標準、具体的な修正方法を示します。

「重大および重要な項目をすべて適用しますか？ それとも特定の項目を選びますか？」と尋ねます。

---

フェーズ 4：改善の適用

確認された項目を次の順序で適用します：重大な違反事項 → 重要な違反事項 → 重要なギャップ → 軽微な違反事項 → 軽微なギャップ。

各項目について：

• 何を変更または追加するのか、またその理由（「依頼されたから」ではなく、原則を参照）を説明します
• 編集を行うか、ファイルを作成します
• 変更が周囲の内容と一貫していることを確認します

選択理由の説明

改善を適用した後、以下を簡潔に説明します：

• 何を変更し、なぜ変更したか — 原則を参照します：「一人称の表現は、評価対象となるトリガー条件ではなく、実行する指示として解析されるため、説明を三人称に書き換えました」
• 何を追加し、なぜ追加したか — 「SKILL.md が 420 行あり、カタログが設定サブタスクでのみ必要なため、references/options.md を作成してオプションカタログを分離しました」
• 何を変更せず、なぜそのままにしたか — 「ライフサイクルの検証は不要なため、hooks は未設定のままです」
• ユーザーが対応する必要があること — 「examples/ のギャップを埋めるにはドメインの知識が必要なため、プレースホルダーディレクトリを作成しました」

確認されたすべての項目が適用され、説明が行われ、検証チェックリストに合格した時点で、フェーズ 4 は完了です。

---

検証

すべての改善を適用した後、${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/quality-checklist.md を読み込み、品質基準チェックを実行してから、項目ごとの検証チェックリストを実行します。最終結果を提示する前に、不合格の項目があれば報告します。