Claude Code Skills(SKILL.md)の作り方：配置・frontmatter・呼ばれ方と使い分け

Claude Code の Skills は、SKILL.md という Markdown ファイル1枚を決まったフォルダに置くだけで作れる、呼び出し可能な手順書・参照資料です。 普段は名前と description だけが Claude の文脈に載り、依頼が description に合ったとき、または /スキル名 と打ったときに本文が読み込まれます。

この記事は公式 Skills ページの記述を根拠に、置き場所、frontmatter の公式キー、本文と付随ファイルの読み込まれ方、ほかの仕組みとの使い分け、チームへの配り方を Skill 側の視点で整理します。手元の Claude Code 2.1.261(Windows 11)で小さな Skill を作り、claude -p で呼ばれるところまで確認しました。拡張機能全体の早見表はサブエージェント・スキル・MCP・hooks・コマンドの使い分けにあるので、ここでは重複させません。

置き場所とコマンド名

公式の「Choose where skills load」の表を、個人開発で使う範囲に絞るとこうなります。

押さえておく規則は4つです。

• コマンド名はフォルダ名から決まる。 個人・プロジェクトの Skill では frontmatter の name は一覧の表示名にしか効かず、.claude/skills/deploy-staging/SKILL.md は /deploy-staging になります。name がコマンド名の最後の部分を置き換えるのはプラグインの Skill だけです。
• 同名なら enterprise > personal > project。 個人とプロジェクトに同じ deploy があると、/deploy で動くのは個人側です。プラグインの Skill は名前空間付きなので衝突しません。
• .claude/commands/ の Markdown は旧形式として今も動く。 同名の Skill があれば Skill が勝ちます。付随ファイルを持てるので、新しく作るなら Skill です。公式の /docs/en/slash-commands を取得すると Skills ページと同じ内容が返り、ドキュメントも統合されています。
• 編集は再起動なしで反映される。 例外は、セッション開始時に存在しなかったトップレベルの skills ディレクトリを新しく作った場合で、このときだけ再起動が要ります。

モノレポでは、起動したディレクトリから親をたどってリポジトリルートまでの .claude/skills/ が読まれます。起動位置より下にある Skill は、Claude がそのサブディレクトリのファイルを読み書きした時点で読み込まれます。

SKILL.md の書き方と公式 frontmatter

最小形は description と本文だけです。frontmatter は --- がファイルの1行目にあるときだけ解釈されます。

---
description: 未コミットの変更を要約し、危ない箇所を指摘する。何を変えたか聞かれたとき、コミットメッセージを頼まれたときに使う。
---

変更内容を2〜3行で要約し、エラー処理の欠落やハードコードされた値など気になる点を列挙する。

公式の Frontmatter reference にあるキーを用途でまとめました(2026-09-14 時点、すべて任意)。

本文では置換が使えます。$ARGUMENTS(引数全体)、$0 $1(位置指定)、${CLAUDE_SKILL_DIR}(SKILL.md のあるフォルダ)、${CLAUDE_PROJECT_DIR}、${CLAUDE_SESSION_ID} などです。引数を受け取る置換が本文に無いと、末尾に ARGUMENTS: <入力> が自動で付きます。

コマンド出力の埋め込みも本文の機能です。行頭か空白の直後に ! を置き、続けてバッククォートでコマンドを囲むと、Claude に渡す前にコマンドが実行されて出力に置き換わります(下の実例を参照)。複数行は、開きフェンスの直後に ! を付けたコードブロックに書きます。コマンドが失敗すると呼び出し全体が中止されるので、終了コード1を返しうるチェックには || true を付けます。

付随ファイルは SKILL.md と同じフォルダに置き、本文からリンクして「何が書いてあり、いつ読むか」を示します。公式は SKILL.md を500行未満に保ち、詳細は別ファイルへ出すよう勧めています。

Claude Code 以外でも使うなら、キーを絞ります。claude.ai へのアップロード、Skills API、package_skill.py でのパッケージ化で使えるのは name description license compatibility metadata allowed-tools の6つだけで、それ以外のキーがあるとエラーで止まると公式ページにあります。! による埋め込みも claude.ai や API では動きません。AGENTS.md のように複数ツールで共有する前提なら、最初からこの6つで書くのが安全です。

実際に作って claude -p で呼ぶ

一時ディレクトリに次のファイルを置き、package.json の version と CHANGELOG.md の先頭行が一致しているかを判定する Skill を作りました。

