ai-docs

Extend Claude with skills

Properties1
tagsclaude-code, skills, context, subagents, permissions, progressive-disclosure

23 min read

一行要約

skill は「SKILL.md を置くだけで Claude の道具箱に増える指示・知識・ワークフロー」であり、CLAUDE.md との決定的な違いは 本体が使うときにしかロードされないこと。したがって長い参照資料を置いても、使うまでのコストはほぼゼロ。

要点

いつ作るか

Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact. 同じ指示・チェックリスト・複数手順の手続きをチャットに何度も貼っているとき、あるいはCLAUDE.md のある節が、事実ではなく手続きに育ってしまったときに skill を作れ。

カスタムコマンドは skill に統合された。 .claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy を作り、同じように動く。既存の .claude/commands/ はそのまま動き続ける。skill 側が追加で持つのは、補助ファイル用のディレクトリ、呼び出し主体を制御する frontmatter、Claude が関連性で自動ロードできること。

Claude Code の skill は Agent Skills というオープン標準に従い、Claude Code が独自拡張（invocation control、subagent 実行、dynamic context injection）を足している。

置き場所と優先順位

場所パス適用範囲
Enterprisemanaged settings 参照組織の全ユーザー
Personal~/.claude/skills/<skill-name>/SKILL.md自分の全プロジェクト
Project.claude/skills/<skill-name>/SKILL.mdそのプロジェクトのみ
Plugin<plugin>/skills/<skill-name>/SKILL.mdplugin が有効な場所

同名なら enterprise > personal > project。この3レベルのいずれかにある skill は、同名の bundled skill も上書きする（プロジェクトの code-review が bundled の /code-review を置き換える）。plugin skill は plugin-name:skill-name の namespace なので衝突しない。

ネストした skill（monorepo 向け）:

  • 作業ディレクトリより下の .claude/skills/ は起動時にはロードされない。そのサブディレクトリのファイルを Claude が読むか編集した時点で使えるようになる
  • 名前が衝突した場合、両方とも使える。ネスト側は apps/web:deploy のようにディレクトリ修飾名で現れる
  • /deploy と打つとプロジェクトルート側が走るが、Claude Code がディレクトリ修飾された variant の一覧を内容に追記し、作業中のファイルがあるディレクトリの variant も呼ぶよう指示する

--add-dir は通常「ファイルアクセスの付与」であって設定の読み込みではないが、skill は例外で .claude/skills/ が自動的にロードされる。ただし permissions.additionalDirectories 設定のほうは skill をロードしない。

live change detection: skill ディレクトリは監視されており、追加・編集・削除は再起動なしに現セッションへ反映される。ただしセッション開始時に存在しなかったトップレベルの skills ディレクトリを作った場合は再起動が要る。

Cowork / cloud セッションの注意: これらは自分のマシンの ~/.claude/skills/ を読まない。routine が個人 skill を呼ぶと「見つからない」と報告される。claude.ai アカウント側で有効化するか、リポジトリの .claude/skills/ にコミットする。

skill の中身は2種類

Reference content — 規約、パターン、スタイルガイド、ドメイン知識。会話の context と並べて使えるようインラインで走る。

Task content — デプロイ、コミット、コード生成のような手順。/skill-name で直接呼ぶことが多く、disable-model-invocation: true を付けて Claude の自動起動を止めるのが定石。

Keep the body itself concise. Once a skill loads, its content stays in context across turns, so every line is a recurring token cost. State what to do rather than narrating how or why. 本体は簡潔に保て。skill はいったんロードされると、その内容がターンをまたいで context に残り続けるため、1行ごとが繰り返し発生するトークンコストになる。やり方や理由を語るのではなく、何をすべきかを述べよ。

Tip: Keep SKILL.md under 500 lines. Move detailed reference material to separate files. ヒント: SKILL.md は500行未満に保て。詳細な参照資料は別ファイルへ移せ。

frontmatter リファレンス

全フィールドが optional。推奨は description のみ。boolean は yes / no / on / off / 1 / 0 も受け付ける（大文字小文字不問）。

