Claude Code Skillsの作り方：実用例3本と、使われない・出てこないときの直し方

Claude Code 初級〜中級 12分で読めます

Claude CodeのSkillsは、繰り返し頼む作業の手順やチームのルールをSKILL.mdというファイルにまとめておき、必要なときにClaudeに読み込ませる仕組みです。書き方自体は簡単ですが、「作ったのに使われない」「メニューに出てこない」というつまずきが多い機能でもあります。この記事では、そのまま使える実用的なSkill 3本と、わざと壊したSkill 6本をclaude plugin validateで検査した結果をもとに、作り方と、検査で見つかる問題・見つからない問題を解説します。

検証環境：Claude Code 2.1.300／WSL2（Ubuntu）。2026年10月16日に、claude plugin validate（通常モードと--strict）で9本のSkillを検査しました。この検査はモデルを呼び出さないため、Skillが実際に「発動するか」までは試していません。その点は公式ドキュメントの記述で補っています。

Skillsの基本

置き場所

置き場所	使える範囲
`~/.claude/skills/スキル名/SKILL.md`	自分のすべてのプロジェクト
`.claude/skills/スキル名/SKILL.md`	そのリポジトリ（gitで共有できる）
`サブフォルダ/.claude/skills/…`	Claudeがそのフォルダのファイルを触ったときに読み込まれる
プラグインの`skills/`	プラグインを有効にした場所（`/プラグイン名:スキル名`）

同じ名前が複数あるときは、組織の管理設定＞個人（~/.claude）＞プロジェクトの順で優先されます。以前の.claude/commands/名前.md形式も今は動きますが、補助ファイルを添えられるSkillsが推奨されています。

Claudeが「使う」かどうかは説明文で決まる

Claudeは、各Skillのdescription（とwhen_to_use）を一覧として常に把握しています。依頼の内容が説明文に合うと判断したときに、本文を読み込みます。本文が読み込まれるのは使うときだけなので、Skillをたくさん置いても、ふだんの文脈を圧迫するのは説明文の分だけです。

だからこそ、説明文には「何をするか」と「いつ使うか」の両方を書くのが肝心です。「コミットメッセージを作る」だけより、「ユーザーが『コミットメッセージを考えて』と頼んだときに使う」まで書いたほうが、発動の判断がぶれにくくなります。

自分で呼ぶか、Claudeに任せるか

設定	自分で`/名前`	Claudeが自動で	向いている用途
（既定）	できる	できる	ふだんの作業手順
`disable-model-invocation: true`	できる	できない	デプロイなど、勝手に動かれると困るもの
`user-invocable: false`	できない	できる	表記ルールなどの背景知識

そのまま使える実用例3本

次の3本は、claude plugin validateの通常モードと--strictモードの両方で「✔ Validation passed」となりました。

1. コミットメッセージを作る（引数と動的な差分の埋め込み）

!`コマンド`と書くと、Skillが呼ばれる直前にコマンドが実行され、その出力が本文に埋め込まれます。ここでは、ステージ済みの差分を埋め込んで、それだけを根拠にメッセージを作らせます。/commit-message 認証まわりの修正のように呼ぶと、補足が$ARGUMENTSに入ります。

# .claude/skills/commit-message/SKILL.md
---
name: commit-message
description: ステージ済みの変更から日本語のコミットメッセージ案を作る。ユーザーが「コミットメッセージを考えて」「コミットして」と頼んだときに使う。
argument-hint: "[補足したい意図]"
allowed-tools: Bash(git diff:*) Bash(git status:*)
---

## ステージ済みの変更

!`git diff --cached --stat`

!`git diff --cached`

## 手順

1. 上の差分だけを根拠に、変更の目的を1文でまとめる（推測で機能を足さない）
2. 次の形式でコミットメッセージ案を1つ出す
   - 1行目：50文字以内。「feat: 」「fix: 」「docs: 」などの種別を先頭に付ける
   - 空行のあと、変更点を箇条書きで3つまで
3. 差分が空なら、`git add` が必要だと伝えて終わる

ユーザーの補足：$ARGUMENTS

注意：!`…`のコマンドが失敗すると、Skillの呼び出し全体が中止されます。gitリポジトリでない場所で使う可能性があるなら、失敗しないコマンドにしておきます。allowed-toolsは「このSkillを呼んだターンの間だけ、確認なしで使えるツール」で、次のメッセージを送ると元に戻ります。

2. チェックリストでレビューする（補助ファイルの使い方）

長い資料はSKILL.mdに詰め込まず、別ファイルにして本文からリンクします。Claudeは必要になったときにそのファイルを読みます。公式ドキュメントは、SKILL.md本体を500行以内に抑えることを勧めています。

# .claude/skills/review-checklist/SKILL.md
---
name: review-checklist
description: プルリクエストや差分をチームのチェックリストに沿ってレビューする。「レビューして」「PRを見て」と頼まれたときに使う。
when_to_use: マージ前の確認、セキュリティや破壊的変更の見落としが心配なとき
---

# レビューの進め方

