Claude Codeを使い始めて、Skillsを自分で作ってみたものの「なんか思ったより動かない」「精度が安定しない」と感じたことはありませんか？
Skills機能は一度うまくはまると開発体験がガラッと変わるのですが、最初のうちはいくつかの"落とし穴"にハマりやすい。この記事では、私が実際に試行錯誤する中で気づいたやりがちなミス5選をまとめました。読み終わる頃には「あ、だからうまくいかなかったのか」と腑に落ちるはずです。
結論：Skillsが機能しない原因はほぼ「定義の曖昧さ」にある
Claude CodeのSkills作成で悩んでいませんか？
結論から言うと、Skillsがうまく機能しない原因の大半は「いつ・どこで・どう使うかの定義が曖昧なこと」に集約されます。
PREP法で整理するとこうなります。
| 観点 | 内容 |
|---|---|
| Point（結論） | Skillsの失敗はほぼ「定義の曖昧さ」が原因 |
| Reason（理由） | ClaudeはSkillsのdescriptionを頼りにトリガーを判断するため |
| Example（例） | descriptionが広すぎると意図しないタイミングで発火する |
| Point（再結論） | 定義を明確にするだけで精度が劇的に上がる |
なぜ「定義の曖昧さ」がこれほど問題になるのか
ClaudeがSkillsを選択するとき、頼りにしているのはほぼdescriptionフィールドの内容です。人間がREADMEを読んで「このツールを使おう」と判断するのと同じように、Claudeもdescriptionを読んで「このSkillが今の状況に合う」と判断します。
つまり、descriptionが曖昧だとClaudeが正しく判断できないのは当然の話です。私はこれに気づく前、「なんとなく動きそうな説明」を書いていました。それが一番の失敗でした。
descriptionは「どんなファイルが関係するとき」「どんな操作を求められたとき」「何をしてはいけないとき」まで明記して初めて機能します。30文字で書けるようなdescriptionは、ほぼ確実に不十分です。
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立ったもあります👇
→記事を読む
Claude CodeのSkills作成でやりがちなミス5選
❌ ミス1：descriptionが短すぎ・広すぎる
最もよくある失敗です。
❌悪い例
説明: 「ドキュメントを作成するスキル」
✅ 良い例
description: "Markdownファイルや技術仕様書作成・編集を行うスキル。ユーザーが「ドキュメントを書いて」「READMEを更新して」と言った場合に使用します。コード生成やデータ分析には使用しません。
descriptionはトリガー条件・使用場面・除外条件の3点セットで書くのが基本です。
| 項目 | 内容の例 |
|---|---|
| トリガー条件 | 「〜ファイルが含まれるとき」「〜と言われたとき」 |
| 使用場面 | 具体的なユースケースを2〜3個列挙 |
| 除外条件 | 「〜には使わない」を明示 |
❌ ミス2：SKILL.mdに「手順」しか書いていない
SKILL.mdを「レシピ」だと思ってしまうと、手順だけを書きがちです。でもClaudeにとってSKILL.mdは「文脈の補足情報」でもあります。
❌ 悪い例（手順だけ）
ファイルを読む
内容を整形する
出力する
✅ 良い例（意図・注意点・例も含める）
目的
このスキルは〜という課題を解決するために使います。
手順
ファイルを読む（文字コードに注意）
内容を整形する
出力する
注意点
バイナリファイルには使用しない
出力先は必ず /mnt/user-data/outputs/ にする
出力例
...（具体例）
◎ 「なぜそうするのか」の意図を書くと、Claudeが応用的な状況でも正しく動いてくれます。
❌ ミス3：スキルの責務が広すぎる（神スキル問題）
「何でもできるスキルを1つ作ろう」と思うと失敗します。スキルの粒度が大きくなるほど、descriptionも曖昧になり、精度が下がります。
| 設計 | 特徴 | 結果 |
|---|---|---|
| ❌ 1スキルに何でも詰め込む | description必然的に曖昧 | 意図しない発火・誤動作 |
| ✅ 単一責任で設計する | 発火条件を明確にできる | 精度が安定する |
| ◎ 類似スキルは除外条件で分離 | 「〜には使わない」を明記 | スキル同士の競合がなくなる |
私は最初、document-skillというスキルにREADME作成・仕様書作成・議事録作成を全部詰め込んでいました。案の定、どのケースでも中途半端な動作になりました。
❌ ミス4：ファイルパスや出力先を固定していない
Skillsを使ってファイルを生成させると、出力先が毎回バラバラになることがあります。これはSKILL.mdに出力パスの制約を書いていないのが原因です。
# ✅ SKILL.mdに必ず書くべき項目
## 出力先
- 最終成果物は必ず `/mnt/user-data/outputs/` に保存する
- 作業用の中間ファイルは `/home/claude/` を使う
- ユーザーのアップロードファイルは `/mnt/user-data/uploads/` にある（読み取り専用）
Claude Codeにはファイルシステムのルールがあります。これを明示しないと、Claudeが「たぶんここかな」で判断してしまいます。
❌ ミス5：availableな状況を想定しすぎたdescriptionを書く
「このスキルはこういう時に使う」を書くとき、ポジティブな条件だけを書いてしまいがちです。でも実際には「似たような別のスキル」が存在する場合、どちらを使うべきか迷ってしまいます。
❌ 悪い例（よくしやすい）
スキルAの説明：「Pythonコードを書くスキル」 スキルBの説明：「データ分析コードを書くスキル」
✅ 良い例（オンラインを防ぐ）
スキル A の説明: 「汎用的な Python スクリプトを書くスキル。データ分析・対話が主目的の場合はデータ分析スキルを使うこと。」
スキルBの説明: 「データ分析・グラフ描画専用のPythonコードを書くスキル。pandasやmatplotlib等の分析ライブラリを使う場合に限定して使用する。」
◎ スキル同士を「住み分け」させるには、descriptionに他のスキルへの言及を入れるのが効果的です。
まとめ
| ミス | 対策 |
|---|---|
| ❌ descriptionが曖昧 | トリガー・場面・除外の3点セットで書く |
| ❌ 手順しか書いていない | 意図・注意点・例もSKILL.mdに記載 |
| ❌ 神スキル設計 | 単一責任で分割し競合を防ぐ |
| ❌ 出力先が不定 | SKILL.mdにパスのルールを明記 |
| ❌ 競合スキルを意識していない | 他スキルへの言及で住み分けを明確に |
Skillsはうまく設計できると、Claude Codeの使い勝手が本当に大きく変わります。最初の設計に少し時間をかけるだけで、後の体験がガラッと変わるので、ぜひ試してみてください。
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立ったもあります👇
→記事を読む