Agent Skillsが動かない？よくある問題と解決方法

Agent Skillsを使おうとしたら動かない…そんな経験はありませんか？

この記事では、よくあるトラブルと解決方法をまとめました。

スキルが認識されない

症状

• /skillsでスキルが表示されない
• スラッシュコマンドが効かない

確認ポイント

1. ディレクトリ構造は正しいか

Copy# ⭕ 正しい構造
~/.claude/skills/my-skill/SKILL.md

# ❌ 間違い：SKILL.mdが直接置かれている
~/.claude/skills/SKILL.md

# ❌ 間違い：skill.md（小文字）
~/.claude/skills/my-skill/skill.md

スキル名のディレクトリの中にSKILL.md（大文字）を配置します。

2. フロントマターは正しいか

Copy---
name: my-skill
description: スキルの説明
---

• nameとdescriptionは必須
• ---で囲まれているか確認
• YAMLの文法エラーがないか確認

3. 文字エンコーディングはUTF-8か

WindowsのメモなどでBOM付きで保存されていると認識されないことがあります。UTF-8（BOMなし）で保存してください。

スキルが自動適用されない

症状

• 自然言語で依頼しても、スキルが使われない
• 別のスキルが使われる

解決方法

1. descriptionをより具体的に

Copy# ❌ 曖昧
description: コードを確認する

# ⭕ 具体的
description: TypeScriptプロジェクトのPRをセキュリティ・パフォーマンスの観点でレビューする

Claudeはdescriptionを見てスキルを選ぶので、キーワードを含めることが重要です。

2. スラッシュコマンドで明示的に呼び出す

自動適用に頼らず、直接呼び出します：

Copy/my-skill

スキルの出力が期待と違う

症状

• 出力が長すぎる/短すぎる
• フォーマットが違う
• 的外れな内容

解決方法

1. SKILL.mdに出力例を追加

Copy## 出力例

[期待する出力の例をここに記載]

Copy

具体例があると、Claudeはそれに近い出力を生成します。

2. 制約を明示

Copy## 制約

- 出力は100文字以内
- 日本語で回答
- 箇条書きで3項目以内

3. コンテキストを追加

呼び出し時にコンテキストを渡します：

Copy/code-review
対象ファイル：src/auth.ts
重点：セキュリティ

複数のスキルが競合する

症状

• どのスキルが使われるか予測できない
• 意図しないスキルが使われる

解決方法

1. descriptionを差別化

似たスキルがある場合、descriptionで用途を明確に分けます：

Copy# スキルA
description: フロントエンドのReactコンポーネントをレビューする

# スキルB
description: バックエンドのAPIエンドポイントをレビューする

2. 使わないスキルを無効化

Copymv ~/.claude/skills/old-skill ~/.claude/skills/_disabled_old-skill

ツール間で動作が違う

症状

• Claude Codeでは動くがCodex CLIでは動かない
• 出力結果が異なる

原因

• scripts/の実行方法がツールによって異なる
• ツール固有機能（Claude Codeのサブエージェントなど）は他では動かない

解決方法

1. 基本機能だけで構成

汎用性を重視するなら、SKILL.md本体だけで完結するスキルにします。

2. ツール別に分岐

どうしても必要な場合は、ツール別のスキルを用意します：

Copy~/.claude/skills/code-review-claude/SKILL.md
~/.codex/skills/code-review-codex/SKILL.md

スキルの更新が反映されない

症状

• SKILL.mdを編集したのに動作が変わらない

解決方法

1. キャッシュの問題

Claude Codeを再起動してみてください。

2. 別のスキルが使われている

/skillsで現在読み込まれているスキルを確認し、意図したスキルが表示されているか確認します。

それでも解決しない場合

デバッグ手順

1. 最小構成でテスト：問題のスキルを最小限の内容にして動作確認
2. 別のスキルで確認：他のスキルは動くか確認
3. 公式ドキュメント確認：仕様変更がないか確認

情報収集

問題を報告する際は以下の情報があると解決が早いです：

• 使用ツールとバージョン
• SKILL.mdの内容
• 実行したコマンド
• エラーメッセージ（あれば）

まとめ

よくあるトラブルの多くは：

1. ディレクトリ構造の問題
2. フロントマターの記述ミス
3. descriptionが曖昧

まずはこの3点を確認してみてください。

スキル一覧で動作確認済みのスキルを試すのも、問題の切り分けに有効です。

関連記事

• Claude Codeでスキルを設定する方法 - 設定を見直す
• 開発効率を上げる7つのTips - 使いこなすコツ
• 自分でスキルを作る方法 - 正しい書き方を学ぶ
• Agent Skillsとは？ - 基本に立ち返る