skill-doctor

スキルドクター

ai-skillet の標準バリデーターを使って、サポートされている拡張スキル方言のローカルカタログとインストール済みスキルルートを監査し、要求された場合に限り、メタデータを最小限修正します。

引数

• --root PATH：このカタログまたはインストール済みスキルルートをスキャンします。複数回指定できます。デフォルトは現在の作業ディレクトリです。
• --skill NAME：診断と修正の対象を、このスキルディレクトリ名に限定します。複数回指定できます。
• --format text|json：レポート形式を選択します。デフォルトは text です。
• --fix-safe：agents/openai.yaml がない場合は作成し、policy.allow_implicit_invocation が一致しない場合は更新します。
• --dependencies-only：形式が不正、または解決できない skill-dependencies 宣言のみを報告します。--fix-safe と併用しないでください。

ワークフロー

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

   ai-skillet doctor
   

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

2. 別のコマンドまたはエージェントが結果を使用する場合は、JSON を使います。

   ai-skillet doctor --root . --format json
   

3. 検出結果を確認してから、安全な修正を実行します。

   ai-skillet doctor --root . --fix-safe
   

4. 手動で編集した後は、--fix-safe を指定せずに再実行します。

依存関係のみを対象とするカタログチェックを実行するには、次を実行します。

ai-skillet doctor --root . --dependencies-only

検出結果

• error の検出結果は、公開または同期を妨げるべきカタログの不備として扱います。
• warning の検出結果は、レビューが必要なカタログの衛生上の問題として扱います。
• JSON 出力では、構造化されたルート、件数、検出結果、安全な修正記録を含むスキーマバージョン1を使用します。各検出結果には、コード、重大度、パス、判明している場合は行番号、修正可能かどうか、メッセージが含まれます。
• Frontmatter の検証では、移植可能な Agent Skills のフィールド、Claude Code の拡張、リポジトリの拡張を、サポート対象の単一の統合仕様として受け入れます。不明なトップレベルフィールド、フィールド・項目・メタデータ値の無効な型、無効な列挙値、および context: fork を指定せずに使用されている agent または background を報告します。
• 明示的な disable-model-invocation: false と user-invocable: true は、有効なデフォルトを再指定するものであり、検出結果なしで受け入れられます。
• プロンプトの衛生に関する警告は助言のみを目的としており、自動修正されません。対象は、古くなったモデルの固定指定、無条件に参照するには大きすぎる Markdown、矛盾する要件・禁止表現、完了を示す証拠の不足です。
• 調整免除に関するエラーは報告のみを行います。coordination: exempt は、通常の Markdown の文章中にあるカタログ標準の coordination-exempt 文と併記する必要があります。インラインコード、フェンス付きまたはインデントされたコード、引用ブロック、および見出しが Example または Examples のセクションは宣言として扱われません。どちらも --fix-safe では修正されません。
• 依存関係のエラーは、配列以外、空、文字列以外、重複、不正な形式、誤った順序、自己参照、または解決できないローカル宣言を検出します。外部の ORG/REPO#SKILL 識別子は、ネットワークにアクセスせずに形式を検証します。
• メタデータ、OpenAI ポリシー、調整、リソース、README、プロンプトの衛生、CLI バージョンのチェックは、--dependencies-only 以外でも利用できます。
• 的確な修正箇所の確認には、JSON 出力の path と line を使用します。

安全な修正ポリシー

--fix-safe で実行できるのは、次の修正のみです。

• agents/openai.yaml がない場合に、SKILL.md から導出した policy.allow_implicit_invocation を含めて作成します。
• 既存の allow_implicit_invocation ブール値が disable-model-invocation と一致しない場合に更新します。

許可された各修正は、対象ファイルをステージングしてからアトミックに名前を変更して適用します。更新時は対象ファイルの権限を保持します。安全な修正に失敗した場合は、対象を部分的に書き換えずに終了コード3で終了します。

--fix-safe は、frontmatter、説明、README の行、references/version.txt、相対リンクを書き換えません。不明なフィールド、無効な型または値、フィールド間のエラー、調整に関する宣言は報告のみを行います。これらは手動で編集し、新たに監査を実行して確認してください。

関連スキル

• skill-doctor は渡されたルートのみを監査し、ルートを検索しません。マシン全体からスキルのインストール先、重複、および相互参照を探すには、ai-skillet map を使用してください。

終了コード

• 0：問題がない場合、または要求された安全な修正がすべて成功し、指摘事項が残っていない場合。
• 1：監査が完了し、指摘事項が残っている場合。運用上のクラッシュではなく、レビュー作業として報告してください。
• 2：引数が無効、または環境を読み取れない場合。
• 3：要求された安全な修正に失敗した場合。

ユーザー向けの出力

--format json の出力は、バイト単位で有効な JSON とし、装飾を付けないでください。人間向けの出力では、終了コード 2／3 の場合は ### 🩺 Skill Doctor — ⛔ blocked、問題がない場合は ### 🩺 Skill Doctor — ✅ clean、レビューが必要な場合は ### 🩺 Skill Doctor — ⚠️ review required で始め、その後にルートとエラー／警告／修正件数を簡潔な表で示してください。安全な修正と残りの指摘事項は別々に一覧表示してください。レビューが必要な結果、またはブロックされた結果の場合は、最後に手動で行う最小限の次のアクションを示してください。問題がない場合は、概要の後で出力を終了してください。パス、行番号、コード、生の指摘事項、コマンド、診断情報は正確に保持してください。