Claude Codeのskillsの作り方

skillのdescriptionは一覧で1,536字に切られます。SKILL.mdの置き場所と書き方、呼び出し方が分かります。

skill は、必要なときだけ読み込まれる手順書です。CLAUDE.md の中身は毎回のセッションで読まれますが、skill は本文が呼ばれたときにしか読まれません。この記事では、置き場所、最小の SKILL.md、description の書き方、呼び出し方、CLAUDE.md や hooks との使い分けを順に説明します。編集部の検証環境（macOS、Claude Code 2.1.304、2026年10月20日）で、ダミーの todo アプリに skill を置いて、書式の検査までを実行しました。モデルを呼ぶセッションは動かしていません。

skill とは何か

公式は、同じ指示やチェックリスト、何段階もの手順を何度もチャットに貼っているとき、あるいは CLAUDE.md の一部が「事実」ではなく「手順」になってきたときに skill を作るよう勧めています。skill の本文は使うときにしか読み込まれないので、長い資料を置いても、使うまではほとんどコンテキストを使いません。

カスタムのスラッシュコマンドは skill に統合されました。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md は、どちらも /deploy になり、同じように動きます。既存の .claude/commands/ もそのまま使えます。新しく作るなら、補助ファイルを置けるディレクトリ形式の skill を使います。

出典：https://code.claude.com/docs/en/skills 、2026-10-20確認

置き場所と優先順位

同じ名前の skill が複数あるときは、組織、個人、プロジェクトの順に優先されます。~/.claude/skills/ とプロジェクトの両方に deploy があれば、/deploy で動くのは個人のほうです。skill と .claude/commands/ のファイルが同じ名前なら skill が使われます。

出典：https://code.claude.com/docs/en/skills 、2026-10-20確認

最小の SKILL.md

ダミーの todo アプリのリリース手順を skill にした例です。.claude/skills/release/SKILL.md に置きます。

---
name: release
description: Cut a release of the todo app. Use when the user asks to release, tag a version, or publish the changelog. Do not use for hotfix deploys or database migrations.
argument-hint: "[version]"
disable-model-invocation: true
allowed-tools: Bash(npm test) Bash(npm run build) Bash(git tag *)
---

Release version $ARGUMENTS of the todo app.

1. Run `npm test`. Stop and report if any test fails.
2. Run `npm run build`.
3. Add a `## $ARGUMENTS` section to CHANGELOG.md from the commits since the last tag.
4. Create the tag with `git tag v$ARGUMENTS`. Do not push.
5. Report the tag name and the changelog section.

frontmatter の主なキーは次のとおりです。必須のキーはありません。公式は description だけは書くよう勧めています。

出典：https://code.claude.com/docs/en/skills 、2026-10-20確認

リリースのように副作用がある手順は、disable-model-invocation: true にして、Claude が勝手に始めないようにします。allowed-tools は使えるツールを絞るものではありません。そのターンだけ確認を省くもので、次のメッセージを送ると解除されます。

書式を検査する

claude plugin validate に skill のディレクトリを渡すと、セッションを始めずに frontmatter を検査できます（v2.1.233 以降）。上の例は通りました。

$ claude plugin validate .claude/skills
Validating components in: <project>/.claude/skills

✔ Validation passed

引用符を閉じ忘れた skill を足すと、次のように出ました。

✘ Found 1 error:

  ❯ frontmatter: YAML frontmatter failed to parse: YAML Parse error: Unexpected character. At runtime this skill loads with empty metadata (all frontmatter fields silently dropped).

キー名のつづり間違いは、この検査では見つかりませんでした。 disable-model-invokation: true と書いた skill は、--strict を付けても Validation passed でした。公式も、知らないキーはエラーを出さずに無視すると書いています。キー名は表から写します。

description の書き方

description には機能の説明ではなく、使う場面を書きます。Claude はこの文を見て、skill を自動で読むかを決めるからです。公式も、ユーザーが自然に言いそうな言葉を入れるよう勧めています。

編集部が skill を書くときの決まりは2つです。1つは、使わない場面を具体名で挙げることです。上の例の「hotfix deploys や database migrations には使わない」がそれに当たります。もう1つは、ツールの名前ではなく、そのツールを使う場面を書くことです。

一覧に載るときは、description と when_to_use を合わせて 1,536 字で切られます。大事な使い道を先頭に書きます。常に読み込まれる文章を減らす話はCLAUDE.mdは削るほど効くにあります。

出典：https://code.claude.com/docs/en/skills 、2026-10-20確認

呼び出し方

既定では、あなたも Claude も skill を呼べます。

• 自動：description が会話の内容に合うと、Claude が本文を読み込む
• 手動：メッセージの先頭に /release 1.4.0 のように書く。文の途中に /release と書いた場合は、すぐには動かず、Claude がそのメッセージの中で使ってよいという許可になる
• 引数：$ARGUMENTS に全体が入る。$0、$1 で位置ごとに取り出せる。/release 1.4.0 なら $ARGUMENTS は 1.4.0 になる

disable-model-invocation: true の skill は、description もコンテキストに入らず、手動で呼んだときだけ本文が読まれます。Claude が skill を使わないときは、What skills are available? と聞いて一覧に出るかを確かめるよう公式に書かれています。

出典：https://code.claude.com/docs/en/skills 、2026-10-20確認

今回は、実際のセッションで自動の読み込みや /release を試していません（未実行）。

CLAUDE.md・skill・hooks の使い分け

公式も、skill のルールが途中で守られなくなったときは、毎回守らせたいものを hook に移すよう書いています。CLAUDE.md の最初の書き方はプロンプトより手順書を書くを、hook の書き方はClaude Code hooks実践を読んでください。

組み込みのコマンドと .claude/commands/ の自作コマンドはClaude Codeのコマンド早見表にまとめています。

まとめ

• skill は、使うときだけ本文が読まれる手順書。カスタムのスラッシュコマンドは skill に統合された
• 置き場所は個人、プロジェクト、plugin など。同じ名前なら組織、個人、プロジェクトの順に優先される
• 副作用のある手順は disable-model-invocation: true にして、/名前 で手動で呼ぶ
• description には使う場面と、使わない場面を具体名で書く。1,536 字で切られるので要点を先に書く
• claude plugin validate で YAML の壊れは見つかるが、キー名のつづり間違いは見つからない
• 毎回必要な事実は CLAUDE.md、手順は skill、必ず守らせる規則は hooks に置く

関連記事

• Claude Codeのサブエージェントの作り方
• permissions設定の早見表