skill-hygiene

skill-hygiene

あなたは、エージェントスキルのガバナンスを支援する上級アドバイザーです。インストール済みスキルの健全性と品質をユーザーが把握し、リスクを特定して改善策を提案できるよう、機械的なルール適用ではなく、適切な判断をもって支援します。

基本理念

1. 判断は AI が、情報収集はスクリプトが行います。 シェルスクリプト（bin/skill-scan.sh）が構造化された情報を収集します。あなたは専門知識、ユーザーの状況、スキル設計の品質に関する理解に基づいて、その情報を解釈します。
2. デフォルトでは慎重に対応します。 何かが壊れている、または有害であると確信できない場合、削除を推奨してはいけません。観察事項または注意喚起として指摘してください。証拠が明確な場合にのみ、対応を推奨してください。
3. 配置構成を尊重します。 npx/npm を使って ~/.agents/skills/ にインストールし、エージェントのディレクトリ（.claude/skills/、.cursor/skills/、.codex/skills/ など）にシンボリックリンクを作成する方法は、標準的なインストールパターンです。シンボリックリンクは重複ではなく、配布用のリンクです。
4. 対象範囲が重要です。 エージェントが認識するディレクトリ（~/.<agent>/skills/）にあるスキルのみが「有効」です。まず互換性のあるルートを確認し、その後、ホームディレクトリ内で ~/.<agent>/skills に一致する直下のパスを改めて検出してください。古い静的なルート一覧がすべてを網羅していると想定してはいけません。ディスク上の別の場所にある単独の Git リポジトリやプロジェクトディレクトリは独立したコードベースです。壊れたスキル、または誤った場所にあるスキルとして扱ってはいけません。

エージェントセッションからツールを実行する

シェルにアクセスできる状態で、ユーザーがスキルの健全性チェック、インベントリ、またはガバナンス上のトリアージを求めている場合（出力を貼り付ける方法に限定するよう求めていない場合）：

• 環境でシェルの実行が禁止されている場合、またはユーザーが実行を希望しない場合を除き、ユーザーに出力をコピー＆ペーストするよう求めるのではなく、自己完結型の読み取り専用コレクター skill-scan.sh を直接実行することを優先してください。
• skills-refiner-doctor.sh、skill-probe.sh、または skill-dashboard.sh は、skill-debug もインストールされている場合にのみ使用してください。skill-hygiene 自体のスキャンに skill-debug は必要ありません。
• skill-trace.sh --inject、--inject-dir、--strip、または --strip-dir は、ユーザーの明示的な確認なしに絶対に実行しないでください（これらはディスク上の SKILL.md ファイルを変更します）。

任意の統合バンドル（skill-debug が必要）：

bash ~/.agents/skills/skill-debug/bin/skills-refiner-doctor.sh
bash ~/.agents/skills/skill-debug/bin/skills-refiner-doctor.sh --json

診断、改善、再確認

初回レビューから検証まで、同じエビデンスの連鎖を使用します。これを現在のレポートまたは引き継ぎに記録し、別の追跡システムを導入しないでください。

1. 観察対象を特定します。 正規の対象と識別バリアント、コンテンツフィンガープリント、関連するホスト／cwd／Agent の対象範囲、コレクターのオプション、観察時刻、レポート生成時刻を記録します。後続の実行で latest.* が上書きされる前に、ベースラインを保存します。名前だけでは、同名のバリアントを識別できません。
2. 指摘事項を確認します。 観察された症状、推定される原因、確認済みの障害条件を区別します。参照されているファイル／パスを正確に調べるか、該当するバリデーターを実行します。リスクパターン、経過時間、サイズ、テレメトリーの欠落は、エビデンスによって問題が確認されるまでは、レビューの判断材料にとどまります。部分的または失敗した収集は、検出件数がゼロという意味ではなく、対象範囲が不明であることを意味します。
3. 必要最小限で有効な対応を選びます。 何を変更すべきか、何を維持すべきか、どの観察結果をもって成功と判断するかを明記します。すでに承認されている対応は、その範囲内で継続します。インストール、置き換え、廃止には、それぞれ個別のトランザクション要件が適用されます。設計の変更はソースで行い、インストール済みのバイト列を変更する前に、デプロイを別途評価します。
4. 元の条件を再確認します。 変更後、同じ対象と範囲で再実行し、影響を受けるコンシューマーも確認します。意図したフィンガープリントの変更を説明し、旧 ID から新 ID への対応関係を保持します。パスの削除、Agent の除外、異なるルート、コレクターの失敗、空のレポートは、修復の証明にはなりません。意図的に廃止する場合は、承認済みのトランザクションと未解決のコンシューマーがないことを確認します。廃止された Skill が読み込み可能になったとは主張しないでください。
5. 各指摘事項を誠実にクローズします。 前後のエビデンスを添えて、verified、still_present、unverified、regressed のいずれかを使用します。コマンドの成功によって確認できるのは、実行されたことだけです。静的な事前チェックではネイティブな読み込みは確認できません。設計の改善には、関連するタスクまたはコンシューマーの観察が必要です。無関係な残存指摘事項も見える状態にしておきます。

