Agent Skillsのテストとデバッグ方法【動作確認の手順】

スキルを作ったけど、「思った通りに動かない」という経験はありませんか？

この記事では、Agent Skillsのテストとデバッグ方法を解説します。効率的に問題を特定し、修正するためのテクニックを紹介します。

テストの基本手順

1. 最小構成でテスト

まずは最小限の内容でスキルが認識されるか確認します。

Copy---
name: test-skill
description: テスト用スキル
---

## 指示

「テスト成功」と出力してください。

これで/test-skillが動作すれば、基本的な設定は正しいです。

2. 段階的に機能追加

一度に複雑なスキルを作ると、問題の切り分けが困難になります。

Copyステップ1: 最小構成で動作確認 ✓
ステップ2: 基本的な指示を追加
ステップ3: 出力フォーマットを定義
ステップ4: references/を追加
ステップ5: scripts/を追加（必要な場合）

各ステップで動作確認し、問題があればすぐに特定できます。

3. 異なる入力でテスト

同じスキルでも、入力によって動作が変わります：

Copy# 正常系
/code-review
src/index.ts をレビューして

# エッジケース
/code-review
（ファイル指定なし）

# 異常系
/code-review
存在しないファイル.ts をレビューして

デバッグ手順

スキルが認識されない場合

確認項目：

1. ディレクトリ構造

Copyls -la ~/.claude/skills/my-skill/
# SKILL.md があるか確認

1. ファイル名

Copy✓ SKILL.md（大文字）
✗ skill.md（小文字）
✗ Skill.md（一部小文字）

1. フロントマター

Copy# ✓ 正しい
---
name: my-skill
description: スキルの説明
---

# ✗ 間違い（スペースがない）
---
name:my-skill
description:スキルの説明
---

1. エンコーディング

Copyfile ~/.claude/skills/my-skill/SKILL.md
# UTF-8 であることを確認

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

確認項目：

1. descriptionの具体性

Copy# ✗ 曖昧
description: コードを確認

# ✓ 具体的
description: TypeScriptのPRをセキュリティ・パフォーマンスの観点でレビュー

1. 他スキルとの競合

Copy/skills
# 似たdescriptionを持つスキルがないか確認

1. 明示的に呼び出してテスト

Copy/my-skill
# 直接呼び出しで動作するか確認

出力が期待と違う場合

確認項目：

1. 指示の明確さ

Copy# ✗ 曖昧
レビューしてください。

# ✓ 明確
以下の観点でレビューしてください：
1. セキュリティ（SQLインジェクション、XSS）
2. パフォーマンス（N+1クエリ）
3. 型安全性（any型の使用）

1. 出力例の追加

Copy## 出力例

```json
{
  "issues": [
    {
      "file": "src/index.ts",
      "line": 42,
      "severity": "high",
      "message": "SQLインジェクションの可能性"
    }
  ]
}

Copy
3. **制約の明示**
```markdown
## 制約

- 日本語で出力
- 100文字以内
- JSON形式

デバッグツール

/skills コマンド

現在有効なスキルを確認：

Copy/skills

スキルが一覧に表示されない場合は、配置場所かファイル形式に問題があります。

詳細ログの確認

Claude Codeの設定でログレベルを上げると、スキルの読み込み状況を確認できます。

差分テスト

問題が発生したら、動作するバージョンと比較：

Copydiff working-skill/SKILL.md broken-skill/SKILL.md

よくあるエラーと対処法

YAMLパースエラー

原因：フロントマターの文法エラー

Copy# ✗ コロンの後にスペースがない
name:my-skill

# ✗ 引用符の不一致
description: "説明文'

# ✓ 正しい
name: my-skill
description: "説明文"

文字化け

原因：エンコーディングの問題

対処：UTF-8（BOMなし）で保存し直す

scripts/が実行されない

原因：

• 実行権限がない
• ツールがscripts/をサポートしていない

対処：

Copychmod +x scripts/my-script.sh

または、スクリプトなしで動作するようにフォールバックを用意。

テスト自動化

テストケースを文書化

Copy## テストケース

### TC-1: 基本動作
- 入力: `/code-review src/index.ts`
- 期待: レビュー結果がJSON形式で出力される

### TC-2: ファイル指定なし
- 入力: `/code-review`
- 期待: 「ファイルを指定してください」というエラー

### TC-3: 存在しないファイル
- 入力: `/code-review nonexistent.ts`
- 期待: 「ファイルが見つかりません」というエラー

回帰テスト

スキルを更新したら、以前動作していたケースも再テスト。

まとめ

Agent Skillsのテストとデバッグのポイント：

1. 最小構成から始める
2. 段階的に機能追加
3. 異なる入力でテスト
4. ログを活用
5. テストケースを文書化

問題が起きたら、この記事のチェックリストを順に確認してください。

関連記事

• 自分でスキルを作る方法 - スキル作成の基本
• スキルが動かない？トラブルシューティング - よくある問題と解決法
• 上級テクニック - references/やscripts/の活用
• 開発効率を上げる7つのTips - 効率的な開発方法