フィールド説明
name一覧に出る表示名。既定はディレクトリ名。personal / project skill では表示名にしか効かず、コマンド名はディレクトリ名から来る。plugin skill では最終セグメントを置き換える
description何をするか + いつ使うか。Claude が適用判断に使う。省略すると markdown の最初の段落が使われる。description + when_to_use の合計は 1,536 文字で切られるので主要ユースケースを先頭に置く
when_to_useトリガーとなる言い回しやリクエスト例。description に追記され、1,536 文字の上限に算入される
argument-hint補完時に出る引数のヒント（[issue-number] など）
arguments$name 置換用の名前付き位置引数。空白区切り文字列か YAML リスト
disable-model-invocationtrue で Claude の自動ロードを禁止。subagent への preload も、scheduled task による起動も防ぐ
user-invocablefalse で / メニューから隠す。ユーザーが直接呼ぶ意味のない背景知識向け
allowed-toolsskill を呼んだターンの間だけ、確認なしで使えるツール。次のメッセージを送ると解除される
disallowed-toolsskill が有効な間、ツールプールから除去する。自律ループで AskUserQuestion を封じるなど
modelこの skill が有効な間のモデル。現在のターンの残りにだけ適用され、設定には保存されない
effortlow / medium / high / xhigh / max
contextfork で forked subagent 実行
agentcontext: fork のときの subagent 種別
backgroundcontext: fork のときのみ。false で呼んだターン内で結果を待つ。既定 true
hooksこの skill のライフサイクルに紐づく hook
pathsglob。マッチするファイルを扱っているときだけ自動ロードされる
shell!`command` に使うシェル。bash（既定）か powershell
metadata自前ツール用の自由な YAML マップ。Claude Code は中身に反応しない
license / compatibilityAgent Skills 仕様のフィールド。Claude Code は受け付けるが動作に使わない

Claude Code の外では使えるフィールドが違う（重要な落とし穴）:

配布経路使えるフィールド
Claude Code の skill（plugin skill 含む）上表のすべて
claude.ai へのアップロード、Skills API、package_skill.py によるパッケージングname, description, license, compatibility, metadata, allowed-tools の6つだけ

仕様外のフィールドがあると無視ではなくハードエラーになる。

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

コマンド名がどこから来るか

skill の場所コマンド名の出所例
~/.claude/skills/ または .claude/skills/ 配下ディレクトリ名.claude/skills/deploy-staging/SKILL.md → /deploy-staging
ネストした .claude/skills/（名前衝突時）作業ディレクトリからの相対パス + skill ディレクトリ名apps/web/.claude/skills/deploy/SKILL.md → /apps/web:deploy
.claude/commands/ 配下のファイル拡張子を除いたファイル名.claude/commands/deploy.md → /deploy
plugin の skills/ 配下frontmatter name またはディレクトリ名、plugin 名で namespacemy-plugin/skills/review/SKILL.md → /my-plugin:review
plugin ルートの SKILL.mdfrontmatter name（なければ plugin ディレクトリ名）name: review → /my-plugin:review

文字列置換

変数内容
$ARGUMENTS渡された引数全体。content 内に無ければ ARGUMENTS: <value> として末尾に付く
$ARGUMENTS[N] / $N0 始まりの位置指定。$0 が第1引数
$namearguments frontmatter で宣言した名前付き引数
${CLAUDE_SESSION_ID}現在のセッション ID
${CLAUDE_EFFORT}現在の effort（ultracode は独立レベルではなく xhigh として報告される）
${CLAUDE_SKILL_DIR}SKILL.md があるディレクトリ。plugin skill では plugin ルートではなく skill のサブディレクトリ
${CLAUDE_PROJECT_DIR}プロジェクトルート。hook や MCP server が受け取るものと同じ

${CLAUDE_SKILL_DIR} と ${CLAUDE_PROJECT_DIR} は markdown 本文と allowed-tools の Bash ルールの両方で置換される。両方で同じ変数を使うと、同梱スクリプトを権限プロンプトなしで実行できる。

引数はシェル式のクォートに従う。/my-skill "hello world" second なら $0 は hello world。対応する引数がない位置指定はそのまま残り、名前付きは空文字に展開される。リテラルの $ は \$1.00 のようにバックスラッシュでエスケープする。

呼び出し主体の制御（最重要の表）

frontmatter自分が呼べるClaude が呼べるcontext へのロード
（既定）YesYesdescription は常時 context、本体は呼んだとき
disable-model-invocation: trueYesNodescription も context に載らない、本体は自分が呼んだとき
user-invocable: falseNoYesdescription は常時 context、本体は呼んだとき

You don’t want Claude deciding to deploy because your code looks ready. コードが準備できているように見えるからといって、Claude がデプロイを決めてしまうのは望ましくない。

