ai-docs

Extend Claude with skills

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

原典: Extend Claude with skills ／ 日本語版

一行要約

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 を置き換える）。ローカル端末のセッションでは built-in command も置き換えるが、その alias は置き換えない（プロジェクトの usage skill は /usage を置き換えるが、alias の /cost は built-in のまま走る）。plugin skill は plugin-name:skill-name の namespace なので衝突しない。

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

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

--add-dir / /add-dir で足したディレクトリは、.claude/skills/ だけでなく .claude/commands/ と .claude/agents/ もロードされる（Agent SDK の additionalDirectories / add_dirs は --add-dir として渡るので同じ）。ただし permissions.additionalDirectories 設定はファイルアクセスを与えるだけで、どれもロードしない。

worktree では探索が worktree のルートで止まる。 リンクされた git worktree で走るセッションは、親ディレクトリを worktree のルートまでしか遡らない。v2.1.277 以降は、worktree のルートに .claude/skills が無ければメインのチェックアウトの project skill を読む。

live change detection: skill ディレクトリは監視されており、追加・編集・削除は再起動なしに現セッションへ反映される。ただしセッション開始時に存在しなかったトップレベルの skills ディレクトリを作った場合は、/reload-skills で読み込む（まだ監視されていないので、そこを変えるたびに /reload-skills をやり直す）。

Cowork / cloud セッションの注意: これらは自分のマシンの ~/.claude/skills/ を読まない。routine が個人 skill を呼ぶと「見つからない」と報告される。claude.ai アカウント側で有効化するか、リポジトリの .claude/skills/ にコミットする。plugin 経由は使えない —— リポジトリの .claude/settings.json が宣言した plugin も、user 設定でだけ有効にした plugin も、cloud セッションではロードされない。

claude.ai の skill は端末にも同期される（v2.1.273 以降）

claude.ai アカウントでサインインしていれば、設定なしで ~/.claude/skills/synced/ に落ちてくる。 自分が claude.ai で作った／有効にした skill、組織が配った skill、Anthropic の bundled skill（pdf、xlsx など）が対象。起動時にバックグラウンドで落とし、走っている間は約10分ごとに claude.ai を見て、追加・編集・無効化を再起動なしに反映する。

  • 起動は遅くならない。 ダウンロードを待つのはその skill を呼ぶときだけ。だから短い非対話実行は、新しい skill が落ち切る前に終わりうる。待たせたいなら CLAUDE_CODE_SYNC_SKILLS=1
  • 同期しないセッション: /login の資格情報を使わないもの（API キー、ANTHROPIC_AUTH_TOKEN、CLAUDE_CODE_OAUTH_TOKEN、apiKeyHelper）、feature flag を取りに行かないもの（Bedrock、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC）、bare モードと --safe-mode、managed で skill を plugin 限定にしている場合、--setting-sources に user が無い場合
  • 一度落ちた skill はディスクに残る。 同じアカウントなら claude.ai に繋がらなくても読まれる
  • 止めるなら syncClaudeAiSkills: false（user settings）。次回起動時に ~/.claude/skills/.trash/ へ移される
  • 名前が衝突したら、ローカルのほうが /<name> を取る。 同期された側は /anthropic-skills:<name> でだけ呼べる（v2.1.269 より前は短い名前しか無かった）。/ メニュー・/skills・/context では、同期された skill は短い名前で出て、短い名前を他のコマンドが使っている間だけ完全名で出る。/skills の一覧の下に、短い名前を失った同期 skill ごとの注記が出る（~/.claude/ の自分の skill やコマンドが名前を使っていれば、何を改名・削除すれば空くかも出る。v2.1.281 以降）
  • anthropic-skills という名前とその名前空間（anthropic-skills:pdf など）は、同期 skill 用に予約されている（サインインの有無に関わらず）。skill フォルダ・frontmatter の name・.claude/commands/ のファイル・保存した workflow がこの名前だと読み込まれず、起動時の通知が改名すべき最初の項目を名指しする。同じ名前の plugin は読み込まれる（同名の skill があれば /anthropic-skills:<name> は同期 skill を走らせる）。同じ名前の MCP サーバはつながるが、prompt がコマンドとして出ない
  • permission の allow で同期 skill を確認なしに通すには、予約名前空間の中で名指しする（Skill(anthropic-skills:pdf)、全部なら Skill(anthropic-skills *)）。名前空間の外の前方一致（Skill(anthropic *)）は中の名前に当たらない。deny は逆に、書いた名前より広く効く —— Skill(anthropic-skills:deploy) は Claude Desktop が plugin として届けた同じ skill も、plugin 形の Skill(deploy:deploy) は同期 skill も止める（同期 skill 以外の場合は下の「アクセス制御の3手段」）
  • 同期は片道（ダウンロードのみ）。 ~/.claude/skills/synced/ の下を自分や Claude が編集しても claude.ai には保存されず、次の同期で上書き・削除されうる。直すなら claude.ai の側で直す
  • どれが同期されたかは /skills の claude.ai sync で見る

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, and apply the same conciseness test you would for CLAUDE.md content.