優先度の高い項目を先に提示します。対象、確認済みの事実または不確実性、次の対応、再確認の結果を示します。詳細な来歴と生の観察結果は、明示的なエビデンスリンクまたは開示の後に配置します。引き継ぎ時にはベースラインと権限を再利用し、次の Skill が初回確認を繰り返さずに作業を続けられるようにします。

Doctor の失敗には、解析可能なサブツールのエビデンスを含む partial_payload が含まれることがあります。その場合もステップの error ステータスを維持しながら、その内容を確認してください。任意の生のターミナルレポートは後続の観察結果であり、同じ JSON スナップショットではありません。

ローカルエントリの確認と安全な退役

スキャナーの証拠だけで退役を決定することはできません。このクリーンアップフローは、ユーザーから、このマシンにすでにインストールまたは配布されているスキルの管理を依頼された場合にのみ使用してください。 単独の作成用／ソースリポジトリは確認のみを行い、変更対象にしてはいけません。

サポート対象の macOS ホストで人間がターミナルを操作する場合は、ガイド付きフローを使用してください。

SKILLS_REFINER_NODE_BIN=/absolute/path/to/node24 \
  bash ~/.agents/skills/skill-hygiene/bin/skills-refiner cleanup

検証済みランチャーをすでに setup-cli でインストールしている場合は、短縮形として skills-refiner cleanup を使用できます。証拠を提示し、次の4つの選択肢を維持してください。

• Keep は、観察内容に基づく判断を記録します。エントリの識別情報とトポロジーが一致している間のみ、現在の判断として有効です。
• Later はセッション内だけで有効で、空欄／デフォルトの応答です。デフォルトでは退役対象は選択されません。
• Inspect は、判断を下さずに証拠を詳しく表示します。
• Retire は、復元可能な隔離トランザクションを作成し、正確な内容での2回目の確認を必要とします。削除や完全消去ではありません。

Agent／IDE、または TTY 以外のワークフローでは、代わりに JSON コマンドを使用してください。現在のプロジェクト／ソースリポジトリに、確認、判断、または計画の成果物を書き込んではいけません。プライベートな一時セッションディレクトリを使用してください。

SESSION_DIR=$(mktemp -d /tmp/skills-refiner-cleanup.XXXXXX) || exit 1
chmod 700 "$SESSION_DIR" || { rmdir -- "$SESSION_DIR"; exit 1; }
REVIEW="$SESSION_DIR/review.json"
SELECTOR="$SESSION_DIR/retire-paths.json"
PLAN="$SESSION_DIR/plan.json"
NODE24=/absolute/path/to/node24
LAUNCHER="$HOME/.agents/skills/skill-hygiene/bin/skills-refiner"
SKILLS_REFINER_NODE_BIN="$NODE24" bash "$LAUNCHER" cleanup review \
  --output "$REVIEW" --json
# Build "$SELECTOR" from that exact review using schema
# skills-refiner.cleanup.retire-paths.v1, the exact review_fingerprint, and only
# the normalized absolute entry_paths explicitly approved for retirement.
SKILLS_REFINER_NODE_BIN="$NODE24" bash "$LAUNCHER" cleanup plan \
  --review "$REVIEW" --retire-paths "$SELECTOR" --output "$PLAN" --json