disable-model-invocation: true の skill を Claude が呼ぼうとすると、Claude Code が呼び出しをブロックし、かつ「デプロイ手順を別の方法で再現するな」と指示する。

skill の content ライフサイクル（実務で効く挙動）

  • 呼び出されると、レンダリング済みの SKILL.md が1つのメッセージとして会話に入り、セッションの残りずっと居座る
  • Claude Code は後続ターンで skill ファイルを読み直さない。だから「タスク全体に適用してほしい指針」は一回きりの手順ではなく常設の指示として書く
  • 同一内容の再呼び出しでは「すでにロード済み」という短いメモが付くだけ。引数や dynamic context の出力が変われば全文が再追加される
  • auto-compaction 後: 各 skill の最新の呼び出しが要約の後に再添付されるが、先頭 5,000 トークンまで。合計 25,000 トークンの予算を共有し、最近呼んだものから埋めるので、多く呼んでいると古いものは丸ごと落ちる

If a skill seems to stop influencing behavior after the first response, the content is usually still present and the model is choosing other tools or approaches. 最初の応答の後に skill が挙動へ影響しなくなったように見えるとき、たいていその内容はまだ残っており、モデルが別のツールや手順を選んでいるだけである。

ツールの事前承認

allowed-tools は呼んだターンの間だけの付与で、次のメッセージで解除される。利用可能なツールを制限するものではない — 列挙されていないツールも呼べるし、通常の permission 設定が適用される。

Review project skills before trusting a repository, since a skill can grant itself broad tool access. リポジトリを信頼する前に、プロジェクトの skill を確認せよ。skill は自分自身に広範なツールアクセスを与えられるからである。

dynamic context injection

!`<command>` 構文は、skill の内容が Claude に送られる前にシェルコマンドを実行し、出力でプレースホルダを置き換える。Claude はコマンドではなく実データを受け取る。

"disableSkillShellExecution": true で無効化できる（bundled と managed skill は影響を受けない）。managed settings に置くとユーザーが上書きできない。

skill 実行時により深い推論を要求したいなら、skill の内容のどこかに ultrathink と書く。

subagent で走らせる（context: fork）

skill の内容がそのまま subagent を駆動するプロンプトになる。会話履歴にはアクセスできない。

  • 既定ではバックグラウンド実行。作業を続けられ、完了時に結果が会話に届く。background: false で呼んだターン内で待つ
  • 待機になるケース: 非対話モード（-p / Agent SDK）、CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1、同じ skill の前回の実行がまだ走っているとき、scheduled task から発火したとき
  • バックグラウンドの fork は checkpoint の外で編集を適用するので /rewind では戻せない。git で戻す

context: fork only makes sense for skills with explicit instructions. If your skill contains guidelines like “use these API conventions” without a task, the subagent receives the guidelines but no actionable prompt, and returns without meaningful output. context: fork が意味を持つのは、明示的な指示を含む skill に対してだけである。タスクを伴わず「この API 規約に従え」といった指針だけを含む skill では、subagent は指針を受け取るものの実行すべきプロンプトがなく、意味のある出力を返さずに終わる。

skill と subagent の2方向の組み合わせ:

やり方system promptタスク他にロードされるもの
context: fork の skillagent 種別からSKILL.md の内容CLAUDE.md（agent が Explore / Plan のときを除く）
skills フィールドを持つ subagentsubagent の markdown 本体Claude の委譲メッセージpreload された skill + CLAUDE.md

アクセス制御の3手段

# 全 skill を無効化（deny rules に追加）
Skill
 
# 特定の skill だけ許可 / 拒否
Skill(commit)
Skill(review-pr *)
Skill(deploy *)

Skill(name) は完全一致、Skill(name *) は引数付きの前方一致。

The user-invocable field only controls menu visibility, not Skill tool access. Use disable-model-invocation: true to block programmatic invocation. user-invocable フィールドが制御するのはメニューへの表示だけであり、Skill ツールからのアクセスは制御しない。プログラムからの起動を止めるには disable-model-invocation: true を使え。

skillOverrides 設定（SKILL.md を編集したくない、共有リポジトリの skill 向け）。/skills メニューで Space で状態を巡回し Enter で .claude/settings.local.json に保存できる。

値Claude への提示/ メニュー
"on"名前 + description表示
"name-only"名前のみ表示
"user-invocable-only"隠す表示
"off"隠す隠す

bundled skills

