skill-debug

skill-debug

あなたはスキルの可観測性を支援するアドバイザーです。スキルについてローカルにどのような証拠があるかをユーザーが理解できるよう支援します。具体的には、検出される可能性のある場所、カナリアの有効化、使用パターンなどです。これらのシグナルを、プラットフォーム上で読み込まれたこと、指示に従ったこと、または成果の品質を証明するものとして過大に評価しないでください。

基本方針

1. 推測せず、観察する。 ツールはスキルの検出と有効化に関する事実を収集します。パターンを解釈し、ユーザーの実際の経験と照らし合わせてください。
2. 構成を尊重する。 スキルは ~/.agents/skills/ にインストールされ、エージェントのディレクトリにシンボリックリンクされます。同じソースを指すシンボリックリンクは配布リンクであり、重複ではありません。プローブでは、シンボリックリンクと実際の重複を区別する必要があります。
3. 誤報を避ける。 有効化が観察されていないスキルは、単に必要とされなかっただけかもしれません。「観察されていない」ことも観察結果であり、結論ではありません。削除を推奨する前に、ユーザーの実際のワークフローと照合してください。

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

シェルアクセスがあり、ユーザーが検出診断、有効化統計、またはスキルの全般的なヘルススナップショットを求めている場合：

• ユーザーに手動実行を指示するのではなく、読み取り専用スクリプト（skills-refiner-doctor.sh、skill-probe.sh、skill-dashboard.sh）を自分で実行することを優先してください。
• ユーザーがカナリアトレースのためにディスク上のスキルを変更するよう明示的に求めない限り、skill-trace.sh --inject / --inject-dir / --strip / --strip-dir は実行しないでください。

読み取り専用のワンショットスナップショット：

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

問題

エージェントスキルは、設計上「設定したらあとは任せる」ものです。インストールしたら、エージェントが見つけてくれることを期待するしかなく、確認できる方法は限られています。

• この診断ツールがスキャンできるローカルの検出対象に、スキルは存在していますか？
• スキルに基づく実行中に、カナリアコマンドは観察されましたか？
• エージェントはスキルの指示に従っているように見えましたか？
• インストール済みのスキルのうち、カナリアイベントが観察されたものと、ローカルでカナリアの証拠がないものはどれですか？

このスキルは、これらの問いに関する証拠を収集するための3層デバッグアーキテクチャを提供します。判断はあなた自身で行ってください。

クイックスタート

# Read-only bundle: probe + dashboard + hygiene scan (does not inject traces)
bash ~/.agents/skills/skill-debug/bin/skills-refiner-doctor.sh

デフォルトのdoctorターミナル出力は、簡潔なガバナンスサマリーです。サブツールのターミナルレポート全体が必要な場合に限り、--raw を使用してください。ターミナルのラベルを中国語にするには --lang zh を使用します。JSON出力では安定した英語のキーが維持され、product_version: "2.0" が含まれます。skills-refiner.doctor.v2 などのスキーマ文字列は互換性のバージョンであり、製品のリリース番号ではありません。

選択的インストールの仕様：skill-debug はプローブ、ダッシュボード、トレース、カナリアの各操作を単独で実行できます。doctor は、skill-hygiene がインストールされている場合にそれも使用します。インストールされていない場合でも、doctor --json は steps.hygiene.status: "unavailable" を含む有効な部分オブジェクトを返し、終了コードは 1 になります。この部分的なスナップショットを、完全なガバナンススキャンとして提示しないでください。

# Layer 1: What local skill surfaces are likely discoverable right now?
bash ~/.agents/skills/skill-debug/bin/skill-probe.sh

# Layer 2: Inject activation canaries into skills
bash ~/.agents/skills/skill-debug/bin/skill-trace.sh --inject ~/.agents/skills/my-skill/SKILL.md

# Layer 3: View canary observation dashboard
bash ~/.agents/skills/skill-debug/bin/skill-dashboard.sh

3層デバッグアーキテクチャ

ネイティブのプラットフォームシグナルを優先

ネイティブのエージェントシグナルが存在する場合は、それを優先してください。このスキルはローカルの証拠不足を補うものであり、プラットフォームのテレメトリーに取って代わるものではありません。

