skill-stocktake
skill-stocktake は、skill や command の参照切れ、曖昧な手順、古い前提を点検する。過去の成果物を根拠に改善候補を挙げ、現在も必要な規則かを確かめて維持・修正・削除を検討する。
使い方
対象の skill と、参照してよい PR・成果物・作業ログを指定する。使用実績の指定がなければ「なし」と記録し、実績からの改善候補の抽出を縮小する。agent-dotfiles では claude/skills/<skill> を編集元とする。
- 既存差分と編集元を確認し、一覧を作る。
- 発動、再現性、例、完了条件、鮮度、構造を点検する。
- 出典を確認して改善候補を挙げ、必要な候補だけ効果を比較する。
- 客観的な修正を行い、判断が必要な変更を提案にまとめる。
- 修正した手順を先頭から実行トレースし、検証後に commit と PR 作成へ進む。
Quick Scan では変更された skill だけを再評価できる。変更なしならそこで終了する。Full Stocktake では全対象を点検するが、毎回必須の全件比較は行わない。
候補の記録
改善候補ごとに次を補助記録へ残す。結果 JSON と補助 script の入出力契約は変更しない。
| 項目 | 記録する内容 |
|---|---|
| 元の失敗と根拠 | 規則の path / revision、失敗の出典、確認日 |
| 当時と現在の環境 | モデル名・version、effort、アプリ名・version、利用 tool / 設定 |
| 事実と仮説 | 観測、必要性の仮説、未確認事項。不明な環境は「不明」、未実施の比較は「未実施」 |
| 比較結果 | 規則あり・なしの記録、品質、失敗再発、時間・token・費用、結論の適用範囲 |
比較と判断
- 元の失敗を含む課題と品質基準を決める。受け入れ条件、失敗再発、権限と完了条件の順守を確認対象にする。
- 規則を一群ずつ変える。規則あり・なしで同じ課題、モデル、effort、アプリ環境を使い、対象外の条件を固定する。
- 各条件を独立した session で実行し、相手の回答や結論を渡さない。別コピーを使い、稼働中の個人設定や権限境界を変更しない。安全に外せない規則は実行比較を保留する。
- 品質・失敗再発を先に確認する。同じ基準を満たした場合に時間・token・費用を比べ、時間・token 削減だけで採否を決めない。環境差があれば限界を記す。
- 維持・修正・削除候補・必要時参照への移動候補・追加調査から選ぶ。規則なしでも同じ品質が得られた範囲で削除や移動を検討し、再発した失敗への対策は維持する。
以下は架空の例であり、実測結果ではない。
| 候補 | 比較結果 | 判断 |
|---|---|---|
| 古い出力崩れを補う重複手順 | 元の根拠は古く、現行環境では規則なしでも品質基準を満たし、再発なし | 比較した範囲で削除候補。特殊条件でだけ必要なら必要時参照への移動候補とし、ユーザー確認を待つ |
| 対象外変更を防ぐ確認手順 | 規則なしで対象外変更が再発し、規則ありで防げた | 維持。規則なしの方が速くても削除しない |
| 新モデルなら不要という仮説 | 当時の effort は不明で、比較未実施 | 追加調査または現状維持。削除済み・効果確認済みにはしない |
変更の境界
モデル能力の向上だけで、個人の規則、権限境界、実際に再発した失敗への対策を不要と判定しない。規則の自動削除・自動追加、権限や完了条件の自動緩和は行わない。削除や必要時参照への移動は提案に留め、ユーザー確認後に変更する。
新たな必須 gate や集計基盤は追加しない。Claude 固有の診断機能は任意の補助で、全 runtime の必須依存にしない。PR 本文 composer、compact-plus、comment-intent、task-ledger の撤去をこの評価手順の結論に含めない。
検証と結果
既存の点検、出典確認、公開前の実行トレースと検証を維持する。実施済み修正と提案を分けて報告し、比較未実施なら削除済み・効果確認済みとは報告しない。
agent-dotfiles の契約検査は go test ./internal/skilldocs -count=1 で実行する。TestSkillStocktakeContract が、skill と本ページの比較手順、判断例、禁止事項を確認する。
詳細な操作、報告フォーマット、結果 JSON は skill 本体 を参照する。