メインコンテンツへ移動
AIチュートリアル

Skill Sunsetで古いAI指示を安全に監査する

Skill Sunsetを使って、AGENTS.md、CLAUDE.md、SKILL.mdのファイルを監査し、壊れた参照、重複、過大な指示、古くなっている可能性のあるルールを検出する方法を学びます。このチュートリアルでは、セットアップ、レポート生成、CI統合、動作実験、安全な修正、ロールバックについて解説します。

約14分で読了
Skill Sunsetで古いAI指示を安全に監査する

Skill Sunsetとは？

Skill Sunsetは、蓄積されたAIエージェントの指示を監査するコマンドラインツールです。AGENTS.md、CLAUDE.md、SKILL.mdなどのファイルをスキャンし、古い参照、重複したSkill、常時読み込まれるサイズ過大なコンテンツ、不正なフロントマター、その他の保守上の問題を特定します。

このツールは、決定論的なチェックと、慎重に作成されたレビュー仮説を組み合わせます。古く見える指示をすべて不要とはみなさず、検出結果が削除を許可することもありません。代わりに、静的に検証できる問題と、テストが必要な挙動関連のルールを分けて扱います。

重要: TEST判定は「この仮説を評価する」という意味です。新しいAIモデルによってその指示が不要になったことを意味するものではありません。

監査はローカルで読み取り専用として実行されます。コア機能はAI APIを呼び出さず、モデルのクォータを消費せず、プロバイダーの認証情報も読み取りません。

テストフィクスチャから生成されたSkill Sunset監査レポート

主な機能

  • 静的な指示チェック: 壊れたローカル参照、古い絶対パス、不正なSkillフロントマター、常時読み込まれるサイズ過大なファイル、平文の認証情報の可能性を検出します。
  • 慎重な重複処理: 同名のSkillを検出し、復元可能な廃止を推奨する前に完全なバンドルを検証します。
  • 挙動に関する仮説: モデル世代に依存した補正ルールを、不要と断定せずTESTとして分類します。
  • 複数のレポート形式: バイリンガルHTML、Markdown、JSON、CodexおよびClaudeへの引き継ぎプロンプト、評価計画、実験テンプレート、ロールバックマニフェストを生成します。
  • 保護対象の指示カテゴリ: ドメイン知識、安全ルール、認可ゲート、プロジェクト不変条件を自動廃止の対象から除外します。
  • CI対応: --fail-onを通じて、重大度に基づく終了コードを返せます。
  • プライバシーに配慮したレポート: ユーザーのホームディレクトリ配下のパスを$HOME/...に短縮し、それ以外の絶対パスの対象を$ABSOLUTE/<name>として表します。

要件と対応環境

Skill SunsetはNode.js 20、22、24に対応しています。GitHub Actionsを通じてUbuntu、macOS、Windowsで検証されています。その他のLinuxディストリビューションもNode.js 20以降で動作すると想定されていますが、現在はプロジェクトのCIマトリクスに含まれていません。

Codex用のプリセットスキャン対象は~/.codex、Claude Code用は~/.claudeです。明示的に指定した任意の範囲限定ディレクトリも監査できます。

インストールとセットアップ

グローバルインストールは必要ありません。最新の公開パッケージをnpxで直接実行します。

npx skill-sunset@latest audit --codex --open

このコマンドはCodexの設定を監査し、生成されたHTMLレポートを開きます。代わりにClaude Codeを監査するには、次を実行します。

npx skill-sunset@latest audit --claude --open

プロジェクトまたは別の範囲限定ディレクトリをスキャンするには、そのパスをauditに渡します。

npx skill-sunset@latest audit /path/to/setup

主レポートの言語はデフォルトで--lang autoです。--lang enまたは--lang zh-CNで明示的に選択できます。各レポートバンドルには、移植可能な英語および簡体字中国語のHTMLページも含まれます。

最初の監査を実行する

現在のディレクトリを監査する

指示ファイルを変更する前に、復元可能なコピーを作成してください。たとえば、AGENTS.mdをバックアップし、専用ディレクトリにレポートを書き込みます。

cp AGENTS.md AGENTS.md.skill-sunset.bak
npx skill-sunset@latest audit . --out .skill-sunset --open

監査は読み取り専用です。保守作業の可能性を報告しますが、スキャンしたファイルを変更または削除することはありません。

レポートバンドルを理解する

デフォルトでは、生成されたバンドルに次の成果物が含まれる場合があります。

.skill-sunset/
├── index.html
├── index.en.html
├── index.zh-CN.html
├── audit-report.md
├── audit.json
├── execution-prompt-codex.md
├── execution-prompt-claude.md
├── eval-plan.md
├── experiment-template.json
└── rollback-manifest.json

HTMLファイルは対話的な人間によるレビューに、audit-report.mdは移植可能なテキストレポートに、audit.jsonは自動化に使用します。実行プロンプトはCodexまたはClaude Codeへの引き継ぎに対応し、評価計画と実験テンプレートは挙動に関する仮説の検証に役立ちます。

生成されたrollback-manifest.jsonは、認可された実行エージェントが実際の変更とハッシュを記録するまで空のままです。

判定を解釈する

  • MERGE: 完全な重複、または競合する同名Skillは、統合の対象としてレビューする必要があります。
  • UPDATE: パス、参照、ツールの前提、またはバージョンに依存する指示に修正が必要な可能性があります。
  • DEMOTE: 有用な詳細情報が広範囲に読み込まれており、段階的開示に移すべき可能性があります。
  • RETIRE: 同一のスキャンルート内に、同名でバイト単位の内容が同一かつ完全な汎用Skillバンドルが存在します。推奨されるのは、復元可能なアーカイブのみです。
  • TEST: 不要になった可能性があるという主張について、整理する前に旧版と新版の挙動評価が必要です。