プラットフォーム	ネイティブシグナル	このリポジトリの範囲
Claude Code	OpenTelemetry のメトリクス／イベント／トレース。設定されている場合は、スキルの有効化やツールのスパンを含みます	skill-probe --doctor はローカルの OTel 環境の状態を報告します。カナリアは引き続きフォールバック／プロキシです
Codex	.agents/skills、~/.agents/skills、管理者／システムのスコープ、シンボリックリンクの追跡、agents/openai.yaml の呼び出しポリシーからのネイティブなスキル検出	ローカルの配置場所とメタデータを報告します。実行時の有効化を主張しないでください
OpenAI Agents SDK	SDK の実行に対するアプリのワークフロー追跡：生成、ツール、ハンドオフ、ガードレール、カスタムスパン	独立した SDK シグナルです。Codex／IDE によるスキル読み込みの証拠ではありません
Cursor	ルール、メモリー、MCP 設定、Agent Skills、エージェントのターミナルコンテキスト	ローカルのルール／スキル／MCP の有無を報告します。完全なトレースエクスポーターが文書化されているとは想定しません
Pi 0.86.0	ネイティブのパッケージリゾルバーとスキルローダー	pi-skill-catalog.mjs は、ユーザースキルの検出、選択されたパス、無効化されたパス、警告を観測します。プロジェクト／パッケージ／CLI リソースとワークフローの実行は、このプローブの対象外です

Pi のユーザースキル検出

Pi の起動時の警告を調べるには、SKILL.md ファイルだけがカタログに入ると決めつけず、インストール済みのランタイムを使用してください。

node ~/.agents/skills/skill-debug/bin/pi-skill-catalog.mjs \
  --pi-package /absolute/path/to/node_modules/@earendil-works/pi-coding-agent --json

エントリーポイントは自己完結型で、Pi 0.86.0 にバージョンが固定されています。この Pi のインストール環境でサポートされている Node ランタイムを使用してください。--settings /absolute/candidate.json は、候補のユーザー設定を書き込まずに確認します。ローカルリソースのパスは、解決の基準として実際のエージェントディレクトリを保持します。終了コード 0 は、報告された警告を含め、観測が完了したことを意味します。カタログが問題なく、または実行時の適合性が確認されたことを証明するものではありません。終了コード 3 は、サポートされていない Pi のバージョンまたは設定済みのパッケージを報告します。これらは、そうしなければインストールを開始する可能性があります。その他の失敗では終了コード 2 になります。拡張機能もモデル呼び出しも実行されません。

