レッスン4: テストとデバッグ: スキルを正しく動作させる

学習目標:

• スキルをテストする基本的な方法を学ぶ
• 実際に遭遇する失敗を診断する
• 反復ループを理解する
• スキルが本当に残す価値があるかを見極める方法を知る

前提: << レッスン3 | 次: レッスン5 >>

最初のスキルは正しく動かない

最初のスキルを書いて実行してみると、次のようなことに気づいたはずです。

• 一部のタスクがまったく認識されなかった
• 優先度が間違って出力された
• 出力フォーマットがぐちゃぐちゃだった
• そもそも Claude がスキルを読み込まなかった

それが普通です。

スキルはコードと同じです。一度動かせたらそれはスタートラインであって、ゴールではありません。実際に役立つスキルはどれも、何度かの改訂を経てそこにたどり着いています。¹

このレッスンでは、そうした問題を見つけて直すための、繰り返し使える方法を紹介します。

テスト方法1: 直接呼び出す

最も単純なテストは直接呼び出すことです。/skill-name で一度呼び出し、何が出力されるかを観察します。²

テストケースを用意する

何かを呼び出す前に、3〜5個の入力を書き出しておきます。

通常ケース:

四半期レポートを仕上げるPR #234 を金曜までにレビューする明日ログインのバグを直す

エッジケース:

(空の入力)

無意味なケース:

これはタスクを一切含まない、まったく無関係な文章の段落ですasldfkjasldfj!@#$%

テストを実行する

Claude Code で、1つずつ入力していきます。

/task-organizer
四半期レポートを仕上げるPR #234 を金曜までにレビューする明日ログインのバグを直す

3つの点を観察します。

1. そもそも Claude がスキルを読み込んだか?（読み込まれていなければ、問題は description にあります。）
2. 出力フォーマットは正しいか?（ぐちゃぐちゃなら、問題は出力フォーマットのセクションにあります。）
3. 内容は期待どおりか?（分類が間違っているなら、問題は処理ステップにあります。）

何が起きたかを書き留める

小さな表で十分です。

テスト方法2: 読み込みの挙動を観察する

問題が指示部分ではなく、フロントマターにあることもあります。

問題: Claude がスキルを自動で読み込まない

症状: 「これらのタスクを整理して」と言っても、Claude が task-organizer スキルを無視する。

考えられる原因:

1. description が汎用的すぎる

   修正: トリガーとなる語を入れます。

2. 実際に使う言葉が description に含まれていない

   「この To-Do を整理して」と言っても、description のどこにも「To-Do」という言葉がなければ、Claude はそのスキルを思いつかないかもしれません。³

   修正: ユーザーが言いそうな言葉を description に書き込みます。

問題: Claude が間違ったスキルを読み込む

症状: task-organizer を使いたかったのに、Claude が別のものを拾ってしまう。

考えられる原因: もう一方のスキルの description のほうが入力によく一致している。

修正: /task-organizer で明示的に呼び出すか、競合するスキルよりも具体的になるように description を研ぎ澄まします。

よくある失敗を診断する

問題1: 出力フォーマットが間違っている

症状: スキルは動くが、フォーマットがおかしい。

例:

緊急: ログインのバグを直す - 明日重要: PR #234 をレビューする - 金曜

絵文字と見出しでグループ分けされたセクションを期待していたのに、Claude はフラットなテキストリストを返してきました。

原因: 出力フォーマットのセクションが十分に具体的でないか、例がない。

修正: SKILL.md の「出力フォーマット」セクションに、完全な例を入れます。

「必ずこのフォーマットに正確に従うこと」と書いてから、全体を見せます。

問題2: 認識が不正確

症状: 一部のタスクが見落とされる、または間違った分類に入る。

例:

入力:

明日あのバグを直さないといけない金曜までにデモを用意する

出力:

### ⚪ 通常- 明日あのバグを直さないといけない - 期限の記載なし- 金曜までにデモを用意する - 期限の記載なし

どちらにも明確な期限があるのに、両方とも期限なしと判定されました。

原因: 処理ステップの時間認識ルールが、十分なケースをカバーしていない。

修正: 埋めていきます。

要点: 思いつく限りの言い回しをすべて書き出すことです。

問題3: エッジケースをすり抜ける

症状: 通常の入力は問題ないのに、変わった入力でスキルの挙動がおかしくなる。

例:

入力: 空文字列

出力: Claude が止まる、または意味のないテキストを大量に生成する。

原因: 「Notes」セクションに、空入力をどう扱うかを書いていない。

修正:

反復ループ

良いスキルは一度で書き上がるものではありません。テスト→修正→テストのループから生まれます。¹

1. 最初のバージョンを書く (中核の挙動だけ)2. 3〜5個のテストケースに対して実行する3. 何がうまくいかなかったか書き留める4. SKILL.md を編集する5. もう一度テストする6. すべてのテストケースが通るまで 3〜5 を繰り返す7. 1週間、実際に使う8. 新しい問題を見つける9. ステップ4に戻る

バージョン1が正しいとは期待しないこと。 まず動かし、次に正しくし、それから良くします。

そのスキルは本当に役立っているか?

正しく動くようになったら、もう一つ大きな問いが残っています。このスキルは本当に時間を節約しているか?¹

A/B で比べる

比較は単純です。同じタスクを、スキルありとなしで数回ずつ実行し、両方の時間を計ります。

スキルなし:

計ります。あなたが手作業でプロセスを説明し、Claude が実行する — 平均でどれくらいかかりますか?

スキルあり:

計ります。あなたがスキルを呼び出し、Claude が実行する — 平均でどれくらいですか?

スキル版のほうが速くない、または品質が劣るなら、そのスキルはまだ改善が必要です。

1週間使ってみる

本当のテストは実際の使用です。⁴

次の数字を記録します。

• 何回呼び出したか
• 手直しなしでそのまま使えた結果が何回あったか
• 再実行したり出力を手で直したりした回数
• どれだけ時間を節約できたか

1週間で呼び出しが3回未満なら、そのタスクはスキルを作るほど繰り返し性が高くない可能性が高いです。

デバッグ早見表

スキルが動かないときは、まず読み込み失敗のチェックから始めます。下の表をたどり、ファイルパス・フロントマターの形式・トリガーキーワードの順に切り分けていきます。

まとめ

• 最初のSkillは正しく動かない — テスト→修正→テストのループを経てそこにたどり着く
• テスト方法: 直接呼び出す、読み込みの挙動を観察する、テストケースを事前に用意する
• よくある失敗: description が汎用的すぎる、出力フォーマットの指定が不足、認識ルールが不完全、エッジケースが未処理
• デバッグの流れ: 期待と実際を記録し、診断し、SKILL.md を編集し、再テストする
• 価値の証明: Skillあり/なしで時間・品質・一貫性を比べ、1週間使って呼び出し回数を数える

次のレッスンでは、完全なコードレビューSkillを一通り見て、より込み入ったワークフローの扱い方を学びます。

>> レッスン5: ケーススタディ: コードレビューSkillを作る