Agent Skills がなぜ動作しない？2026年 Claude Code のスキル起動と権限のトラブルシューティング

Agent Skills が動作しない場合は、モデルやクライアントを再インストールする前に、発見、起動、ツール実行の3層を最小Skillで切り分けるのが最も確実です。Claude Codeの公式配置に合っていても、説明文の条件、プロジェクトの信頼範囲、ReadやBashなどの権限が合わなければ、Skillは表示されても実処理まで進みません。

この切り分けが必要な開発者

Claude CodeのSkillが起動しない状態を、ディレクトリ、frontmatter、ログから順番に調べたい開発者向けの記事です。
チームのカスタムSkillを共有リポジトリやリモートMacへ配布するエンジニアは、権限と信頼境界の節を重点的に確認してください。

AI Coding Agentの運用を担当する技術責任者には、最後の受け入れチェックリストが、Skillを本番コードへ投入する前の共通基準になります。

最初に故障層を3つへ分ける

Agent Skillsが動作しないとき、最初に「何も起きない」という表現を分解します。次の表で、観測された症状と確認箇所を対応させると、不要な再インストールを避けられます。

故障層	典型的な症状	最初に確認する箇所	次の判断
発見されない	Skill名が候補に出ず、説明も表示されない	プロジェクトルート、ディレクトリ階層、SKILL.mdの名前	パスと形式を修正する
起動されない	Skillの説明は見えるが、要求に対して本文が使われない	description、作業要求との一致、現在のコンテキスト	再現可能な要求文で試す
実行に失敗する	Skillは読み込まれたが、ファイル操作やMCP呼び出しで止まる	Read、Write、Bash、MCP、確認ポリシー	権限と作業領域を狭く調整する

公式のAgent Skills仕様では、Skillは定められたディレクトリ構成とSKILL.mdを中心に扱われます。一方、Claude Codeの読み込み範囲は公式Skillsドキュメントに依存するため、別のAI Coding Agentへ同じフォルダをコピーすれば必ず動く、とは判断できません。

最小Skillで発見だけを確認する

最初から大量の指示、スクリプト、MCP接続を含めると、失敗箇所が分からなくなります。本文には固定の識別文だけを書き、外部ファイルの読み込みやシェル実行を含めない最小構成にします。

そのSkillが一覧や候補として認識されるなら、発見層は通過しています。認識されない場合は、モデルの性能ではなく、プロジェクトルート、配置規則、ファイル名、frontmatterを優先して調べます。

配置とfrontmatterを順番に検査する

Claude CodeのプロジェクトSkillでは、まず現在の作業ディレクトリが想定したリポジトリのルートかを確認します。ターミナルを別の親ディレクトリで開いていたり、リモートワークスペースがサブディレクトリだけをマウントしていたりすると、ローカルでは正しく見えるSkillがAgent側から見えないことがあります。

次の表は、配置とファイル形式を確認するための簡易基準です。

確認対象	正常と判断する条件	失敗しやすい例	修正方針
Skillのディレクトリ	対象Agentが認識するプロジェクト配下にある	.claude/skills/team/audit/skill/のように不要な階層が増えている	公式構成に合わせて階層を減らす
本文ファイル	ファイル名がSKILL.mdで、大小文字も一致する	skill.md、SKILL.MD、拡張子の重複	ファイル名を正確に戻す
YAML frontmatter	開始・終了区切りと必須フィールドが正しい	コロン、インデント、区切りの欠落	最小の値で再作成する
プロジェクト境界	Agentが実際に開いているルートから参照できる	ローカルとリモートでマウント先が異なる	実行中の作業ディレクトリをログで確認する

特にfrontmatterのエラーは、本文に有用な指示が書かれていても、本文まで解析されない原因になります。説明文を長くする前に、名前と説明だけの小さなfrontmatterで読み込みを確認し、通過後に指示を追加してください。

