スキル改善方法論

skill-reviewer エージェントを使用して Claude Code スキルを繰り返し改善し、品質基準を満たすまで実行します。

前提条件

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

有効になっているか確認します: /plugins を実行してください — plugin-dev がリストに表示されるはずです。ない場合は、Trail of Bits プラグインリポジトリからインストールしてください。

コアループ

1. レビュー - 対象スキルに対して skill-reviewer を呼び出す
2. 分類 - 問題を重大度別に分析する
3. 修正 - 重大度が高い問題と重大な問題に対応する
4. 評価 - 軽微な問題の妥当性を修正前に確認する
5. 繰り返し - 品質基準を満たすまで続ける

使用する場合

• 複数の品質問題を持つスキルを改善する場合
• 新しいスキルを基準を満たすまで反復する場合
• 手動編集の代わりに自動修正レビューサイクルを行う場合
• スキル全体で一貫した品質を強制する場合

使用しない場合

• ワンタイム レビュー: /skill-reviewer を直接使用してください
• 簡単な単一の修正: ファイルを直接編集してください
• スキル以外のファイル: SKILL.md ファイルでのみ動作します
• 実験的スキル: 探索中はより細かい制御のために手動反復を使用します

問題分類

重大な問題 (直ちに修正が必須)

これらはスキルの読み込みをブロックするか、ランタイム障害の原因となります:

• 必須フロントマター フィールド (name, description) の欠落 — Claude がスキルをインデックス化またはトリガーできません
• 無効な YAML フロントマター構文 — 解析に失敗し、スキルが読み込まれません
• 存在しない参照ファイル — Claude がリンクをたどるときにランタイム エラーが発生します
• 破損したファイルパス — 上記と同じで、ツール障害につながります

重大な問題 (修正が必須)

これらはスキルの効果を大幅に低下させます:

• 弱い、またはあいまいなトリガー説明 — Claude がスキルを使用する時期を認識しない可能性があります
• 間違った文体 (命令形の代わりに「you」という二人称) — Claude の実行モデルと矛盾しています
• SKILL.md が 500 行を超え、references/ を使用していない — コンテキストをオーバーロードし、理解度を低下させます
• 「いつ使用するか」または「いつ使用しないか」セクションの欠落 — プロジェクト品質基準で必須です
• トリガーする時期を指定していない説明 — スキルが選択されない可能性があります

軽微な問題 (修正前に評価)

これらはポーランド項目で、スキルを改善する場合とそうでない場合があります:

• 主観的なスタイル好み — レビュアーが著者と異なる好みを持つ可能性があります
• オプションの拡張機能 — 比例した価値なしに複雑さを追加する場合があります
• 「あったら良い」改善 — 実装前に費用対効果を検討してください
• フォーマット提案 — しばしば有効ですが影響は低いです

軽微な問題の評価

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

1. これは本当の改善か？ — 実際の価値を追加していますか、それとも単なる好みを満たしていますか？
2. これは誤検知の可能性はありますか？ — レビュアーがコンテキストを誤解していませんか？
3. これは Claude がスキルを使用するのに実際に役立ちますか？ — 機能的な改善に焦点を当てます

明らかに有益な軽微な修正のみを実装してください。Skill-reviewer は誤検知を生成する可能性があります。

skill-reviewer の呼び出し

plugin-dev プラグインから skill-reviewer エージェントを使用します。Claude に以下を要求することでレビューをリクエストします:

Review the skill at [SKILL_PATH] using the plugin-dev:skill-reviewer agent. Provide a detailed quality assessment with issues categorized by severity.

[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

適用された修正:

• フロントマターに name フィールドを追加
• 説明を三人称で書き直し
• 「いつ使用しないか」セクションを追加

イテレーション 2 — 修正を検証するために skill-reviewer を再度実行:

Minor: Line 45 is verbose

軽微な問題の評価: 45 行目は現状のままで効果的に伝わっています。冗長性は有用なコンテキストを提供します。スキップします。

すべての重大および重大な問題が解決されました。完了マーカーを出力します:

<skill-improvement-complete>

注: マーカーが出力に表示される必要があります。「品質基準を満たしている」または「見た目が良い」のようなステートメントはループを停止しません。

完了基準

重要: 停止フックは以下の明示的なマーカーのみをチェックします。他の信号ではループは終了しません。

完了時にこのマーカーを出力します:

<skill-improvement-complete>

マーカーを出力する場合:

1. skill-reviewer が「Pass」を報告する または 問題が見つからない → 直ちにマーカーを出力します
2. すべての重大および重大な問題が修正されている AND 修正を検証した → マーカーを出力します
3. 残りの問題が軽微なものだけである AND それらを誤検知または修正の価値がないと評価した → マーカーを出力します

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

• 重大な問題が修正されずに残っている
• 重大な問題が修正されずに残っている
• 修正が機能したことを確認するために skill-reviewer を実行していない

マーカーはループを完了するための唯一の方法です。「見た目が良い」または「品質基準を満たしている」のような自然言語ではループを停止しません。

却下すべき正当化

• 「完了とマークして、後で戻ってくればいい」 - 問題を今すぐ修正してください
• 「この軽微な問題は間違っているように見えるので、すべてをスキップします」 - 各問題を個別に評価してください
• 「レビュアーが厳しすぎます」 - 品質基準が存在するには理由があります
• 「十分に良いです」 - 重大な問題がある場合、十分ではありません