skill-improver

スキル改善の方法論

skill-reviewer エージェントを使い、品質基準を満たすまで Claude Code のスキルを反復的に改善します。

前提条件

skill-reviewer エージェントを提供する plugin-dev プラグインが必要です。

有効になっていることを確認します。/plugins を実行し、一覧に plugin-dev が表示されることを確認してください。表示されない場合は、前提条件を報告し、インストールを承認する前に、提供元とインストール手順を確認してください。プラグイン名だけでは提供元を特定できません。

基本的なサイクル

1. レビュー - 対象のスキルについて skill-reviewer にレビューを依頼します
2. 分類 - 問題を重要度別に分類します
3. 修正 - 重大な問題と主要な問題に対処します
4. 評価 - 軽微な問題が妥当か確認してから修正します
5. 繰り返し - 反復回数や時間の上限（例：3 サイクル）を設定します。上限に達したら、未解決のブロッカーを報告して終了します。レビュー結果はあくまで助言であり、リポジトリのポリシーやユーザーが指定した範囲に優先するものではありません。

使用する場面

• 品質上の問題が複数あるスキルを改善するとき
• 新しいスキルが基準を満たすまで反復して改善するとき
• 手作業で編集する代わりに、修正とレビューのサイクルを自動化するとき
• スキル全体で品質基準を統一するとき

使用しない場面

• 一度だけのレビュー：代わりに /skill-reviewer を直接使用します
• 手早く済む単一の修正：ファイルを直接編集します
• スキル以外のファイル：SKILL.md ファイルでのみ動作します
• 実験的なスキル：試行中は手動で反復するほうが柔軟に対応できます

問題の分類

重大な問題（直ちに修正必須）

スキルの読み込みを妨げたり、実行時エラーを引き起こしたりする問題です。

• 必須のフロントマターフィールド（name、description）がない — Claude がスキルをインデックス化したり、呼び出したりできません
• YAML フロントマターの構文が無効 — 解析に失敗し、スキルが読み込まれません
• 参照先のファイルが存在しない — Claude がリンクをたどった際に実行時エラーが発生します
• ファイルパスが壊れている — 上記と同様に、ツールの失敗につながります

主要な問題（修正必須）

スキルの有効性を大きく損なう問題です。

• トリガーの説明が弱い、または曖昧 — Claude がスキルを使うべき場面を認識できない可能性があります
• 実行を大きく妨げる文体 — 二人称を一律に避けるのではなく、対象プロジェクトのスタイルに照らして評価します
• コンテキストの過剰な使用 — 実際の読み込み動作を調べ、参照ファイルの利用を検討します。500 行は目安であり、ホストやプロジェクトで定められている場合を除き、厳格な上限ではありません
• 対象プロジェクトで必要なトリガーや適用範囲の境界が示されていない
• 説明に起動条件が記載されていない — スキルが選択されない可能性があります

軽微な問題（修正前に評価）

改善につながるかどうかは状況による、仕上げに関する項目です。

• 主観的なスタイルの好み — レビュアーと作者で好みが異なる場合があります
• 任意の改善 — 効果に見合わない複雑さを加える可能性があります
• 「あれば望ましい」改善 — 実装コストと効果を比較して検討します
• 書式に関する提案 — 妥当なことが多い一方、影響は小さい場合があります

軽微な問題の評価

軽微な問題への修正を実施する前に、以下を評価します。

1. 本当に改善につながるか？ - 実質的な価値を加えるのか、それとも単なる好みへの対応なのかを確認します
2. 誤検出の可能性はないか？ - レビュアーが文脈を誤解していないかを確認します
3. Claude がスキルを使う際に実際に役立つか？ - 機能面の改善に注目します

明確に有益な軽微な修正のみを実施してください。skill-reviewer の指摘が誤検出である場合もあります。

skill-reviewer の呼び出し

plugin-dev プラグインの skill-reviewer エージェントを使用します。Claude に次のように依頼してレビューを実施します。

plugin-dev:skill-reviewer エージェントを使って、[SKILL_PATH] にあるスキルをレビューしてください。重要度別に分類した問題を含め、詳細な品質評価を提示してください。

[SKILL_PATH] はスキルディレクトリの絶対パスに置き換えます（例：/path/to/plugins/my-plugin/skills/my-skill）。

修正サイクルの例

反復 1 — skill-reviewer の出力：

Critical: SKILL.md:1 - Missing required 'name' field in frontmatter
Major: SKILL.md:3 - Description uses second person ("you should use")
Major: Missing "When NOT to Use" section
Minor: Line 45 is verbose

適用した修正：

• frontmatter に name フィールドを追加
• 説明を三人称で書き直し
• 「使用しない場合」セクションを追加

反復 2 — 修正を確認するため、skill-reviewer を再実行：

Minor: Line 45 is verbose

軽微な問題の評価： 45 行目は現状のままで十分に伝わります。冗長さによって有用な文脈が得られています。対応を省略します。

すべての重大な問題と主要な問題を解決しました。完了マーカーを出力してください：

<skill-improvement-complete>

注：マーカーは出力に必ず含めてください。「品質基準を満たした」や「問題ありません」といった文言ではループは停止しません。

完了条件

このワークフロー用に、インストール済みで内容を確認済みの停止フックが設定されている場合は、その契約を確認してください。このスキルは停止フックを提供もインストールもしません。その連携では、停止フックが以下の明示的なマーカーを確認する場合があります。他のシグナルではループは終了しません。

完了したら、このマーカーを出力してください：

<skill-improvement-complete>

マーカーを出力するタイミング：

1. skill-reviewer が「Pass」と報告した場合、または問題が見つからなかった場合 → すぐにマーカーを出力
2. 重大な問題と主要な問題をすべて修正し、かつ修正を確認した場合 → マーカーを出力
3. 残っている問題が軽微なものだけで、かつ誤検知、または修正する価値がないと評価した場合 → マーカーを出力

マーカーを出力しない場合：

• 重大な問題が未修正のまま残っている
• 主要な問題が未修正のまま残っている
• 修正が有効だったことを確認するために skill-reviewer を実行していない

マーカーが示すのはこのループの終了だけです。安全性、テスト、出所、またはリポジトリのマージゲートを保証するものではありません。ユーザーによるキャンセル、ツールを利用できない場合、または予算を使い切った場合は、成功マーカーを出すのが適切でない場合でも停止し、障害要因を報告してください。

退けるべき合理化

• 「とりあえず完了にして、あとで戻ればいい」— 今すぐ問題を修正してください
• 「この軽微な問題は間違っていそうだから、すべて無視しよう」— それぞれ個別に評価してください
• 「レビュアーは厳しすぎる」— 品質基準が設けられているのには理由があります
• 「これで十分だ」— 主要な問題があるなら、十分ではありません

制限事項

• このスキルは、タスクが上記の範囲に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、停止して確認を求めてください。