/da-skills-audit — ツールキットを腐らせない

スキルは溜まることで劣化する。インストール済みの全 description は常にコンテキストに載り、モデルはそれと依頼を突き合わせて選ぶ。刈り込まずに増やすと、誰にも気づかれずに選択が外れ始める。

このスキルは何も変更しない。報告と提案だけで、削除の承認はユーザーが行う。

このスキルはファイルを読む。利用状況は測らず、評価（eval）でもない。道具は 4 つあり、1 つでは足りない。

レポートの冒頭で、4 つのうちどれを実行したかを書く。補助ツールがそのハーネスで利用できなければ、未実行と限界を明示してファイル監査を続ける。導入や別ハーネスへの移動を必須にしない。ファイル監査が綺麗でも、スキルが役立つかは何も分からない。それには最後の行のような比較評価が要る。

結果を信じる前に知っておくこと。

• 一覧はこのリポジトリよりずっと大きい。約 40 本が Claude Code 本体に組み込まれてディスクに現れず、Anthropic 管理のプラグインがさらに約 11 本足す。ファイル監査はモデルが見る一部しか見ない。全体を見るのは /skill-doctor と /doctor で、ディスク上の本数を総数として出さない。
• 書いたセッションでベンチマークしたスキルは実際より良く見える。残ったコンテキストが指示の穴を埋めるので、新しいセッションで測る。

実行条件

ワークフロー上の位置

読むファイル

常に読む

条件つきで読む

すべてのスキル本文を読まない。それはこのスキルが見つけるべき失敗そのもので、監査で節約する以上のコンテキストを使う。

レポートはユーザーが書いている言語で書く（不明なら日本語）。パス・識別子・コマンド・コード片・ログは原文のまま残す。

Step 0. 自作と外部を分ける

grep -l 'source: bwkw/dotagents' ~/.agents/skills/*/SKILL.md

それ以外は第三者からのインストール。どちらかで提案してよいことが変わる。

• 自作 — 何でも提案してよい。description の書き直し、本文の分割、削除。
• 外部 — 手段はインストールかアンインストールだけ。upstream のスキルの編集は提案しない。次の npx skills update で黙って消える。upstream のスキルが問題なら、そう書いて削除か upstream への報告を提案する。

先に進む前に本数を書く。どちらが自作か分からない予算報告は動きようがない。

Step 1. 静的チェック

監査パスにリンターを掛ける。機械的なチェックはすでに実装されている。

"$(node -e 'console.log(require(process.env.HOME+"/.claude/.dotagents-managed.json").repo)')/scripts/verify-skills.sh" ~/.agents/skills

報告されるもの: name / description の欠落、name とディレクトリの不一致、大きすぎる SKILL.md、disable-model-invocation、本文が裏付けない allowed-tools / context:、相対の reference パス、description の合計予算。

結果の読み方:

Step 2. 守備範囲の重複

トリガーの語彙を共有する description をまとめる。同じ依頼を 2 本が取り合うと、どちらも確実には勝たない。

特に出どころをまたぐ組を探す。upstream の集合同士も、ローカルで書いたものとも重なる。まとまりごとに、スキル・共通のトリガー・その領域を持つべき 1 本を報告する。

Step 3. 利用状況 — 知っている道具に聞く

使われていないものは静的解析では分からない。分かる情報源は 3 つあり、手間の少ない順に並べる。

1. /skill-doctor。使われずにコンテキストを食うスキルを出す専用の道具。利用でき、利用状況の確認が必要な時に実行結果を使う。ファイル監査に見えない組み込み・プラグインのスキルも含む。利用できない時は未実行として先に進み、ファイルの存在やサイズから利用頻度を推測しない。

2. ~/.claude.json → skillUsage。スキル名から {usageCount, lastUsedAt} への対応で、直接読める。

node -e 'const u=require(process.env.HOME+"/.claude.json").skillUsage||{};
  Object.entries(u).sort((a,b)=>b[1].usageCount-a[1].usageCount)
    .forEach(([k,v])=>console.log(String(v.usageCount).padStart(5), new Date(v.lastUsedAt).toISOString().slice(0,10), k))'

注意が 3 つある。どれも実際に誤った結論を生んだ。

• キーが無いのは「名前で呼ばれたことが無い」という意味で、役に立たないという意味ではない。自動発火したスキルは載らないことがある。
• キーに出どころが無い。素の review は組み込みスキルかもしれず、同名のプロジェクトコマンドかもしれない。他リポジトリのプロジェクト用コマンドも区別なく混ざる。
• インストール日と比べる。昨日入れて利用 0 のスキルからは何も分からない。結論の前に ~/.agents/.skill-lock.json かディレクトリの mtime を見る。

3. OpenTelemetry。合計ではなくトリガー別の内訳が欲しい時。OTEL_LOG_TOOL_DETAILS=1 が要る（dotagents が設定する）。イベントは skill_activated で、skill.name と invocation_trigger を持つ。クエリはユーザーが実行するものとして出し、自分でバックエンドに問い合わせない。

Cursor はこれを何も出さない。標本は Claude Code だけなので、主に Cursor で使うスキルはここでは未使用に見える。テレメトリだけで削除しない。これは候補を絞るもので、決めるのはユーザー。

Step 4. 報告する

## スキル監査 — N 本、description 合計 M 文字

### 自作 / 外部
自作 N 本、upstream からのインストール M 本、計 T 本。

### ブロッカー
(Step 1 のエラー: 壊れた frontmatter、大きすぎる本文、Cursor で動かない宣言。
upstream のスキルのエラーは報告するが、その場で直すものではない)

### 予算
合計 M 文字（目標 8,000）。超過の大きいもの:
| スキル | 文字数 | 削る案 |

### 守備範囲の重複
| まとまり | スキル | 共通のトリガー | 持ち主にする案 |

### 利用状況のクエリ
(ユーザーが実行するクエリ)

### 提案するアクション
| スキル | 自作？ | アクション | 理由 |
| … | 自作 / upstream | 残す / description を書き直す / X に統合 / 削除 | … |

完了条件

• Step 1 のエラーがすべて、ブロッカーとして挙がっているか、許容できる理由が書かれている
• description の予算が目標に対する数値で書かれている
• 提案した削除のすべてに、「テレメトリが 0」だけではない理由がある

次に

合意したアクションを適用する。upstream のスキルの削除は npx skills remove <name> -g。自作の削除は dotagents/skills/ から消して setup.sh install を実行する（配らなくなったものは install が刈る）。