1. 変更されたファイルを一覧にし、変更の目的を1文で確認する
2. [checklist.md](checklist.md) の項目を上から順に確認する
3. 指摘は「重大」「要確認」「軽微」の3段階に分け、該当行を必ず示す
4. 問題がなければ「指摘なし」とだけ書く（無理に指摘を作らない）

# .claude/skills/review-checklist/checklist.md
# レビュー用チェックリスト

- [ ] 秘密情報（APIキー、パスワード、トークン）がコードやログに含まれていない
- [ ] 入力値の検証がある（外部からの入力をそのまま使っていない）
- [ ] エラー時の処理がある（例外を握りつぶしていない）
- [ ] 破壊的な変更（APIの引数・戻り値、DBのスキーマ）が説明されている
- [ ] テストが追加・更新されている

3. 日本語ドキュメントの表記ルール（背景知識として持たせる）

user-invocable: falseにすると/のメニューには出ず、Claudeだけが必要なときに参照します。pathsを指定すると、条件に合うファイルを扱うときに限って自動で使われるようになります。

# .claude/skills/jp-doc-style/SKILL.md
---
name: jp-doc-style
description: このリポジトリの日本語ドキュメントの表記ルール。docs/ 配下のMarkdownを書く・直すときに参照する。
user-invocable: false
paths: docs/**/*.md
---

- 文体は「です・ます」にそろえる
- 英数字の前後に半角スペースを入れない（例：「Claude Codeで」）
- 「下さい」ではなく「ください」、「出来る」ではなく「できる」と書く
- 見出しの末尾に句点を付けない

わざと壊して検査した結果

claude plugin validate <フォルダ>は、フォルダ内のSkills・エージェント・コマンドの書式を検査するコマンドです。モデルを呼ばないので、利用枠を使わずに何度でも試せます。--strictを付けると警告もエラー扱い（終了コード1）になり、CIに組み込めます。

claude plugin validate ./my-project/.claude          # 通常の検査
claude plugin validate --strict ./my-project/.claude # 警告もエラーにする（CI向け）

わざと壊した6本の結果です。

壊し方	通常の検査	--strict
1行目が空行で、`---`が2行目にある	⚠ 警告「No frontmatter block found」	失敗（終了コード1）
`description`がない	⚠ 警告「No description in frontmatter」	失敗
項目名の打ち間違い（`descripton`）	⚠ 警告「No description in frontmatter」	失敗
説明文に引用符なしのコロン（`description: 注意: …`）	通過	通過
名前に`<`を含む（`bad<name>`）	通過	通過
説明文が1,536文字を超える（約2,000文字）	通過	通過

注意したいのは最後の2つです。公式ドキュメントによれば、<や>、制御文字などを含む名前は受け付けられず、/のメニューに出てきません。また、説明文（descriptionとwhen_to_useの合計）は一覧では1,536文字で切られます。どちらも検査は通るのに、実際の動作では問題になるケースです（この2点の実際の動作は、検証環境では確かめていません）。

打ち間違いも、検査は「説明がない」としか言いません。項目名が間違っているのに、間違いそのものは指摘されないのです。警告が出たら、まず項目名のつづりを疑ってください。

「Skillが使われない・出てこない」ときの確認順

claude plugin validateで書式を検査する：フロントマターが1行目から始まっているか、descriptionが読めているかを確かめます。公式ドキュメントによれば、YAMLが解析できない場合、Skill自体は読み込まれますが、項目は一つも設定されない状態になります。
説明文を見直す：「何をするか」だけでなく「どんな依頼のときに使うか」を、頼むときの言い回しに近い言葉で書きます。重要な用途は説明文の先頭に置きます（後ろは切られる可能性があります）。
セッション中に作ったなら読み込み直す：セッションの途中で新しいSkillのフォルダを作った場合は、/reload-skillsで読み込み直します。サブフォルダの.claude/skills/は、Claudeがそのフォルダのファイルを触るまで読み込まれません。
メニューに出ないなら名前を疑う：使えない文字が名前に入っていないか確かめます。公式ドキュメントは、claude --debugで起動してログを[names]で検索する方法を挙げています。
確実に呼びたいなら自分で呼ぶ：自動の発動はClaudeの判断なので、毎回とは限りません。必ず使ってほしい手順は/スキル名で呼びます。逆に、勝手に使われて困るものはdisable-model-invocation: trueにします。

使われていないSkillを洗い出すには、/skill-doctorも使えます（公式ドキュメントの記述による。検証環境では未実行）。

claude.aiやAPIでも使うなら

同じSkillをclaude.aiにアップロードしたり、Skills APIで使ったりする場合、使える項目はname、description、license、compatibility、metadata、allowed-toolsだけです。pathsやuser-invocableなどのClaude Code専用の項目が入っていると、アップロード時にエラーになります。共通で使うSkillは、項目を最小限にしておくのが無難です。

まとめ

Skillsは「説明文で使われ方が決まり、本文は使うときだけ読まれる」仕組みです。作ったらclaude plugin validateで書式を確かめ、名前の文字と説明文の長さは検査で見逃されることを覚えておく——この2点を押さえるだけで、「作ったのに使われない」の多くは防げます。

最終確認日：2026年10月16日（Claude Code 2.1.300で検査）