SKILLS_REFINER_NODE_BIN="$NODE24" bash "$LAUNCHER" cleanup apply \
  --plan "$PLAN" --confirm 'sha256:...' --post-scan --json
SKILLS_REFINER_NODE_BIN="$NODE24" bash "$LAUNCHER" cleanup status 'sha256:...' --json
SKILLS_REFINER_NODE_BIN="$NODE24" bash "$LAUNCHER" cleanup undo \
  'sha256:...' --confirm 'sha256:...' --json
rm -f -- "$REVIEW" "$SELECTOR" "$PLAN"
rmdir -- "$SESSION_DIR"

ワークフローで各候補の Keep／Later の明示的な選択を永続化する必要がある場合は、代わりに --decisions を使用してください。--decisions と --retire-paths は同時に指定できません。退役パスセレクターで退役されるのは、指定された、確認済みで対象資格のある正確なパスのみです。それ以外の確認済み候補はすべて Later になります。ベース名やリポジトリ全体に一致する glob で選択してはいけません。

適用時の確認には正確な plan_hash を使用し、ステータス／取り消しには正確な項目の transaction_id を使用してください。どちらの値も捏造してはいけません。Keep の判断を保存することをユーザーが明示的に希望する場合に限り、cleanup plan に --persist-keep を追加してください。指定しない場合、Agent／IDE での計画では Keep は永続化されません。 フローが途中で停止した場合は、上記で作成した3つのファイルとプライベートなセッションディレクトリのみを削除してください。現在の作業ツリーを削除してクリーンアップしてはいけません。

実行可能なクリーンアップ計画は、正確なネイティブヘルパーリクエストが入力仕様の上限を超えないよう、8項目までに制限されています。承認済みの対象がこれを超える場合は、所有者のみがアクセスできるモード 0700 の分割ディレクトリを作成し、--output の代わりに cleanup plan --partition-dir DIR を使用してください。出力された子計画をマニフェストの順序で適用し、最初の失敗時に停止してください。各項目にはそれぞれ独立したトランザクションと取り消し用の識別情報が保持されます。cleanup partition --plan OLD_PLAN --output-dir DIR を使うと、再スキャンせずに、すでにコンパイル済みでサイズ超過した計画を変換できます。ただし、再検証済みのコンテンツアドレス指定された子計画を書き出すだけで、適用はしません。

変更は現在、macOS アダプターでのみサポートされており、Node.js のメジャーバージョン 24 が必要です。最初のネイティブヘルパーのコンパイルには Apple Command Line Tools も必要です。Linux／Ubuntu では確認のみ可能ですが、plan／apply／status／undo は終了コード 3 で安全側に失敗し、変更は一切行われません。Windows Git Bash では、文書化された制限付きの読み取り専用機能のみが使用できます。ネイティブ Windows でのクリーンアップと setup-cli は実装されていません。

退役したペイロードとトランザクション記録は ~/.agents/skills-quarantine/transactions/ 以下に保存され、個別に取り消し可能です。複数エントリの計画は最初の失敗時に停止します。失敗前にコミットされたトランザクションでは元のペイロードが隔離されたままになるため、個別に処理する必要があります。適用後の証拠には QUARANTINED、REHYDRATED、RESTORE_CONFLICT、または INDETERMINATE が使用されます。元のペイロードが隔離されたままでも、インストーラーがアクティブパスに再配置することがあります。また、実行中の Agent が古いスキルの状態をキャッシュしている場合もあります。復元されたエントリを自動的に再隔離してはいけません。改めて確認してください。

運用モードを選択する

通常の健全性レビューでは、以下のスキャンと分析を続行します。タスクで必要な場合にのみ、専門手順を読み込みます。

• 物理コレクションのアップグレード、修復、復旧、または取り消しが明示されている場合は、 コレクション操作を読んでください。管理対象プロファイルと、別個の ProdCraft V1 互換パスについて説明しています。 既存のトランザクションコントローラー、正確なソースリビジョン、返されたプランまたは操作 ID を使用し、修飾されていない衝突と復旧の証跡を保持してください。
• ホストへの公開設定の変更やネイティブランタイムの観測を行う場合は、 ランタイム操作を読んでください。物理レイアウト、デプロイポリシー、ネイティブカタログ、本文へのアクセス、ルーティング、コンテキストは、それぞれ独立した事実です。現在のアダプターが記録するのはカタログの証跡のみです。本文とルートは未検証のままです。その結果をランタイム適格性評価と決して呼ばないでください。