Pi は、共有グループディレクトリ内の説明が空でない通常の Markdown ファイルを検出し、無効な名前や長すぎる説明を警告付きで保持する場合があります。観測されたパスを、意図したスキルエントリーと比較してください。参照用／テンプレート用のリソースが公開されていることを確認した場合は、Pi のユーザー settings.json で、正確なリソースサブツリーを !<absolute-directory>/** により除外してください。参照ファイルは引き続き読み取り可能な状態にしてください。ホスト固有のバリアントが存在することを確認した場合は、優先されるパスと内容を確認した後に限り、-<absolute-loser-SKILL.md> を使用してください。オーバーライドパターンでチルダが展開されると決めつけたり、どちらかのバリアントを削除したり、プレースホルダーを有効なスキル名に変更したりしないでください。既存の skills 配列にマージし、候補のカタログと実際のカタログを比較して、保持されるすべての識別情報を確認してください。ネイティブのディレクトリ警告、本文へのアクセス、タスクの結果は、それぞれ別個の事実です。

正確性の契約

このスキルは、ローカルの証拠については正確な件数を算出できます。対象パスで検出可能なファイル数、正規化されたスキル識別情報、シンボリックリンクの分布、リンク切れの数、記録されたカナリアの JSONL イベント数が該当します。プラットフォームが実行時のイベントをエクスポートしない限り、実際の検出、読み込み、指示への従順さ、有用性を正確に数えることはできません。ネイティブテレメトリーがない場合、カナリアの統計はプロキシによる観測にすぎません。

レイヤー 1：検出診断（skill-probe）

回答：「ここからアクセスできる、検出対象になりそうな場所にあるローカルスキルファイルはどれですか？」

bash ~/.agents/skills/skill-debug/bin/skill-probe.sh [--cwd /path/to/project] [--verbose]

機能：

• 一般的なローカルスキルディレクトリ（.warp/skills/、.agents/skills/、.claude/skills/、.codex/skills/、.cursor/skills/、.gemini/skills/、.copilot/skills/、.factory/skills/、.github/skills/、.opencode/skills/）をスキャンします
• プロジェクトレベル（cwd → リポジトリルート）とグローバル（~/）の両方の場所を確認します
• スキル名の競合（同じ名前でパスが異なるもの）を報告します
• 診断における検出の優先順位を表示します
• フロントマターが解析可能かどうかを検証します

出力：この診断で検出できるローカルスキルファイルを色分けして表示するターミナルレポートです。プラットフォーム固有の実行時検出結果は異なる場合があります。

レイヤー 2：有効化トレース（skill-trace）

回答：「エージェントは、このスキルに挿入されたカナリアコマンドに従いましたか？」

# Inject trace into one skill
bash ~/.agents/skills/skill-debug/bin/skill-trace.sh --inject ~/.agents/skills/my-skill/SKILL.md

# Inject trace into all skills in a directory
bash ~/.agents/skills/skill-debug/bin/skill-trace.sh --inject-dir ~/.agents/skills/

# Remove traces
bash ~/.agents/skills/skill-debug/bin/skill-trace.sh --strip ~/.agents/skills/my-skill/SKILL.md

# Remove all traces
bash ~/.agents/skills/skill-debug/bin/skill-trace.sh --strip-dir ~/.agents/skills/

仕組み：

• スキルに軽量な「カナリア」プリアンブルブロックを挿入します。以下は概念的な構造であり、生成されたコマンドを実行可能な形でコピーしたものではありません。

## Activation Canary Trace (auto-injected by skill-debug)


When this skill is used, run this canary command first:
\`\`\`text
_skill_debug_helper="/abs/path/to/skill-debug/bin/skill-canary.sh"
if [ -f "$_skill_debug_helper" ]; then
  bash "$_skill_debug_helper" "/abs/path/to/SKILL.md"
else
  # Generated block uses a compact secure fallback: require real, non-symlink
  # debug/log paths; set 0700/0600; append one degraded JSON event or fail closed.
  secure_degraded_append_or_fail_closed
fi
\`\`\`

• トレースは短い bash ブロックで、エージェントが挿入された指示に従った場合に観測できます
• このブロックは、ID ハッシュを計算する唯一の実装である bin/skill-canary.sh に処理を委譲します。挿入されたファイルに正規化アルゴリズムの固定コピーが含まれることはないため、以前に挿入されたカナリアが孤立することなくアルゴリズムを変更できます。
• 各イベントには、正規化された SKILL.md パスと正規化済みコンテンツハッシュから導出されたローカル ID キーが含まれます。自動挿入されたカナリアブロックはハッシュの対象外のため、挿入／除去を繰り返しても以前の観測結果が孤立することはありません。
• ヘルパーが見つからない場合（たとえば、挿入後に skill-debug がアンインストールされた場合）、ブロックはサイレントに失敗するのではなく、劣化した名前のみのイベント（trace_kind: "canary_degraded"、空の identity_key）を追記します。
• ~/.agents/debug または activation.jsonl がシンボリックリンクの場合、カナリアの書き込みはフェイルクローズします。ヘルパーがこれらのリンクをたどったり、リンク先の権限を変更したりすることはありません。
• Windows Git Bash/MSYS2/Cygwin 環境、および WSL 2 で HOME が /mnt/<drive> 配下にある場合も、カナリアの書き込みはフェイルクローズします。これらの環境では、文書化された 0700／0600 のプライバシー要件を保証できないためです。対応する POSIX ファイルシステムでは、ヘルパーはシンボリックリンクになっているパス構成要素を拒否し、chmod 後に実効モードを検証します。Windows で完全な可観測性を実現する想定環境は、専用ランナーによる認証待ちの、HOME が Linux ファイルシステム上にある WSL 2 です。
• オーバーヘッドは最小限です。観測されたカナリアごとにハッシュ計算 1 回、追記 1 回です
• すべてのトレースに、ディスク上から削除できることが明示されています
• 存在する場合は、カナリアコマンドに従ったことを意味します。存在しない場合は判断できず、スキルが検出、読み込み、または活用されなかった証拠にはなりません。

レイヤー 3：カナリア観測ダッシュボード（skill-dashboard）

回答：「カナリアの有効化が観測されたスキルはどれで、観測されていないスキルはどれですか？」

bash ~/.agents/skills/skill-debug/bin/skill-dashboard.sh [--json] [--days 30]

レポート内容：

• カナリアイベントの頻度 — スキル ID ごとの観測されたカナリアイベント数
• 最後に観測されたカナリア — 記録された最新のカナリアのタイムスタンプ
• コンテキストの分布 — 記録されたカナリアイベントの cwd の分布
• カナリア観測済み ID の割合 — インストール済みスキル ID のうち、カナリアイベントが記録された ID の割合
• 未観測リスト — 記録されたカナリアイベントがゼロの、インストール済みスキル ID
• 最も多く観測されたスキル — 観測されたカナリアイベントが最も多い ID

包括的なヘルスチェック

# Run all three layers + hygiene scan
bash ~/.agents/skills/skill-debug/bin/skill-probe.sh --doctor

--doctor モードは、以下を組み合わせます。

1. 検出プローブ（レイヤー 1）
2. ネイティブプラットフォームのシグナルチェック（Claude Code の OTel 環境変数、Codex／Cursor のローカルサーフェス、OpenAI Agents SDK のトレーシング環境変数）
3. 有効化ログの分析（レイヤー 3）
4. 利用可能な場合は、skill-hygiene のスキャン結果との相互参照

結果の解釈

検出の問題

• 「スキルが検出パスにない」 — スキルが、現在の cwd を起点としてこの診断がスキャンするローカルパスの外にあります
• 「名前の競合」 — 同じ名前のスキルが 2 つ以上あります。エージェントは優先順位に基づいて選択するため、誤ったスキルが選ばれる場合があります
• 「無効なフロントマター」 — 解析エラーにより、エージェントがスキルをスキップする場合があります

有効化の問題

• 7 日以上経過しても Canary が一度も観測されない — スキルがトリガーされていない、必要とされていない、または Canary に従っていない可能性があります
• Canary は観測されたが、出力の品質が低い — スキルの指示が不明確、または範囲が広すぎる可能性があります
• Canary の数は多いが、出力の品質が低い — スキルは頻繁に使われていても、設計の改善が必要な可能性があります

使用パターン

• Canary の観測同一性率が 30% 未満 — Canary の観測率が低いため、skill-hygiene でワークフローのコンテキストを確認してください。このしきい値はトリアージ専用であり、品質や成果のしきい値ではありません。
• グローバルパスにある単一プロジェクト向けのスキル — プロジェクトレベルのスコープのほうが明確かどうか確認してください
• グローバルスキルが観測されない — 自動アーカイブの対象ではなく、人による確認を推奨する候補です

ガードレール

• トレースの挿入は、--strip を使えば、末尾に改行がないファイルも含め、ディスク上でバイト単位に元に戻せます。変換またはメタデータ復元に失敗した場合、対象は変更されません。現在のエージェントセッションには、会話コンテキストが更新されるまで、すでに読み込まれたスキルのテキストが残る場合があります。
• すべてのログデータは、実際の（シンボリックリンクではない）~/.agents/debug/ ディレクトリ内にローカル保存されます。ディレクトリのモードは 0700、activation.jsonl のモードは 0600 です。
• シェルの完全なサポートは、macOS でネイティブに検証されています。Linux ファイルシステム上の HOME を使用する WSL 2 は設計上サポートされていますが、専用ランナーではまだ認定されていません。Git Bash の対象範囲は、実ディレクトリに対する読み取り専用のガバナンスとトレースファイルの変換に限られます。シンボリックリンク／ジャンクションの構造、Canary のログ記録、ネイティブの PowerShell／cmd は、サポート対象として保証されていません。
• データが外部に送信されることはありません
• ダッシュボードは読み取り専用で、スキルファイルを変更することはありません
• 有効化ログは追記専用の JSONL です。--rotate フラグでローテーションしてください

統合

• 完全なガバナンスワークフローには、skill-hygiene と組み合わせてください：
  1. skill-debug probe → 対象の cwd におけるファイルシステム上の検出候補を調査します
  2. skill-debug dashboard → Canary の観測状況を確認します
  3. skill-hygiene scan → 事実を収集し、重大な指摘を確認します
  4. 既存の権限範囲内で改善し、廃止には hygiene のトランザクションフローを使用します
  5. 同じスコープで元の対象と失敗条件を再確認し、影響を受ける利用側を検証します

正規の対象／同一性バリアント、フィンガープリント、観測時刻、 スコープ、確認済みの失敗、期待される成功を引き継ぎ情報に含めてください。ログがない場合は no_data、コレクターの失敗は error とします。Doctor は、解析可能なサブツールの失敗出力を partial_payload として保持し、失敗を成功に変換しません。任意の raw terminal レポートは、それ以降に行われた観測です。終了コードがゼロであることや、変更後のスキャンに結果が含まれないことだけでは、元の指摘が解消された証明にはなりません。