Claude Codeの公式Skills仕様と対象Skillの現在のリポジトリ構成を照合し、過去の記事やコミュニティ投稿だけでパスを決めないことも重要です。公式仕様が更新された場合、以前動いていた配置が現在の推奨方法とは限りません。

起動条件を再現テストで確かめる

Skillが表示されたのに呼び出されない場合、発見と起動を混同しないことが重要です。descriptionが広すぎると無関係な要求でも候補になり、狭すぎると実際の依頼で条件に一致しません。ほかのSkillと説明が重複している場合は、Agentが別のSkillを選ぶこともあります。

テスト文は、次のように3種類へ分けます。

• そのSkillが必ず扱う具体的な依頼
• 似ているが別のSkillが扱う依頼
• 対象外であり、起動してはいけない依頼

同じリポジトリ、同じ作業ディレクトリ、同じ権限状態でこの3種類を試し、説明文だけを一度に変更します。要求文と結果を保存すれば、Skillの更新後にも起動条件を比較できます。

ここで「Skill名が表示された」だけなら、まだ成功とはいえません。本文の識別文が読み込まれたか、指示に沿った応答になったか、必要なツール呼び出しが発生したかを別々に記録します。Claude Code以外のCodexやOpenCodeでは、Skillの発見や起動の実装が異なる可能性があるため、同じテスト結果をそのまま互換性の証拠にしないでください。Codexについては、公式のSkill評価に関する説明も確認対象になります。

権限と信頼境界を最小範囲で戻す

Skillが本文まで読み込まれた後に止まるなら、次はツール実行の層を調べます。Readが拒否されれば対象ファイルを取得できず、Writeが制限されれば修正結果を保存できません。Bashはコマンドの副作用が大きく、MCPは外部サービスや追加のデータ源へ接続するため、同じ「権限不足」でも影響範囲が異なります。

Claude Codeの権限判定は、公式の権限ドキュメントにある設定と実行環境の境界を確認してください。Skillの指示に「許可を自動承認する」と書かれていても、文章だけで実行ポリシーを変更できるとは限りません。

第三者Skillを受け取った場合は、次の順番で確認します。

• SKILL.mdが要求しているファイル操作とコマンドを読む
• 参照されるスクリプトや設定ファイルを開く
• WriteやBashが必要になる理由を確認する
• MCP接続先と送信される情報を確認する
• 本番リポジトリではなく、破棄可能な検証用プロジェクトで実行する

MCPを使うSkillでは、MCP SDKの公式ドキュメントにある現在の接続方式と対象ツールを確認します。さらに、管理対象Agentでのツール制御については公式の受管制ツール説明を参照し、Skillの指示と実際の許可設定を混同しないようにします。

リモート環境では交付経路を分けて確認する

ローカルプロジェクトで動作するSkillを、リモートMacやクラウド開発環境へ移した途端に失敗する場合、Skill本体ではなく交付経路が原因になりがちです。リポジトリに含めたのか、起動時に別途コピーしたのか、ワークスペースのマウント対象に含めたのかを記録してください。

特に確認すべき点は、Agentが開いているルートと、開発者が確認したルートが同じかどうかです。コンテナや仮想ワークスペースでは、ホスト側の.claude/skillsが内部へ自動的に共有されるとは限りません。

チーム運用では、Skillの変更を本番コードと同じタイミングで反映しない方法が安全です。検証用ブランチまたは専用ワークスペースへ先に配布し、発見、起動、ツール操作を確認した後に、利用者と対象リポジトリを広げます。変更履歴、承認者、ロールバック対象を残しておけば、説明文の変更だけで起動先が変わった場合も追跡できます。

5項目の受け入れチェックで回帰を防ぐ

新しいSkillを登録するときは、インストール完了ではなく、次の受け入れ項目をすべて通過した状態を公開可能とします。

• [ ] 対象Agentの公式構成でSkillが発見される
• [ ] 対象内、類似、対象外の要求文で起動結果を比較できる
• [ ] 本文の読み込みとツール呼び出しを別々に確認できる
• [ ] Read、Write、Bash、MCPの必要範囲と確認操作が明記されている
• [ ] 変更前のコミット、Skillの版、失敗時の戻し方が残っている