本体は簡潔に保て。skill はいったんロードされると、その内容がターンをまたいで context に残り続けるため、1行ごとが繰り返し発生するトークンコストになる。やり方や理由を語るのではなく何をすべきかを述べ、CLAUDE.md の内容に対するのと同じ簡潔さの基準を当てよ。

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 も受け付ける（大文字小文字不問）。

綴りを間違えても何も言われない。 フィールド名は表と完全一致していなければならず（ハイフンも含む。when_to_use だけがアンダースコア）、知らないフィールドは黙って無視される。--- の間の YAML がパースできなければ、skill は「フィールドが1つも設定されていない」状態でロードされる（これも黙って起きる。--debug でパースエラーが見える）。

.claude/commands/ のコマンドファイルも同じフィールドを受け付ける —— 例外は name と paths の2つ。

フィールド説明
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
hookshook の定義。skill を呼んだ時点で登録され、skill が終わってもセッションの残り全体で走り続ける（allowed-tools と違って解除されない）。1回で終わらせたいなら各 hook に once: true（hooks）
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/ 配下frontmatter name またはディレクトリ名.claude/skills/deploy-staging/SKILL.md → /deploy-staging、name: deploy なら /deploy
ネストした .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
${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: trueYes自分からは呼べないdescription も 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 が呼び出しをブロックし、かつ「デプロイ手順を別の方法で再現するな」と指示する。

名前を書く位置で意味が変わる。 メッセージの先頭の /deploy staging は skill を直接走らせる。平文の後ろに区切った語として書いた go ahead and /deploy to staging は何も直接走らせず、そのメッセージに限って走らせてよいという許可になる（走らせるかは Claude が文面から判断する）。許可せずに skill の話をしたいなら / を付けない。

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

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

途中から skill に従わなくなったら、原典のトラブルシューティングは場合を3つに分ける:

場合打つ手
毎回必ず守るべき規則を飛ばしたhook に移す。hook はイベントのたびに走り、Claude が skill に従っているかに関係しない。skill と一緒に置くなら skill の hooks frontmatter に書く（呼んだ時点からセッション終了まで有効）
判断して当てはめる指針を飛ばしたタスク全体に掛かる書き方にする（「テストを走らせて」ではなく「編集のたびにテストを走らせて」）。ファイルは後続ターンで読み直されない
compaction があったskill をもう一度呼ぶ。compaction 後は先頭しか残らないことがあるので、一番大事な指示は SKILL.md の先頭近くに置く

ツールの事前承認

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

Workspace trust doesn’t gate this field. Claude Code applies a project skill’s allowed-tools even in a -p run in a folder you’ve never trusted. A skill can grant itself broad tool access, so review the allowed-tools of skills checked into a repository before you run Claude Code there.

workspace trust はこのフィールドを関門にしない。プロジェクトの skill の allowed-tools は、一度も信頼したことのないフォルダでの -p 実行でも適用される。 skill は自分自身に広範なツールアクセスを与えられるので、リポジトリにコミットされた skill の allowed-tools は、そこで Claude Code を走らせる前に確認せよ。

組織として止めるなら managed settings の allowManagedPermissionRulesOnly（v2.1.282 以降）。project / personal skill などの allowed-tools が無視され、列挙されたツールは組織の managed rules と通常の permission プロンプトを通る。そのセッションで無視された skill は /status に一覧される。

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 *) は引数付きの前方一致。

deny は書いた名前より広く止める:

deny に書いた名前例一緒に止まるもの
aliasSkill(review)bundled の /code-review（/review という alias 経由）
修飾しない名前Skill(deploy)ネストした apps/web:deploy
パラメータ形Skill(skill:deploy)その skill を、alias や表示名も含めどの名前で呼んでも

With user-invocable: false, you can’t invoke the skill, but Claude still can. To keep Claude from invoking it through the Skill tool, set disable-model-invocation: true.

user-invocable: false にすると自分では呼べなくなるが、Claude は依然として呼べる。Skill ツール経由での起動も止めたいなら disable-model-invocation: true を設定せよ。

disable-model-invocation: true は skill を Claude の context から丸ごと外す。

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

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

skillOverrides に無い skill は "on" 扱い。 "off" は Remote Control と Agent SDK に広告されるコマンド一覧からも隠す（フルネームで呼んでも skillOverrides のエラーが返る）。

