improve-skill

Skill Improver

ユーザーの意図をモデル化し、その意図に照らしてスキルをメンタルシミュレーションと実際のドキュメント検証でテストし、優先順位を付けた改善案を提示することで、既存のスキルの有効性を高めます。改善案には、新機能、UX の向上、精度の修正、効率化が含まれます。

このスキルが扱うのは、スキルがユーザーに必要なことを実現できるかどうかです。構造上の正しさ（不正なフロントマター、必須フィールドの欠落、規約違反）は repair-skill の担当領域です。明らかな構造上の問題がある場合は、簡潔に指摘して repair-skill を推奨し、有効性の分析を続けてください。

Phase 0: スキルを読み込む

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

• ディレクトリの場合：SKILL.md を読み、references/、scripts/、examples/、assets/ のうち、どれが存在するかを記録します
• ファイルの場合：そのファイルを直接読み、同階層のリソースディレクトリを確認します

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

明らかな構造上の問題があれば、1 文で指摘して（「この説明は一人称です。構造上の修正には repair-skill を推奨します」）、先に進みます。完全な構造監査は行わないでください。

SKILL.md を読み込み、同階層のディレクトリ一覧を記録したら、Phase 0 は完了です。

Phase 1: ユーザーの意図を把握する

分析を始める前に、AskUserQuestion を使ってユーザーの希望を確認します。

• 「このスキルが具体的にうまくできていないのは、どのような点ですか？」
• 選択肢：「気づいている具体的な問題がある」、「よくわからない — 有効性を全面的に監査してほしい」、「問題なく動作するが、新しい機能がほしい」、「ワークフローが使いにくい」

回答にかかわらず、説明と本文からスキルの目的も推測してください。解決する問題と対象ユーザーについての理解を 1 文で述べてから、次に進みます。これにより、分析全体の適切な前提を定めます。

ユーザーが具体的な問題を挙げた場合は、その領域を中心に分析し、同じワークフローの関連箇所も確認します。ユーザーがよくわからない場合は、Phase 2 の 5 つすべての分析を行います。

ユーザーの意図を把握し、スキルの目的を述べたら、Phase 1 は完了です。

Phase 2: 有効性の分析

${CLAUDE_PLUGIN_ROOT}/skills/improve-skill/references/effectiveness-rubric.md を読み込んでから、分析を始めてください。ここには、Phase 3 で使用する重大度の基準、改善の種類の定義、工数と効果の評価基準が記載されています。

5 つすべての分析を行います。それぞれの指摘について、問題点、ユーザーの有効性が低下する理由、具体的な改善策を記録してください。

---

2a — メンタルシミュレーション

Claude がスキルを実行する際の流れを、典型的なユーザーリクエストを使ってたどります。通常のワークフローを実行できる入力を選び、エッジケースは避けてください。

スキルの各フェーズについて、以下を評価します。

• 不足情報：このステップに必要なのに、まだ提示も収集もされていない情報は何ですか？ユーザーが指定しておらず、スキルも質問しない場合、Claude は何を推測しなければなりませんか？
• 分岐点：同じ指示を実行する 2 つの Claude インスタンスが、どの箇所で大きく異なる結果にたどり着く可能性がありますか？これらは指示が不明確な箇所です。
• 行き止まり：スキルのワークフローが終わっても、ユーザーの実際の目標が達成されていない箇所はどこですか？スキルの完了後、ユーザーが手作業で行わなければならないことは何ですか？
• 摩擦：Claude が妥当な既定値を選べるのに、価値の低い判断でユーザーを中断する箇所はどこですか？反対に、ユーザーに強い希望があるのに、必要な入力を求めていない箇所はどこですか？

指摘事項を種類別に記録します。停滞点、分岐点、行き止まり、摩擦点に分類してください。

---

2b — ドキュメントのリアルタイム検証

スキル内にある、外部標準に関するすべての事実上の主張を特定します。対象には、フロントマターのフィールド名、Claude のツール名と動作、API パラメーター、CLI フラグ、サードパーティサービスのインターフェースが含まれます。

各主張を、最新のドキュメントで検証します。

For Claude-specific claims (frontmatter options, tool names, model IDs):
  Use Task tool with subagent_type=claude-code-guide — faster and more accurate than WebSearch.

For third-party claims (npm packages, APIs, external CLIs):
  Use WebSearch or WebFetch against official documentation.

スキルの記述と現状との相違を報告します。重要度は、主張によって出力が壊れる場合は高、古いガイダンスになる場合は中、動作に違いがなく名称だけが変わっている場合は低とします。

---

2c — 関連機能のスキャン

スキルの目的を踏まえ、欠けているものの、付加価値の高い機能を特定します。

• 隣接機能：スキルがすでに行っていることを自然に拡張する機能です。同じ領域をもう一歩進めるもので、このスキルを実行したユーザーが、その次にほぼ確実に求めるものです。
• 補完機能：このスキルの直前または直後によく必要になる機能です。ユーザーは現在、これを手作業で行っています。
• エンドツーエンドのギャップ：スキルが作業を開始するものの、ユーザーが手作業で完了させている状態です。ユーザーが「計画を提示して」だけでなく「それを適用して」まで望んでいるのに、ワークフローが「計画はこちらです」で止まっています。