proj/
├── package.json          # "version": "1.2.0"
├── CHANGELOG.md          # 先頭行: ## v1.1.0 - 2026-09-01
└── .claude/skills/release-check/
    ├── SKILL.md
    └── rules.md          # 判定ルール(付随ファイル)

---
name: release-check
description: package.json の version と CHANGELOG.md 先頭の見出しが一致しているかを確認する。「リリースできる?」「バージョンを確認して」と聞かれたときに使う。
allowed-tools: Read Bash(node -p *) Bash(head -n 1 *)
---

## 現在の値

- package.json の version: !`node -p "require('./package.json').version"`
- CHANGELOG.md の先頭行: !`head -n 1 CHANGELOG.md`

## 手順

1. 判定ルールは同じフォルダの [rules.md](rules.md) を読んでから適用する。
2. 次の1行だけで答える: `RELEASE-CHECK: OK` または `RELEASE-CHECK: NG (<理由>)`

先に frontmatter の構文を確かめます。v2.1.233 以降の claude plugin validate は skills ディレクトリにも使えます。

$ claude plugin validate .claude/skills
Validating components in: ...\proj\.claude\skills

✔ Validation passed

実行時は、ユーザー設定やプラグインの影響を外すため --setting-sources project,local、トークン節約のため --model haiku を付け、--output-format stream-json --verbose と --debug-file で記録しました。5回実行し、うち3回はつまずきの記録です。

1回目: /release-check がパスに化けた。 Git Bash から claude -p "/release-check" を実行すると、応答は「C:/Program Files/Git/release-check というパスについて何をしますか」でした。Git Bash(MSYS)が / で始まる引数を Windows のパスに変換したためです。MSYS_NO_PATHCONV=1 を前に付けると、/release-check のまま渡りました。

2回目: 埋め込みコマンドが許可されておらず、0ターンで止まった。 この時点の allowed-tools は Read だけでした。

Shell command permission check failed for pattern "!`node -p \"require('./package.json').version\"`": This command requires approval

結果は num_turns: 0、コスト0で、モデルは呼ばれていません。公式にも、埋め込みコマンドは許可を尋ねず、許可されなければ呼び出しを中止するので allowed-tools で事前に許可する、とあります。Bash(node -p *) と Bash(head -n 1 *) を足して解消しました。

3回目: 自動呼び出しが拒否され、Claude は Skill なしで答えた。 claude -p 'このプロジェクト、リリースできる状態?' に対し、Claude は description に反応して Skill ツールを {"skill":"release-check"} で呼びました。しかし結果はエラーで、debug ログには Skill tool permission denied と、Skill(release-check) を allow に加える提案が出ていました。Claude はそのまま PowerShell や Read でファイルを眺め、「リリース可否の判断には実装内容やテストの確認が必要です」という一般論で終わりました。Skill を使えなかったことは最終応答のどこにも書かれていません。 どういう条件で Skill ツールに許可が要るのかは、公式ページでは確認できていません。

4回目: Skill(release-check) を許可すると期待どおりに動いた。 --allowedTools "Skill(release-check)" を足すと、Skill ツールの結果 Launching skill: release-check の直後に、会話へ入った本文がそのまま記録されていました。

Base directory for this skill: C:\Users\...\proj\.claude\skills\release-check

## 現在の値

- package.json の version: 1.2.0
- CHANGELOG.md の先頭行: ## v1.1.0 - 2026-09-01

## 手順

1. 判定ルールは同じフォルダの [rules.md](rules.md) を読んでから適用する。
2. 次の1行だけで答える: `RELEASE-CHECK: OK` または `RELEASE-CHECK: NG (<理由>)`

! の行が実行結果に置き換わっていること、付随ファイルの rules.md は本文に含まれていないことが分かります。Claude はこの後 Read で rules.md を読みにいき、RELEASE-CHECK: NG (CHANGELOG.md の version 1.1.0 が package.json の 1.2.0 と一致していません) と答えました。

5回目: 明示呼び出し。 MSYS_NO_PATHCONV=1 claude -p "/release-check" でも、同じく rules.md を読んで NG を返しました。こちらはプロンプトの段階で展開されるため Skill ツールを経由せず、追加の許可なしで動いています。公式 headless ページにも、-p でもプロンプトに含めた /skill-name は実行前に展開される、とあります。

呼ばれる条件と読み込まれ方

既定では、自分も Claude も Skill を呼べます。この2つを制御するのが次の2キーです(公式の表より)。