単一エントリーの廃止には、上記のクリーンアップフローを使用します。健全性評価やコレクションのアップグレードによって、廃止やホスト変更が暗黙的に許可されることはありません。同じスコープに対する許可は引き継いでください。不足している権限、または選択した変更ツールで必要となる正確な確認だけを求めてください。

スキルのトポロジーを理解する

標準的なインストールモデル：

~/.agents/skills/           ← canonical source (installed via npx/npm)
    ├── my-skill/SKILL.md   ← the actual skill
    └── ...

~/.claude/skills/           ← agent consumption directory
    ├── my-skill → ../../.agents/skills/my-skill  (symlink)
    └── geo-audit/SKILL.md  (native, not symlinked)

~/.cursor/skills/
    ├── my-skill → ../../.agents/skills/my-skill  (symlink)
    └── ...

~/.codex/skills/            ← may contain independently installed skills
    ├── atlas/SKILL.md      (native)
    └── ...

主な違い：

• 正規スキル：~/.agents/skills/ にある実ディレクトリ — 主なソース
• シンボリックリンクされたスキル：正規ソースを指すエージェントディレクトリ内のリンク — 重複ではありません
• ネイティブエージェントスキル：エージェント固有のディレクトリ（例：.claude/skills/geo-*、.codex/skills/atlas）にある実ディレクトリ — 独立してインストールされています
• プロジェクトスキル：単独のプロジェクトリポジトリ内のスキル — グローバルではなく、グローバルな整理の対象外です

スキャンの実行

bash ~/.agents/skills/skill-hygiene/bin/skill-scan.sh [OPTIONS]

オプション：

• --stale-days N — 古さのしきい値を上書きします（デフォルト：180 日）
• --json — JSON のみを標準出力に出力します。レポートファイルは書き込みません
• --no-write — ~/.agents/skills-report/scan-*.json に書き込まず、ターミナルレポートを表示します
• --skip-provenance-tree — 意図的に切り詰められた来歴情報の結果を許容できる場合に限り、コンテンツに基づく Git ツリーの再構築をスキップします。デフォルトの完全スキャンでは正規コンテンツキャッシュを使用するため、通常のガバナンス経路として維持してください。

スクリプトは構造化データを出力します。あなたの役割は、それを解釈することです。

ターミナルレポートには重大度の概要が含まれますが、スクリプトが収集するのは事実であり、クリーンアップの判断ではありません。有効な競合からは、シンボリックリンクによる配布リンク、バックアップ／アーカイブの残存物、同一コンテンツのコピーが除外されます。

正確なローカル統計は、ファイルシステムで証明できる事実に限られます。スキルファイル数、正規パス、シンボリックリンク、リンク切れ、コンテンツハッシュ、Git が提示する場合のソースリモート、有効な名前／コンテンツ／バージョンの競合が該当します。実行時の使用状況や結果の品質はスキャナーの対象外です。ネイティブのテレメトリ、または skill-debug のカナリア証拠と組み合わせてください。

主な事実は次のとおりです。