候補ごとに、実装にかかる労力（指示の変更 1 件、新しいフェーズ、または新しいスクリプト）とユーザーにとっての価値（まれなエッジケース、よくあるシナリオ、または重要なシナリオでスキルを妨げる要因）を見積もります。

---

2d — UX フローのレビュー

スキルのインタラクション設計を評価します。

• スキルは必要な質問をすべて最初に提示していますか（本格的な作業に入る前に）？ それとも、ユーザーが予期していなかった質問でワークフローの途中に割り込んでいますか？
• 「わからない」場合の手順は明確ですか？ ユーザーが具体的な不満を持たずにスキルを起動した場合、スキルは適切に対応しますか、それともユーザーが把握していることを前提にしていますか？
• 出力形式は、ユーザーの利用方法に合っていますか？ 一度だけ読むレポートなら密度の高い文章でも構いませんが、繰り返し適用するものなら、より構造化する必要があります。
• ユーザーの入力なしに、スキルが重大な判断を下すステップはありますか？

---

2e — エッジケースのストレステスト

メインパス（2a）を確認した後、意図的にスキルが失敗する状況を試します。失敗モードを検証する敵対的な入力を 3～5 件特定します。

• 入力の欠落または不正な形式：必要なファイルが存在しない、パスが間違っている、引数が空または破損している場合、どうなりますか？
• 要件の矛盾：ユーザーが述べた目的と入力が食い違う場合（例：スキルではないファイルに対して「このスキルを改善して」と依頼された場合）はどうなりますか？
• 未対応の構成：スキルが想定していない構成に遭遇した場合（異なるフレームワークのバージョン、特殊なプロジェクトレイアウト、想定外のファイル形式など）はどうなりますか？
• 境界条件：入力が非常に大きい（500 行の SKILL.md）、非常に小さい（空のファイル）、またはパスや名前に特殊な文字が含まれている場合はどうなりますか？

敵対的な入力ごとに、スキルが問題を検出して有用なエラーを提示するか、気づかずに誤った出力を生成するか、ワークフローがクラッシュするかを評価します。調査結果を改善の種類に分類します。エラー処理の欠如 → 新機能、わかりにくいエラーメッセージ → UX 改善、検出されない不正な状態 → 正確性の修正。

すべてのサブ分析が完了し、調査結果が記録された時点で、フェーズ 2 は完了です。

フェーズ 3：改善案の提示

レポートを作成する前に、出力形式として ${CLAUDE_PLUGIN_ROOT}/skills/improve-skill/references/effectiveness-report-template.md を読み込みます。必要に応じて、深さと具体性の目安として ${CLAUDE_PLUGIN_ROOT}/skills/improve-skill/examples/sample-analysis.md を参照します。

ユーザーは監査の観点ではなく、改善による成果を重視するため、調査結果は改善の種類ごとにまとめて提示します。各項目には、サブ分析コードを角括弧で示し、ギャップの内容、ユーザーにとって重要な理由、具体的な修正方法を含める必要があります。references/effectiveness-rubric.md の基準を使って重要度を調整します。

「すべての改善を適用しますか？ それとも一部を選択しますか？」と尋ねます。

レポートを提示し、ユーザーの選択が確認された時点で、フェーズ 3 は完了です。

フェーズ 4：改善の適用

確認済みの項目を、新機能 → 精度の修正 → UX の改善 → 効率性の向上の順に適用します。

各項目について：

• 変更内容と理由を述べます。「依頼されたから」ではなく、効果性の原則を参照します
• 編集を行うか、ファイルを作成します
• 変更が周囲の内容に問題なく統合されていることを確認します

適用後、次の内容を簡潔に説明します：

• 何を、なぜ変更したか
• 何を、なぜ追加したか
• 何を、なぜ見送ったか（労力に見合う効果がない、またはユーザーが提供する必要のあるドメイン知識が必要）
• 何を選択しなかったか — 後から適用できる状態であることを明記します

検証： 説明を提示した後、変更済みの SKILL.md を最初から最後まで読み直し、選択した改善がすべて反映されていること、周囲の内容を誤って変更していないこと、フェーズ番号と終了条件が維持されていること、すべての参照先ファイルが存在することを確認します。

確認済みの項目がすべて適用され、説明が提示され、検証で統合上の問題が見つからなければ、フェーズ 4 は完了です。

フェーズ 5：構造のリント

効果性の改善を適用した後、構造と品質を確認するために skill-lint エージェントを呼び出します：

Use Task tool with subagent_type=claude-skills:skill-lint:
"Lint the skill at <path-to-skill-directory>. Auto-apply critical and major fixes, report
minor findings for user decision."

エージェントの完了を待ちます。構造上の修正が自動適用された場合は、フェーズ 4 の効果性の変更と併せて記載します。軽微な指摘があった場合は、ユーザーに提示します。

リントエージェントが結果を返し、ユーザーが選択した軽微な修正が適用されたら、フェーズ 5 は完了です。