/deploy や /commit のように副作用がある手順は disable-model-invocation: true にします。コードが整って見えたからといって Claude に勝手にデプロイさせないためです。逆に「古いシステムの仕組み」のような背景知識は、自分がコマンドとして打つ意味がないので user-invocable: false が向きます。

一覧には予算がある。 名前と description の一覧はコンテキストウィンドウの1%を予算にしており、はみ出すと呼び出し頻度の低い Skill から description が削られます。今回、自作は1つだけでしたが、debug ログには同梱の Skill を含めた次の警告が出ていました。

[WARN] Skill listing over budget: 18 skills, 8439 chars > 8000 budget — descriptions will be truncated. Run /skills to disable some, or raise skillListingBudgetFraction in settings.

description の先頭に使う場面を書く、使わない Skill を skillOverrides で "name-only" や "off" にする、/skill-doctor(v2.1.252 以降)で使われていない Skill を探す、が公式の対処です。

本文は1回入ったら残り続ける。 呼ばれた SKILL.md は1つのメッセージとして会話に入り、以後のターンも残ります。Claude Code は後のターンでファイルを読み直さないので、作業全体に効かせたい指示は「最初に1回やること」ではなく常に守る指示として書きます。自動コンパクション後は、Skill ごとに先頭5,000トークン、合計25,000トークンまでが新しい順に再添付されます。一方で allowed-tools の許可は次のメッセージを送った時点で消えます。

context: fork は会話を引き継がない。 本文をプロンプトにしたサブエージェントが起動し、それまでの会話は見えません。規約だけを書いた Skill を fork すると、やることが無いまま戻ってきます。agent: Explore や agent: Plan は CLAUDE.md も読まない点に注意します。

Skill 側から見た使い分け

公式 features-overview の比較表を、「これを Skill に書くべきか」という問いに置き直しました。

判断は3つの問いで足ります。毎セッション必要かなら CLAUDE.md、必ず起きないと困るかなら hooks、会話の文脈が要らない長い作業かならサブエージェントか context: fork です。どれにも当たらない「時々要る知識と手順」が Skill の居場所です。公式も、ガードレールは hooks に置くべきで、CLAUDE.md や Skill に書いた禁止は保証ではなく依頼にすぎない、と明記しています。フック側の具体例はhooks レシピ集に、別コンテキストでの委譲はサブエージェントの作り方にまとめています。CLAUDE.md や AGENTS.md に何を残すかはAGENTS.md完全ガイドが詳しいです。

チームで配る

配り方は公式の Share skills に3つあります。

• プロジェクトにコミットする。 .claude/skills/ をリポジトリに入れれば、そのリポジトリで作業する全員に届きます。クラウドセッションもリポジトリの .claude/skills/ を読みますが、個人の ~/.claude/skills/ は読みません。
• プラグインにする。 プラグインのルートに skills/<skill-name>/SKILL.md を置き、必要なら .claude-plugin/plugin.json で名前とバージョンを付けます。開発中は claude --plugin-dir ./my-plugin で読み込み、変更は /reload-plugins で反映します。複数リポジトリへ配るならマーケットプレイス経由です。claude plugin init my-tool は ~/.claude/skills/my-tool/ にマニフェスト付きのひな形を作り、次のセッションから my-tool@skills-dir として読み込まれます。
• managed settings で組織に配る。 管理者が managed settings ディレクトリに置きます。

チーム向けに書くときは、作った本人の会話の文脈があると指示の抜けに気づけません。公式は、新しいセッションで Skill ありと無しを比べる評価を勧めており、プラグインなら claude plugin eval で自動化できます。

まとめ

• Skill は SKILL.md 1枚。~/.claude/skills/ は自分の全プロジェクト、.claude/skills/ はリポジトリ単位で、コマンド名はフォルダ名
• frontmatter はすべて任意。description に使う場面を先頭から書き、副作用のある手順は disable-model-invocation: true
• ! の埋め込みコマンドは許可を尋ねない。allowed-tools で許可しないと呼び出しごと中止される
• claude -p では自動呼び出しが拒否されると Claude は黙って別のやり方で答える。--allowedTools "Skill(名前)" を足すか /名前 で明示する。Git Bash では MSYS_NO_PATHCONV=1
• 毎回守らせる規約は CLAUDE.md、必ず止めたいことは hooks、時々要る知識と手順が Skill

claude -p を CI やスクリプトに組み込むときの権限の絞り方はヘッドレス実行の記事、skillOverrides などの設定ファイルの置き場所はsettings.json 逆引きを参照してください。