Claude CodeのSkillsを使い始めて1ヶ月、最初に作ったスキルは 「呼ばれない」 ものでした。
頑張って手順を書き込んだのに、Claude Codeが選んでくれない。手動で /my-skill と叩けば動くけれど、それじゃスキルにした意味が半減する。
何が悪かったのか、どう書き直したら自然に呼ばれるようになるのか — 1ヶ月の試行錯誤で見えてきた 10個のコツ を共有します。
ユースケース紹介の方は別記事にまとめてあるので、 「Skillsで何ができるか」 を知りたい方はそちらから。
前提 — スキルの仕組みは「frontmatter + 本文」
最初に最低限の構造だけ整理します。
スキルは ~/.claude/skills/{スキル名}/SKILL.md という1ファイルから始まります。中身はこんな構造。
---
name: my-skill
description: いつ・誰が・何のために使うかを20-50字で
---
# 本文(スキルの手順や指示)
ここに「どう動いてほしいか」を日本語で書く。
ここで知っておくべき重要事実が1つ。
Claudeがスキルを呼ぶか判断するときに読むのは description だけ。本文は呼ばれた後に読まれる。つまり description が 呼び出しの全て を決めるということです。
逆に言うと、本文をどれだけ丁寧に書いても、 description が雑だと一生呼ばれません。
コツ1 — /skill-creator から始める
ゼロからファイル作るより、 公式が提供している skill-creator スキル に頼るのが速い。
/skill-creator
これでClaude Codeが対話形式で質問してくれる。「このスキルは何のためのものですか」「いつ呼ばれるべきですか」「どういう手順を実行しますか」と聞かれて、答えていくだけで SKILL.md の雛形が完成します。
私は最初、 skill-creator を使わずに手書きで作って、何度も書き直しになりました。1回目から 対話で詰めながら作る方が手戻りが少ない。
コツ2 — 3回以上やった作業だけスキル化する
スキルは 作るのも保守するのも工数 がかかります。
「これ便利そうだから」とスキル化する習慣をつけると、半年後に 使われていないスキルが20個並んでいる墓場 ができあがります。私の知り合いの実例。
目安は 3回以上やった作業、または週次で発生する作業。これを下回る頻度の作業は、その都度プロンプトで頼んだ方が早い。
コツ3 — 名前より description が決定的に重要
ここが最大のハマりポイント。
name(スキル名)はファイル名としてしか使われません。Claudeが「このスキルを使うべきか」を判断する時に読むのは description のみ。
雑な例。
description: 議事録を整形する
これだと、Claudeに「会議のメモを綺麗にして」と頼んでも呼ばれない可能性が高い。「議事録を整形する」と「会議のメモを綺麗にする」が結びつかない。
良い例。
description: Slackや会議の生メモを社内議事録テンプレに整形してToDoとセットで出力する
「Slack」「会議」「整形」「テンプレ」「ToDo」と、 想定される依頼文に含まれそうなキーワード が散りばめられている。これだと自然に呼ばれます。
コツ4 — descriptionを声に出して読む
仕上げのチェックとして、 描いた description を声に出して読んでみる。
そして「自分が日常的にClaudeに頼みそうな依頼文」と並べて、 語感が近いか を確認します。距離があれば書き直し。
私の /threads-post スキルの場合、最初の description は「Threadsの投稿を生成」でした。これだと「投稿作って」「ポストして」と頼んでも呼ばれにくい。
書き直し後 — 「バズ投稿のサンプル集を読み込んで型を抽出し、お題に対する新規Threads投稿を3-5本生成」。これで呼ばれるようになりました。
コツ5 — 「いつ使うか」を本文ではなく description に書く
これも見落とされがち。
スキル本文に「## いつこのスキルを使うか」というセクションを書きたくなりますが、 本文は呼ばれた後にしか読まれない。 「いつ使うか」が本文にあっても、Claudeはそれを見て呼び出し判断ができません。
when to use 情報は すべて description に詰め込む のが正解。少し長くなっても問題ありません。
コツ6 — リファレンスデータをスキルフォルダに同梱する
長いリスト・例文集・テンプレートをスキル本文に直書きすると、本文が 常時ロードされる重さ になります。
代わりに、 スキルフォルダ内のサブファイル に分離。
~/.claude/skills/threads-post/
SKILL.md # 軽い、手順のみ
examples.md # バズ投稿サンプル20件
templates.md # フックパターン集
SKILL.mdからは「./examples.md を読み込んで」とだけ書く。 必要なときだけ読み込まれる 構造になります。
これが「段階的開示(Progressive Disclosure)」の考え方。
コツ7 — ロジックをコードに書かない
スキル本文は Claudeへの指示書 です。プログラムではない。
if 入力に「議事録」が含まれる:
テンプレAを使う
else:
テンプレBを使う
こういうコード風の書き方をスキル本文に入れると、逆効果。Claudeは 日本語の自然言語の方が読みやすい。
正しい書き方。
入力が議事録系の依頼ならテンプレAを使う。それ以外の業務メモならテンプレB。判断に迷う場合はユーザーに確認。
これだけで通じます。Claudeは賢いので、過剰に細かい分岐を書く必要はありません。
コツ8 — テンプレと「良い例・悪い例」を1つずつ入れる
抽象的な指示より、 具体例1つ の方が精度が上がる。
私のスキルでは、こんな感じで例を入れています。
## 出力フォーマット
良い例
投稿1｜知らないと損する小ワザ
Claude Codeの/clear、知らない人が多いです。 (本文) #ClaudeCode
悪い例(避ける)
今日はClaude Codeの便利な機能を3つご紹介します！
「悪い例」を併記 すると、Claudeが「これだけは避ける」を強く意識するようになります。
コツ9 — 失敗パターンを「## 守ること」セクションに集約する
禁止事項やお作法を本文の各所に散らすと、Claudeが見落とす確率が上がります。
代わりに 「## 守ること」セクションを1つ 作って、そこに集約します。
## 守ること
- AIっぽい定型句(禁止ワードリスト)を使わない
- 句点(。)ごとに改行
- ハッシュタグは2-3個まで
- 絵文字は使わない
- 文字数は500字以内
具体的な禁止ワードは別ファイル(例えば style-guide.md)に分離して、SKILL.md からは「./style-guide.md を読み込んで遵守」と書く方式が長期運用には向いています。
これだけで、 守られる確率が体感で2-3倍 上がります。リストにまとまっていると、Claudeが最後にチェックしやすい。
コツ10 — 1ヶ月後に自分で見直す
最後のコツがこれ。
作った直後は完璧に見えても、 1ヶ月後に自分で振り返ると、必ず欠けている指示 がある。実際の依頼で「あ、ここを書いていなかった」「これは指示と違う動きをしている」と気づく場面が出てきます。
私は 月末に過去のスキル使用ログ を /export で出して、descriptionと手順を1回見直す習慣にしています。10分の作業ですが、これで翌月のスキルの精度が上がる。
「作って終わり」ではなく、 継続的に育てる前提 で運用するのが、長く効くスキルの条件です。
私自身の失敗談 — 最初に作ったスキルが呼ばれなかった理由
参考までに、私の最初のスキル失敗例を共有します。
業務日報を書くスキル /daily-report を作りました。本文は丁寧に手順を書いて、テンプレも入れて、書式の例も載せた。 完璧なはず と思って運用開始。
でも、「日報書いて」と頼むとClaudeが普通に応答してきて、スキルが呼ばれない。 /daily-report と手動で叩けば動くんですが、それなら従来のプロンプトでも変わらない。
問題は description でした。
最初の description — 「業務日報を書くためのスキル」
書き直し後 — 「今日やったタスクを箇条書きで渡すと、社内日報フォーマット(やったこと/学び/明日の予定)に整形して、Slack投稿用のテキストを生成する」
書き直した瞬間、 「今日やったこと書いて」「日報まとめて」「明日に向けて整理して」 の全パターンで呼ばれるようになりました。
description は 呼ばれるための広告コピー。本文は呼ばれた後の作業手順。役割を切り分けて書くのがコツです。
まとめ
- スキルは
SKILL.mdの frontmatter(description) + 本文 の2部構成 - 呼び出し判断は descriptionだけ で行われる、ここが命
- まずは
/skill-creatorで対話的に作る - スキル化は 3回以上やった作業のみ に絞る
- description は 想定される依頼文に近い語感 で書く
- 「いつ使うか」は本文ではなく description に詰め込む
- 大きなリファレンスは スキルフォルダ内のサブファイル に分離
- 本文に ロジック分岐を書かず 自然言語で指示
- 良い例・悪い例 を1つずつ入れる、 守ることセクション で禁止事項を集約
- 1ヶ月後に見直す 習慣で、スキルの質を継続的に上げる
スキルは「作るのが目的」ではなく「呼ばれて動くのが目的」。今日のうちに自分の description を1個だけ見直してみてください。明日から、 Claudeに「あれやって」と頼む頻度が増える はずです。