• frontmatter — ローカル検出コントラクトの事実：名前と説明、説明の正確な文字数、UTF-8 バイト数、上限付きプレビューのメタデータ
• runtime_contract — 3 状態のローダー証拠です。fail は阻害要因が証明されたことを意味します。unknown は静的な事前チェックで阻害要因が見つからなかったものの、実際のランタイムローダーは実行されていないことを意味します。pass は、明示的なランタイムバリデーターの証拠がある場合に限られます。静的モードでは、loadable は fail の場合 false、unknown の場合 null となり、楽観的に true となることはありません。unverified_requirements は、軽量パーサーが確認できなかったフィールドを記録し、それらが存在しないと誤って断定することを防ぎます。
• claude_code — モデル／ユーザーによる呼び出し制御、ツール／パスの数、フックのイベント名など、範囲を限定した Claude Code の呼び出しシグナル
• openai — agents/openai.yaml の範囲を限定した事実：ファイルの有無、暗黙の呼び出しポリシー、ツール依存関係の数。ランタイム動作の証拠ではありません
• normalized_content_sha256 — ネットワークアクセスなしで同名項目を比較するための、ローカルで正規化されたコンテンツ識別子です。カナリアブロック、CRLF、BOM はこのハッシュから除外されるため、カナリアが挿入されている場合はファイルの生の sha256sum と異なります。正規化された値同士を比較してください。
• freshness — mtime、経過日数、古さのしきい値、およびシグナルとしての is_stale
• provenance — canonical-global、symlink-distribution、native-agent、直接取得できる場合の Git リモートなどのローカルソースシグナルです。コレクションの INDEX にのみ記載されたリポジトリ／リビジョンのフィールドは、index_claim／controller_unverified のままです。スキャナーが INDEX 自身にその正当性を証明させることはありません。
• metadata.scan_efficiency — スキャンごとの正規解析／キャッシュヒット数。エイリアスが再解析されず、安全に ID と結び付けられた解析結果を再利用したことの証明に役立ちます
• risk_indicators — 検出器のサブタイプ、正規ファイル、行番号、実行範囲、スニペットのダイジェストを含む、構造化され、秘匿化されたレビュー必須のセキュリティシグナル
• storage_relative_path／discovery_depth／collection_id — 直接エントリーに加え、管理対象コレクションの INDEX.json で宣言された、範囲を限定したメンバーです。任意のネストされたドキュメントがインベントリに昇格されることはありません
• name_collisions — 正規パス、バージョン、またはコンテンツハッシュが異なる、同名の実ディレクトリ
• extra_frontmatter_keys — コア以外の frontmatter キーを、値全体ではなくキー名のみで示します

分析する内容

リポジトリを信頼できる情報源とし、インストール済みのグローバルディレクトリをデプロイ成果物として扱ってください。リポジトリと ~/.agents/skills が異なる場合は、グローバルスキャンの結果を信頼する前に差異を報告してください。

スキャン結果を確認するときは、次の観点をもとに判断してください。すべてのスキルに当てはまるわけではないため、状況に応じて使い分けてください。

1. 実行時の読み込み可能性

設計上の判断を始める前に、スキルを読み込めますか？

• runtime_contract.status は fail、unknown、または実行時に明示的に検証された pass ですか？
• 必須のフロントマター項目はそろっていますか？
• description はローダーの上限内ですか？
• このレイヤーが fail の場合は、設計品質を評価する前に重大なブロッカーとして報告してください。
• unknown の場合は、実行時の読み込み可能性が未検証であることを伝えてください。静的なブロッカーがないことを、合格と判断してはいけません。

2. フロントマターと見つけやすさ

スキルの説明は十分ですか？エージェントは必要なときに見つけられますか？

• description に明確な起動条件が記載されていますか？
• name は規約に沿っていますか？
• エージェントとして、説明だけを見てこのスキルをいつ呼び出すべきか判断できますか？
• disable-model-invocation やユーザーのみが呼び出せる設定など、公式の呼び出し制御によって、カナリア観測の回数が少ない理由を説明できますか？

3. 構造の品質

スキルの目的は効果的に伝わっていますか？

• 使用するタイミングが明確に示されていますか？
• 指示は具体的で、曖昧ではありませんか？
• スコープは適切ですか（ひとつの役割を適切に果たしているか、または詰め込みすぎていないか）？

4. サイズとコンテキストコスト

現在のタスクでコンテンツが必要か、また使用時に利用可能かを確認してください。

• 長さだけでは、無駄の証拠にも削除を正当化する根拠にもなりません。
• 有用な専門知識、例、復旧手順、まれに必要となる重要な動作は維持してください。
• タスクに関係のない処理に負担をかける大規模なモード固有の手順は、参照可能な場所へ移してください。その際、利用するワークフローから引き続き参照できることを確認してください。
• コスト削減を主張する場合は、ファイルの長さではなく、測定された実行時の証拠に基づいてください。

5. 鮮度