これらの判定はレビューカテゴリであり、自動的な変更承認ではありません。指示を編集する前に、各問題をリポジトリ、現在のツール、代表的なタスクに照らして確認してください。

例: 検出結果からロールバックまで

たとえば、AGENTS.mdファイルに無条件のツール要件と、存在しないデプロイガイドへのリンクが含まれているとします。

すべてのタスクで必ず Context7 を使用してください。
[デプロイ手順書](docs/deploy.md)

docs/deploy.md が存在しない場合、Skill Sunset は次の3つの異なる懸念を報告することがあります。

  • UPDATE / broken-reference：手順書の参照先を解決できないため。
  • UPDATE / context7-assumption：現在のツールの利用可能性を検証する必要があるため。
  • TEST / unconditional-tooling：「すべてのタスクで」という要件には、代表的な動作評価が必要なため。

確認済みの変更のみ適用する

まず、実際のデプロイ手順書を特定し、現在のツール一覧を確認します。確認できた古い参照だけを修正してください。無条件のツール使用ルールは、静的レポートに基づいて削除するのではなく、別個の実験候補として扱います。

編集後、監査とプロジェクト独自のテストを再実行します。

npx skill-sunset@latest audit . --out .skill-sunset --format json
npm test

TEST 検出項目を検証する

TEST 項目の場合は、生成された .skill-sunset/experiment-template.json を完成させます。コマンドを実行せずにマニフェストを検証するには、次を実行します。

npx skill-sunset@latest test .skill-sunset/experiment-template.json --root .

検証だけではコマンドは実行されません。実行するには、別途 --run フラグが必要です。

npx skill-sunset@latest test .skill-sunset/experiment-template.json --root . --run

実験に合格しても、そのマニフェストに記述された受け入れ基準だけが証明されます。その指示が普遍的に不要であることを示すものではありません。

回帰をロールバックする

参照、プロジェクトのテスト、またはタスクの動作に回帰が発生した場合は、保存したファイルを復元して、もう一度監査します。

cp AGENTS.md.skill-sunset.bak AGENTS.md
npx skill-sunset@latest audit . --out .skill-sunset

CI で Skill Sunset を使用する

自動化のために JSON 出力を要求し、重大度のしきい値を設定します。

npx skill-sunset@latest audit /path/to/setup --format json --fail-on high

この形式は、機械可読な出力と重大度の高い検出項目に対する失敗条件を必要とする CI パイプラインに適しています。終了ステータスを指示の変更や削除の承認とみなすのではなく、JSON アーティファクトを確認してください。

高度な安全対策とワークフローのヒント

スキャン対象のルートを限定する

監査対象の指示セットを含む最小のディレクトリを渡します。重複分析と廃止の推奨は1つのスキャンルート内で評価されるため、明確な境界を設定すると結果を解釈しやすくなります。

静的修正と動作変更を分離する

リンク切れや確認済みの古いパスは、通常、直接調査できます。モデルの動作や無条件のツール使用に関するルールは、明示的な受け入れ基準、代表的なタスク、ロールバック計画を備えた別個の候補として扱うべきです。

実験の実行を特権操作として扱う

実験マニフェストは --run が指定されない限り検証専用です。コマンドはシェルを介さずに実行され、デフォルトでは最小限の非機密環境変数許可リストを受け取ります。

完全な環境変数の継承には、--run に加えて --inherit-env が必要です。継承された変数にはプロバイダーの認証情報が含まれる可能性があるため、このオプションは信頼できるコマンドに対してのみ使用してください。実験マニフェストに認証情報を記載しないでください。

保存される実験データを理解する

ドライランと結果ファイルには、実行ファイル名、引数の数、コマンドハッシュ、出力サイズ、出力ハッシュが保持されます。コマンドの引数や出力本文は保持されません。これにより露出は抑えられますが、実験の定義とコマンドは引き続き慎重に確認してください。

シークレットスキャンを証明とみなさない

Skill Sunset は平文の認証情報らしきものを検出できます。また、プロジェクトでは公開時のチェックとして Gitleaks を使用しています。ただし、README には、これですべての認証情報形式を認識できると証明されるわけではないことが明記されています。

ローカル開発

リポジトリ自体を開発するには、テストを実行し、パッケージの内容を確認し、同梱フィクスチャからデモレポートを生成します。

npm test
npm pack --dry-run
node ./bin/skill-sunset.js audit ./test/fixtures/sample-setup --out ./demo-report --open

プロジェクトの GitHub Actions ワークフローでは、Gitleaks とテストを、サポート対象のオペレーティングシステムおよび Node.js のマトリックス全体で実行します。プロジェクトに関する追加情報は、リポジトリの変更履歴、コントリビューションガイド、セキュリティポリシーで確認できます。

現在の対象範囲

バージョン 0.2.0 では、静的チェック、保守的な重複廃止、ローカライズされたレポート、パスの秘匿化、ゲート付きコマンド実験ハーネス、CI の重大度別終了コード、敵対的出力テストを提供します。現在のプロバイダー機能のスナップショット、セッション使用量アダプター、タスク品質アダプターは、既存機能ではなく、将来のエビデンス層として説明されています。

結論

Skill Sunset は、古いルールが自動的に不要になったと仮定せず、AI 指示ファイルを維持するための慎重なワークフローを提供します。まず読み取り専用の監査から始め、決定論的な問題と動作に関する仮説を区別し、プロジェクトのテストと管理された実験で変更を検証し、プロセス全体を通じて復旧可能なロールバック手段を確保してください。