skill-map

スキルマップ

このスキルは調整の対象外です。宣言された作業では ai-coord ゲートをスキップしてください。

macOS で保護されているホームパスや、明らかなトランスクリプト、キャッシュ、依存関係、バックアップのノイズをスキャンせずに、ローカルファイル内のスキルのインストールと参照を見つけます。

引数

• --root PATH：このルートをスキャンします。複数指定できます。デフォルト：~。
• --portfolio-root PATH：PATH を Git ルートとして解決し、そのリポジトリと既存の ~/.agents/skills および ~/.claude/skills をスキャンします。--root とは同時に指定できません。
• --skill NAME：レポートを1つのスキル名に限定します。複数指定できます。
• --format text|json|dot：レポート形式を選択します。デフォルト：text。
• --include-catalog-sources：広範なスキャンに、~/projects/agent-skills、~/sablier/sablier-skills、~/sablier/agent-skills などの既知のローカルソースチェックアウトを含めます。これらのツリー内で明示的に指定された --root は、常にスキャンされます。
• --include-self：依存関係の出力に自己参照を含めます。
• --include-snippets：完全一致する行が結果を大きく改善する場合、一致した参照テキストを含めます。簡潔で有用な情報を優先するため、デフォルトの出力ではスニペットを省略します。
• --show-skipped：テキストまたは JSON の出力に、無視されたパスの概要を含めます。

ワークフロー

1. ai-skillet 1.0.0 以降が PATH 上にあることを確認してから、次を実行します。

   ai-skillet map
   

   解析した各オプションとその値を、それぞれ別の引数として追加し、引用符で囲まれた値をそのまま保持します。たとえば、--root '/path with spaces' --format json は2つのオプションを追加します。デフォルトを使う場合は、引数を指定しない形式を使用します。

2. 別のコマンドまたはエージェントが結果を処理する場合は、--format json を使用します。

3. リポジトリのスキルと、ユーザーがインストールした Codex および Claude Code の公開状況を比較する場合は、--portfolio-root <repo> --format json を使用します。より広いホームディレクトリのルートは追加しないでください。

4. ユーザーからグラフ、Graphviz 入力、または依存関係の可視化を求められた場合は、--format dot を使用します。

5. 完全一致する行が結果を大きく改善する場合は、ユーザーが表示を求めた場合も含めて、--include-snippets を使用します。

6. 無視ポリシーの説明、監査、または変更を行う場合に限り、references/ignore-policy.md を読みます。

ユーザー向け出力

JSON と DOT はバイト単位で有効な形式のまま、装飾せずに出力します。人が読む出力では、### 🗺 Skill Map — <skills> skills · <duplicates> duplicates · <unresolved> unresolved から始め、スキル／依存関係／重複／未解決項目の簡潔な概要表を続けます。実際にスキャンしたルートと、重要な除外項目を必ず明記します。デフォルトの広範なスキャンでは、標準のエージェントホームとカタログのソースチェックアウトを除外したことを明示します。明示的に指定した --skill フィルターに一致するものがない場合は、何もないマップを問題がないように見せるのではなく、⚠️ Not found として表示します。セクションラベルは必要最小限にし、スニペット、ローカルパス、正確なエッジ、コマンド、診断情報には装飾を加えません。

出力の意味

ai-skillet map はスキーマバージョン 1 を出力します。テキストは人が読みやすい形式、JSON は利用側向けの構造化形式、DOT は Graphviz の入力形式です。

• すべてのエッジには、type、provenance、identifier、source、target、path、line が含まれます。依存関係の根拠には、provenance: declared または inferred を使用します。宣言された根拠と推論された根拠は、同じソースとターゲットを記述していても、独立したレコードとして扱われます。宣言された識別子は、裸の形式または ORG/REPO#SKILL 形式を保持します。
• external-reference レコードは、検出されたスキルの外部への参照を記録します。unresolved-like-reference レコードは、検出されたスキルと一致しなかった、明示的な $kebab-name または /kebab-name 形式のトークンを記録します。
• counts は、宣言された依存関係、推論された依存関係、外部参照、重複、未解決の参照を個別に集計します。--skill フィルターに一致するものがない場合は、stderr に警告を書き込み、フィルター適用後の空のレポートを返します。
• スキルフィルターは、宣言元とターゲットのスキル名に一致します。外部識別子の場合は、# の後ろにある名前も対象です。宣言フィールドが無効な場合、マッパーはパス固有のエラーを出して停止します。
• すべてのスキルレコードには skill_sha256 と tree_sha256 が含まれます。ツリーハッシュの対象は、ソート済みの相対パス、エントリーの種類、通常ファイルの実行ビット、ストリーム読み込みしたファイルバイト、追跡しないシンボリックリンクのターゲットです。

ポートフォリオ JSON には、さらに以下が含まれます。

• portfolio.repository_root と、各ルートが公開するクライアントを含む、存在するユーザールートおよび存在しないユーザールート。
• スキルごとの、解決済みの realpath に加えた字句的な exposure_path、directory_name、リポジトリまたはユーザーの location、インストールまたはカタログの kind、該当する clients。
• 認識されたスキルディレクトリのシンボリックリンクに対する is_symlink と字句的な symlink_target。同じ実ディレクトリに解決される公開先も、それぞれ別のスキルエントリーとして扱われますが、インストールの重複とみなすには、異なる実ディレクトリである必要があります。自動選択されるユーザールートは、明示的に指定されたルートと同様に扱われます。広範なホームディレクトリの無視ポリシーによって、明示的な ~/.agents/skills または ~/.claude/skills ルートが除外されることはありません。ポートフォリオの走査でシンボリックリンクをたどるのは、認識されたリポジトリまたはユーザーのスキルルート直下にある場合に限られます。それ以外のリポジトリ内のシンボリックリンクはたどりません。

--show-skipped を使用すると、設定で無視されたディレクトリ、ファイル、保護対象のホームパス、キャッシュ、カタログソースの除外対象が、テキストまたは JSON の出力に含まれます。

関連スキル

• skill-map はスキルの場所を特定して相互参照するだけで、検証は行いません。カタログまたはインストール済みルートのメタデータやドキュメントリンクの問題を監査するには、インストールされている場合は skill-doctor スキルを使用してください。
• マッピングされたリポジトリ中心のポートフォリオについて、競合、乖離、統合、または不足しているワークフローを評価するには、手動で呼び出す skill-harmonization スキルを使用してください。

ガードレール

• ai-skillet map による除外後は、ユーザーがトランスクリプトや履歴の分析を明示的に依頼しない限り、トランスクリプトやバックアップのディレクトリを手作業で検索しないでください。
• ホームディレクトリのスキャン対象を、~/Library や ~/.Trash などの macOS 保護対象パスに広げないでください。広範囲のスキャンで網羅性を高める必要がある場合は、代わりに対象を絞ったルートを明示的に渡してください。
• マシンを広範囲にスキャンする際は、ローカルのスキルカタログのソースチェックアウトを誤検出として扱ってください。カタログの内容を監査する場合は、--root として明示的に渡してください。
• レポートは重要度の高い情報に絞ってください。正確な根拠が実質的に役立つ場合、またはユーザーが明示的に求めた場合に限り、スニペットを含めてください。出力を公開用または第三者向けの成果物にコピーする前に、外部への情報開示に関するレビューを実施してください。
• 場当たり的なシェルフィルターを使うのではなく、ai-skillet で無視ルールを管理し、その理由を references/ignore-policy.md に記載することを優先してください。