2026-07-18

Claude Codeのスキル入門 — SKILL.mdで自分用コマンドを作る

claude-code個人開発

Claude Codeの「スキル」の仕組みを整理する。スキル = SKILL.md に手順を書いたフォルダで、/スキル名 で呼べる自作コマンドになる。以前の「カスタムスラッシュコマンド」（.claude/commands/*.md）はスキルに統合された（旧形式も動く）。

スキルとは

SKILL.md に指示を書いておくと、自分が /名前 で呼ぶことも、Claudeが関連タスクのときに自動で読み込むこともできる
CLAUDE.mdとの違いは読み込みタイミング。CLAUDE.mdは毎セッション全文がコンテキストに入るが、スキルは説明文（description）だけ常駐し、本文は使うときだけ読み込まれる。長い手順書はスキルにした方がトークンが安い
使い分けの目安: 「事実・規約」はCLAUDE.md、「手順・チェックリスト」はスキル。同じ指示を2回以上チャットに貼ったらスキル化のサイン

---
name: deploy
description: アプリを本番にデプロイする。デプロイ・リリースを頼まれたときに使う
disable-model-invocation: true
---

デプロイ手順:

1. テストを実行する
2. ビルドする
3. デプロイ先にpushする

frontmatterは全部任意（description だけは書くべき。Claudeが自動発動の判断に使う）。主なフィールド:

フィールド	役割
`description`	何をするスキルか+いつ使うか。自動発動の判断材料
`disable-model-invocation: true`	Claudeの自動発動を禁止。自分だけが呼べる（デプロイ・コミット等の副作用系に必須）
`user-invocable: false`	`/` メニューに出さない。Claudeだけが使う背景知識用
`argument-hint`	補完時に出る引数ヒント（例: `[PR番号]`）
`allowed-tools`	このスキル実行中は指定ツールを承認なしで実行可（例: `Bash(git add *)`）
`context: fork`	サブエージェントとして別コンテキストで実行
`model` / `effort`	このスキル実行中だけモデル・思考の深さを変える
`paths`	指定globのファイルを触るときだけ自動発動

設定	自分	Claude	用途
デフォルト	○	○	汎用の手順・知識
`disable-model-invocation: true`	○	×	`/commit` `/deploy` など副作用のある操作
`user-invocable: false`	×	○	レガシー仕様の解説などの背景知識

$ARGUMENTS = 呼び出し時の引数全部。$0 $1 で個別参照、frontmatterの arguments: [issue, branch] で $issue のような名前付きも可
!`コマンド` を本文に書くと、Claudeが読む前にコマンドが実行されて出力に置き換わる。いわゆる動的コンテキスト注入
- 例: !`git diff HEAD` を入れておくと、常に最新のdiffがスキル本文に入った状態で始まる
${CLAUDE_SKILL_DIR} でスキル自身のディレクトリ、${CLAUDE_PROJECT_DIR} でプロジェクトルートを参照できる

スキルはフォルダなので、SKILL.md 以外のファイルも置ける。

my-skill/
├── SKILL.md        ← 本体（必須。500行以内推奨）
├── reference.md    ← 詳細資料（必要になったときだけ読まれる）
└── scripts/
    └── helper.js   ← Claudeが実行するスクリプト

SKILL.md から「詳細は reference.md を見る」のように参照しておくと、Claudeが必要時だけ読む。本文を薄く保つほどトークン効率が良い。

このモノレポでは .claude/skills/ に以下を置いている。全部 disable-model-invocation 相当の「自分が呼ぶ」運用。

「毎回説明していた手順」をスキルにすると、依頼が「/blog-article」の一言で済むようになる。スクリプトを同梱できるのが強くて、GIFエンコードや文字数検証のような決まった処理はスキル内の .js に固めてある。