skills-audit

スキル監査

.agents/skills/ 配下にあるプロジェクトローカルのスキルセットを定期的に見直します。カタログが分かりにくくなる前に、変化によるずれを見つけることが目的です。スキルが多すぎる、トリガーが重複している、説明が本文と一致しなくなっている、名前が変更または削除されたスキルへの参照が残っている、といった問題を確認します。

推奨頻度： 毎週、またはスキルが 1 週間に 2 件以上追加・改名された後。

手順

1 — 一覧の作成

シンボリックリンクされたスキルも含めて、現在の一覧を作成します。package.json のスクリプトと .agents/scripts/ に一覧作成・確認用のヘルパーがないか探し、利用できる場合は再利用します。その際は、チェックを重複して実装せず、対応しているオプションを確認してください。説明を読み、振り分け、重複、古い参照の調査が必要な場合は本文を確認します。一覧作成用のヘルパーがない場合：

find -L .agents/skills -name SKILL.md | wc -l                      # total count, including symlinked skills
find -L .agents/skills -name SKILL.md -exec wc -l {} \; | sort -rn # by body length, including symlinked skills

ドメインごとに、頭の中で表にまとめます（DB／状態管理／UI／エージェント／テスト／ワークフロー／ドキュメントなど）。前回の監査以降に追加されたものを記録します（git log --since="1 week ago" -- .agents/skills/）。

2 — 重複・冗長性の検出

同じドメイン内の各ペアについて、次の点を確認します。

• 説明が同じですか？ → 重複の可能性が高いです（古い名前の変更前の残骸、またはグローバルとローカルの競合である可能性があります）。
• 同じタスクが複数の説明に当てはまりますか？ → スキル同士が補完し合っているのか、実際に競合しているのかを確認します。選択に迷う場合に限り、境界を明確にしてください。
• あるスキルの本文に「こちらも参照：foo」とありますか？ → foo がまだ存在することを確認し、相互参照が今も有効かどうかも確認します（参照先のスキルが、参照元のスキルの対象範囲を取り込んでいる場合があります）。
• スキルが AGENTS.md の内容を重複していませんか？ → 内容を AGENTS.md に統合するか、差分だけに絞ってスキルを簡潔にしてください。

よくある誤検出（統合しないでください）：

• db-migrations と drizzle — ワークフローが異なります（マイグレーションファイルとスキーマの作成）。
• agent-runtime-hooks と agent-tracing と agent-signal — エージェントシステム内の対象領域が異なります。
• testing と acceptance — テストの種類が異なります。

3 — 説明と呼び出し境界

説明からスキルの目的と選択境界が明確に分かり、本文と一致しているか確認します。無関係なタスクまで引き寄せる広すぎるトリガー、重複するスキル間の区別不足、古い名前や参照を指摘してください。

Use when や Triggers on のような文字どおりの表現、決まった文の構造、本文に比例した説明の長さを必須としないでください。これらは文章上の選択であり、実行時の振り分けを制御するものではありません。スクリプトの文言に基づくヒューリスティックは、レビューのヒントとして扱い、問題の証拠とはみなさないでください。

明示的な呼び出しのみを許可する設定について、フロントマターの disable-model-invocation や agents/openai.yaml の policy.allow_implicit_invocation など、使用中のハーネスが対応するメタデータと照らし合わせて検証します。異なるハーネスが同じフィールドを認識すると決めつけないでください。意図されたポリシーを維持し、説明の文言だけから実行時の動作を推測しないでください。

4 — 古いスキルの確認

対象範囲の狭いドメインスキル（例：response-compliance、一度限りの CLI ワークフロー）については：

# Confirm the referenced code surface still exists
rg -l "response-compliance|openresponses" packages/ src/            # adjust per skill
git log --since="3 months ago" -- '.agents/skills/<skill>/SKILL.md' # replace <skill>

基盤となる対象領域がなくなっており、スキルも 3 か月以上編集されていない場合は、アーカイブの候補として指摘します。

4b — 更新が続くログの鮮度（common-mistakes.md、probe-mock-patterns.md）

両方の層（汎用の .agents/skills/acceptance/references/ と、プロジェクト用の .agents/acceptance/）は、すべての受け入れテストの実行に注入されるため、古い項目は古い指示になります。各項目について：

rg -n '^`since|holds-while' .agents/acceptance/common-mistakes.md        # every entry must carry both
rg -n 'holds-while: (?!always)' -P .agents/acceptance/common-mistakes.md # the mechanism-bound ones

• since／holds-while がない場合、その項目は登録ルールの導入前のものです。追加するか、フィールドノートに移してください。
• always 以外の holds-while について、記載された仕組みがまだ存在するか確認します（スクリプトのデフォルト、取り込み時のギャップ、プラットフォームの挙動など）。なくなっている場合は、その項目を削除します（PROCESS.md の Step 0 終了ルール）。履歴はフィールドノートに残します。
• 汎用層の項目で、プロジェクトのスクリプト名や製品名を記載しているものは、配置する層が誤っています。
• ID の重複（rg -o '^### [ML]-?[A-Z]?\d+' | sort | uniq -d）。

5 — 相互参照の整合性

実際のスキルリンク、名前付きの引き継ぎ、参照されているファイルを、シンボリックリンクの参照先も含め、所有するルートと照合してください。バッククォートで囲まれたコードシンボルや CLI コマンドは、自動的にスキル参照となるわけではありません。リンク切れを報告する前に、名前変更または移動された参照先を解決してください。また、編集が許可されている場合は、確認できた参照を修正してください。

6 — 出力レポート

ファイルの参照箇所、根拠、提案する変更を添えて、実行可能な指摘事項を報告してください。確認済みの不具合と不確かな候補を区別してください。ユーザーの判断に役立つ場合に限り、インベントリの合計や実行順序を含めてください。固定の見出し、テンプレート、行数の見積もりは必要ありません。

監査のみの依頼では、推奨事項を提示します。--apply または通常の言葉で修正を許可された場合は、再確認せず、その範囲内で安全に変更を適用してください。削除には対象を含む許可が必要です。すでに許可されている場合は、再度確認しないでください。

出力ルール

• 具体的に記述してください。「スキル X は Y と重複します」では、どのトリガーが重複するのかを示さなければ役に立ちません。
• 説明や本文の問題を指摘する際は、行番号を示してください。
• 統合後のスキルが同じコンテキストで実際に読み込まれる場合を除き、統合を推奨しないでください。
• 最近変更されていないスキルの削除を推奨しないでください。「使われていない」は「安定している」という意味であり、「不要」とは限りません。

してはいけないこと

• ❌ 一部のフィールドが古くなっているからといって、表やセクションを削除しないでください。古いフィールド（ステータス、パス、件数）は更新し、コードでは再現できない判断に関するデータ（優先度、担当者、日付、理由）は残してください。
• ❌ 旧スラッグを記載した相互参照とユーザーメモリのエントリーを確認せず、スキルディレクトリの名前を変更しないでください。
• ❌ 説明を短くしたり、テンプレートに収めたりするためだけに、意味のある選択境界を削除しないでください。
• ❌ ドメインが共通しているという理由だけで、200 行を超える大規模なスキルを別のスキルに統合しないでください。大規模なスキルは必要に応じて選択的に読み込まれます。統合するとすべてが読み込まれてしまいます。
• ❌ ユーザーから明示的に求められない限り、.agents/skills/INDEX.md や <domain>-<skill> 形式のプレフィックスへの名称変更を提案しないでください。見た目だけの再編では、手間に見合うメリットがありません。