bundled skills

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

/verify は自分で呼んだときだけ走る。 長時間・高トークンのチェックをいつ走らせるかをユーザーの手に残すため。

ただし自前の verify / simplify skill があると、コミットの直前に走る（v2.1.286 以降）。セッション開始時にその名前の skill があれば、Claude Code のコミット指示が docs やテストだけの変更を除き、各コミットの直前に走らせるよう Claude に告げる。条件は3つ —— ① enterprise / personal / project / 追加ディレクトリの skill か .claude/commands/ のファイルであること（/verify がリポジトリのルートに記録したレシピは project skill なので数える。bundled の /verify /simplify・plugin skill・claude.ai の skill は数えない）、② Claude が呼べること（disable-model-invocation: true なら告げられない）、③ includeGitInstructions を切っていないこと。

/claude-api はサブコマンドで workflow を始める（/claude-api migrate など）。migrate（新しいモデルへ移行）、upgrade（SDK のメジャー版を上げる。v2.1.236 以降）、managed-agents-onboard、prompt-audit（古いモデル向けに書かれた指示を探して diff で直す。v2.1.221 以降）、cost-optimize（v2.1.247 以降）、build-eval / hillclimb（v2.1.259 以降）、preserved-thinking-migration（preserved thinking を無効にする編集を探す。v2.1.282 以降）。コードが anthropic か @anthropic-ai/sdk を import していれば自動で有効になる。

/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 は載っているだけで context を食い、説明文は黙って削られる

Every skill in the skill listing adds to your context on every turn, whether or not Claude ever uses it.

skill 一覧にあるすべての skill が、Claude が一度も使わなくても、毎ターンあなたの context を食う。

一覧の予算はモデルの context window の 1%。溢れたときの落とし方が効いてくる。

The listing always contains every skill name, but if you have many skills, Claude Code drops some descriptions to fit the listing’s character budget, which removes the keywords Claude needs to match your request. The budget scales at 1% of the model’s context window. When the listing overflows, Claude Code drops descriptions starting with the skills you invoke least, so the skills you use most keep their full text.

一覧には常にすべての skill 名が入るが、skill が多いと Claude Code は予算に収まるよう一部の説明文を落とす。そのとき、あなたの要求に合致させるために Claude が必要とするキーワードが消える。 予算はモデルの context window の 1% に比例する。溢れた場合、Claude Code は呼び出し回数が最も少ない skill から説明文を落とす。よく使う skill は全文が残る。

つまり「使っていない skill が、使いたい skill の説明を削る」のではなく、使っていない skill の説明が先に消える。 症状は「新しく入れた skill が発火しない」という形で出る。

打つ手:

手段効果
/skill-doctorskill ごとの context コストと使用頻度、一度も呼ばれていないものと切り方を報告（v2.1.252 以降）
/doctor一覧全体の context コストの見積もりと、上位の寄与者
/context の Skills 行予算適用後のサイズ（モデルが実際に受け取る量。v2.1.196 より前は適用前の値が出ていた）
skillListingBudgetFraction予算の割合を上げる（0.02 = 2%）
skillOverrides の "name-only"低優先の skill を名前だけにして予算を空ける
description / when_to_use を詰める1エントリの合計は予算に関わらず 1,536 文字が上限（skillListingMaxDescChars で変えられる）。要点を先頭に置く
SLASH_COMMAND_TOOL_CHAR_BUDGET予算を割合ではなく固定の文字数で指定する

/skill-doctor は Remote Control 経由では使えない（Skill usage reports are not available on this connection. が返る）。セッションが走っている機械の端末で実行する。

skill の評価

Seeing a skill trigger tells you Claude found it, not that it did what you intended.

skill が起動したのが見えたということは、Claude がそれを見つけたことを示すだけで、意図した通りに動いたことを示すわけではない。

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

方法はベースライン比較。現実的なプロンプトをいくつか用意し、fresh session で skill あり / なしを走らせて比べる。「なし」の作り方は出どころで違う —— personal / project skill は skillOverrides で "off"、plugin の skill には skillOverrides が効かないので claude plugin eval（plugin を読み込まない回を繰り返す）を使う。

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。

個人 skill が消えた: ~/.claude/skills/.trash/ を見る。v2.1.280 より前は、~/.claude/skills/ に manifest.json があると、そこに列挙された skill フォルダが .trash/ の日時つきフォルダへ移され、ロードされなくなっていた（claude.ai からの同期は synced サブフォルダに落とすだけで、自分が作ったフォルダを動かしも消しもしない）。戻すには日時つきフォルダから ~/.claude/skills/ へ移し直す。retention sweep が既定で 30 日後に trash を消すので、それより前に。

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

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

バックリンク