このチェックリストは、単に「動いた」という印象を避けるためのものです。特に、敏感なファイルの読み取りや外部サービスへの送信が発生するSkillでは、正常系テストだけでなく、権限を与えなかった場合に安全に停止することも確認してください。

長時間使うリモートMacを検証環境にする場合は、運用中のコードベースとは別にSkill試験用の小さなプロジェクトを維持します。Macのレンタル環境を含む開発基盤の選び方は、ZutcloudのMac環境案内でも利用条件を確認できます。

よくある疑問を故障層ごとに整理する

FAQでは、発見、起動、実行、権限を混ぜずに確認することが重要です。原因が異なるため、同じ修正を繰り返すより、最後に成功した層を記録した方が復旧が速くなります。

結論として、再インストールより小さく戻す

Agent Skillsが動作しない問題は、モデルを変更したり、すべてのプラグインを入れ直したりする前に、最小Skill、正しいプロジェクトルート、簡潔なfrontmatter、再現可能な起動文、最小権限という順番で確認してください。Claude Code、Codex、OpenCodeは同じSkillという名称を使っていても、配置規則や権限モデルまで同一とは限らないため、対象Agentの公式資料を基準にする必要があります。

ローカル環境は初期検証には向いていますが、チームで共有する場合は端末ごとの差、権限設定のばらつき、作業ディレクトリの違いが障害になります。既存の開発環境だけで試し続けると、再現条件を保てず、Skillの更新が本番コードへ直接影響する点も弱点です。

一方、Macをその都度用意する方法は、初期設定、利用期間、物理端末の管理、担当者ごとの権限差が負担になります。長期の固定負荷や専用の物理インターフェースが必要なら自前環境が適しますが、短期間のSkill検証、複数環境の比較、遠隔からのAI Coding Agent実験であれば、ZutcloudのMac環境を使って検証用ワークスペースを分離する方が、切り分け条件を揃えやすくなります。運用前の相談や利用条件はZutcloudのヘルプセンターで確認できます。

FAQ

Claude Code が Agent Skills を認識しない場合、最初に何を確認すべきですか？

まずプロジェクトのルートディレクトリを確認し、その配下に想定した .claude/skills ディレクトリと各 Skill の SKILL.md が存在するかを調べます。ディレクトリを深くネストしすぎたり、ファイル名を変更したりすると、Skill の本文以前に発見されません。最小構成の Skill を置き、一覧や読み込みログで認識状態を分けて確認します。

Agent Skills の SKILL.md はどこに置けばよいですか？

Claude Codeでは、プロジェクト単位で使うSkillをプロジェクトの .claude/skills 配下に置く構成が基本になります。ただし、対象のClaude Code、Codex、OpenCodeが同じ配置規則を採用するとは限りません。利用するAgentの公式ドキュメントで、プロジェクト単位、ユーザー単位、プラグイン単位の配置範囲を確認してから共有します。

Agent Skills は起動したのに、ReadやBashなどのツールを使わないのはなぜですか？

Skillの説明が表示されたことと、本文の指示が読み込まれてツール実行まで進んだことは別の状態です。対象ファイルの場所、現在の作業ディレクトリ、許可されたツール、確認待ちの操作を個別に調べてください。ReadやBashが拒否されている場合、Skillの不具合ではなく、実行ポリシーや信頼設定が原因である可能性があります。

Agent Skills の権限と信頼境界を安全に確認する方法はありますか？

第三者から受け取ったSkillを、そのまま本番リポジトリや長時間稼働する環境に配置しないことが重要です。SKILL.mdの指示、参照されるスクリプト、要求されるRead、Write、Bash、MCPの範囲を確認し、最小権限の一時プロジェクトで試します。変更前のコミットを残し、失敗時に確実に戻せる状態で検証します。