古いことは、悪いことを意味するわけではありません。多くのスキルは安定しており、更新が不要です。

• 古さ（設定可能。デフォルトは180日）は、シグナルであり、結論ではありません。
• 次の点と照らし合わせてください。スキルは今も有用ですか？非推奨のツールを参照していませんか？
• 1年前のスキルでも、問題なく動作するなら健全です。

6. リンクの整合性

• シンボリックリンクのリンク先は有効ですか？
• 壊れたシンボリックリンクは、ソーススキルがインストールされていないか、移動されたことを示します。
• スキルやファイルへの内部参照は解決できますか？

7. バックアップとアーカイブの残存物

名前に .backup.、.disabled-、.old を含むディレクトリは、アップグレード後の残存物である可能性があります。

• これらは参考情報です。ユーザーが意図的に保持している可能性があります。
• 報告してください。自動で削除してはいけません。

8. セキュリティ上の兆候

次の内容を含むスキルにはフラグを立ててください（自動修正はしないでください）。

• ハードコードされたシークレットやトークン
• ダウンローダーの出力を sh や bash に直接渡すなど、パイプ経由でシェルにインストール処理を渡すパターン
• / を起点とする破壊的なファイルシステムコマンド、または自動化されたブロック内の特権シェルコマンド
• これらは人によるレビューが必要であり、自動削除してはいけません。

9. 来歴

スキルはどこから来たものですか？

• npx/npm 経由でインストールされた場合（標準的な方法）は、ソースリポジトリが判明しているか確認してください。
• 生成されたコンテンツも手書きのコンテンツも、同じ基準で評価してください。目的、利用者、現時点での正確性、置き換えや復旧の方法を確認します。
• 作成者、経過年数、観測された使用頻度の低さだけでは、不要とは判断できません。出自にかかわらず、有用なドメイン知識や、まれに必要となる重要なワークフローを維持してください。
• サードパーティ製（cursor の組み込み機能など）の場合、独自の更新メカニズムがあることがあります。
• スキャナーが報告するのは、ローカルで確認できる来歴の兆候だけです。ソース URL がないことや、パッケージのメタデータが不明なことは、不確実性として扱い、失敗と判断しないでください。

結果の提示方法

構造化された表を使ってください。重大度別にまとめる前に、確認済みの所見とレビュー用のシグナルを区別してください。スキャナーのカテゴリを結論として扱ってはいけません。

重大（対応が必要）

実行時のブロッカー、確認済みの壊れたシンボリックリンクや必須参照、検証済みのセキュリティ上の欠陥が該当します。未確認のセキュリティパターンは、証拠と不確実性を明記したレビュー待ちの項目に残してください。

参考（レビューを推奨）

バックアップの残存物、経過年数、サイズ、観測データの欠如は、レビュー時の参考情報です。それらだけで価値が低いと判断したり、スキルを変更する理由にしたりしてはいけません。

情報

統計、トポロジーマップ、プロベナンスの分布。

ガードレール

• トランザクションワークフローの代わりに、スキルを削除、消去、または手動で移動してはなりません。 廃止する場合は、ユーザーの明確な確認を得たうえで、クリーンアップ CLI を通じてのみ行ってください。
• 独立した作成元／ソースリポジトリを変更してはなりません。隔離できるのは、レビューによって特定されたインストール済みまたは配布済みのエントリーのみです。
• REHYDRATED と報告されたエントリーを、自動的に再隔離してはなりません。
• 確信が持てない場合は、確認できたことを提示し、ユーザーに判断を委ねてください。
• 「これは壊れている」（証拠に基づく）と「古くなっている可能性がある」（ヒューリスティックに基づく）を区別してください。
• ユーザーのスキルには、十分に理解できていないワークフローが含まれている可能性があることを尊重してください。
• スキャンスクリプトがデータを提供し、あなたが知見を提供します。

統合

• 特定の cwd からファイルシステム上の検出候補を調べるには skill-debug probe を使用し、ネイティブな検出は別途確認してください
• 記録されたカナリアの有効化を示す証拠と照合するには skill-debug dashboard を使用してください
• 個々のスキルを深く分析し、設計品質を評価するには skills-refiner を使用してください