/doctor、/code-review、/batch、/debug、/loop、/claude-api など。prompt ベースで、詳細な指示を Claude に与えてツールで作業を統率させる（多くの built-in command が固定ロジックを直接実行するのとは対照的）。

/verify は自分で呼んだときだけ走る。 長時間・高トークンのチェックをいつ走らせるかをユーザーの手に残すため。v2.1.215 より前は Claude が自分で /verify を起動することもあった。

/code-review は v2.1.218 以降、forked subagent として走る。

/code-review runs as a forked subagent from v2.1.218; on earlier versions it ran inline and stacked. /code-review は v2.1.218 以降、forked subagent として走る。それ以前のバージョンでは inline で走り、スタッキングにも参加できた。

skill のスタッキング: メッセージの先頭で /write-tests /fix-issue 123 のように並べると、先頭 + 最大5個まで展開され、末尾のテキストが各 skill の $ARGUMENTS になる。ただし展開は「inline で動く user-invocable な skill」でない最初のトークンで止まる。したがってforked subagent として走る /code-review や、引数自体が / で始まりうる /loop はそこで打ち止めになり、そのトークン以降はすべて引数テキストとして扱われる。

disableBundledSkills で無効化できる（/doctor を除く）。/doctor は v2.1.205 以降このフラグ下でも入力でき、隠すには DISABLE_DOCTOR_COMMAND か skillOverrides の "doctor": "off" を使う。

アプリを起動して検証する3つ組:

skill目的
/runアプリを起動・操作して変更が動くのを見る
/verifyビルドして走らせ、コード変更が意図通りかを確認する。テストや型チェックに逃げない
/run-skill-generator/run と /verify にビルドと起動の仕方を教える

/run と /verify は設定なしでも動く（プロジェクト種別、README、package.json、Makefile から推測する）。ただし DB、env ファイル、GUI セッション、多段ビルドが要るプロジェクトでは推測が信頼できなくなる。/run-skill-generator はレシピを .claude/skills/run-<name>/ に記録して commit する。

skill の評価

Seeing a skill trigger tells you Claude found it, not that it did what you intended. skill が起動したのが見えたということは、Claude がそれを見つけたことを示すだけで、意図した通りに動いたことを示すわけではない。

測るべきは2つを別々に — ① 呼ばれるべきプロンプトで呼ばれるか、② 呼ばれたとき出力が期待通りか。

方法はベースライン比較。現実的なプロンプトをいくつか用意し、fresh session で skill あり / なしを走らせて比べる。

A fresh session matters because leftover context from authoring the skill will mask gaps in the written instructions. まっさらなセッションで試すことが重要なのは、skill を書いたときの context が残っていると、書かれた指示の抜けが覆い隠されてしまうからである。

トラブルシューティング

発火しない: ① description にユーザーが自然に言う語が入っているか ② What skills are available? で出るか ③ description に寄せて言い換える ④ /skill-name で直接呼ぶ。frontmatter の YAML が壊れているとメタデータ空で本体だけロードされるので、/skill-name は動くが Claude には description がない状態になる（--debug でパースエラーが見える）。

発火しすぎる: description をより具体的に、または disable-model-invocation: true。

description が途中で切れる: skill 一覧の文字数予算はモデルの context window の 1%。溢れると呼ぶ頻度が低い skill から description が落とされる。/doctor で一覧のコストと主犯を推定できる。予算は skillListingBudgetFraction（0.02 = 2%）または SLASH_COMMAND_TOOL_CHAR_BUDGET で上げられる。

そのまま使える具体例

reference 型の skill:

---
name: api-conventions
description: API design patterns for this codebase
---
 
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

task 型の skill（副作用があるので手動起動限定 + 隔離実行）:

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---
 
Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

ツールを事前承認する:

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

同梱スクリプトを権限プロンプトなしで走らせる（両方で同じ変数を使うのが要点）:

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---
 
Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

dynamic context injection（実データを埋め込んでから Claude に渡す）:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
 
## Pull request context
- PR diff: !`gh pr diff`

置換変数を使う:

---
name: session-logger
description: Log activity for this session
---
 
Log the following to logs/${CLAUDE_SESSION_ID}.log:
 
$ARGUMENTS

skill ディレクトリの構成:

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output showing expected format
└── scripts/
    └── validate.sh    # Script Claude can execute

settings から可視性を上書きする:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

eval 用プラグインを入れる:

/plugin install skill-creator@claude-plugins-official

原典で言及されている関連文書

未取得の派生リンク

グラフビュー

バックリンク