Claude Code Skills 使い方完全ガイド｜SKILL.mdの作り方・保存場所・Agent Plugins対応【2026年8月最新】

Claude Code Skills（Agent Skills）とは、.claude/skills/<スキル名>/SKILL.md にやり方を書いておくと、Claude が必要になったときだけ読み込んで実行してくれる再利用可能な指示パッケージです。CLAUDE.md が常時ロードされる「事実の置き場」なのに対し、Skills は呼ばれたときだけロードされる「手順の置き場」で、トークンコストをほぼ増やさずに大量のノウハウを抱えられます。

2026年8月時点では、Claude Code のカスタムスラッシュコマンドは Skills に統合済みで、.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy として同じように動きます。さらに、SKILL.md を束ねる「プラグイン」の仕様が Claude Code 独自形式と業界標準 Agent Plugins 1.0.0 の2系統に分かれ始めており、この違いを踏まえた設計が必要になっています。

この記事でわかること

• Skills の仕組みと、CLAUDE.md・スラッシュコマンド・MCP・Hooks との使い分け
• SKILL.md のフロントマター全フィールドと、標準6フィールドしか使えない配布経路の落とし穴
• 保存場所4種（Enterprise / Personal / Project / Plugin）の優先順位とモノレポ運用
• 2026年8月時点のバンドルスキル一覧（/run・/verify・/run-skill-generator ほか）
• 「Skill が途中から効かなくなる」「そもそも発動しない」の原因と対処
• Agent Plugins 1.0.0 と Claude Code プラグインの関係
• 料金・セキュリティ・法人導入時の確認事項（ZDR 対象外など）

こんな方に役立ちます

• 毎回同じ指示を Claude Code に貼り付けている開発者
• CLAUDE.md が肥大化してコンテキストを圧迫しているプロジェクト
• チームや組織単位でノウハウを配布したいリードエンジニア・情報システム部門
• Skills を作ったのに動かず、原因を切り分けたい人

Claude Code そのものの全体像から確認したい場合は Claude Codeとは？特徴・料金・使い方を完全解説 を先に読むと理解が早くなります。

Claude Code Skills（Agent Skills）とは

出典: Anthropic Engineering Blog

Skills は「いつ使うかを書いたメタデータ」＋「何をするかを書いた手順書（SKILL.md）」＋「任意のスクリプト・参照ファイル」をひとつのディレクトリにまとめたものです。公式ドキュメントは Skills を「Claude のツールキットに追加される能力」と表現しており、Claude が状況に応じて自動で使うか、ユーザーが /skill-name で直接呼び出します。

いつ Skill にすべきか（公式の判断基準）

公式ドキュメントは、Skill を作るタイミングを明快に示しています。

• 同じ指示・チェックリスト・複数ステップの手順を毎回チャットに貼り付けているとき
• CLAUDE.md の一節が「事実」ではなく「手順」に育ってしまったとき

逆に言えば、1回きりのタスクや、プロジェクト全体に常時効かせたい規約は Skill にする必要がありません。

設計の中核は「使うときだけ読む」

Skills が効率的なのは、Claude が起動時に読むのが各 Skill の name と description だけだからです。本文（SKILL.md 本体）と参照ファイルは、実際に呼ばれた時点で初めてコンテキストに入ります。

この構造のおかげで、数十個の Skill を「待機」させても常時コストはメタデータ分だけで済みます。SKILL.md 本体は500行以内に収め、詳細は参照ファイルに逃がすのが公式推奨です。

Agent Skills オープン標準に準拠している

Claude Code の Skills は、Anthropic が策定して公開した Agent Skills オープン標準（agentskills.io） に準拠しています。2026年8月時点で、Claude Code / Claude（claude.ai）/ ChatGPT・Codex / GitHub Copilot / VS Code / Cursor / Gemini CLI / Goose / OpenCode / OpenHands / Kiro / Roo Code / Amp / Junie（JetBrains）ほか、非常に多くのクライアントが対応を表明しており、SKILL.md は事実上の業界標準フォーマットになりつつあります。

ただし Claude Code は標準を拡張しています。呼び出し制御・サブエージェント実行・動的コンテキスト注入などは Claude Code 独自の機能で、他クライアントでは無視されるか動作しません。

まずは動かす：最初の Skill を作る4ステップ

最小構成の Skill を1つ作れば、仕組みはすぐ理解できます。ここでは PR レビュー用の pr-review を例にします。

ステップ1: ディレクトリを作る

mkdir -p .claude/skills/pr-review

SKILL.md は必ず <スキル名>/ 直下に置きます。pr-review/docs/SKILL.md のように1階層深いと認識されません。

ステップ2: SKILL.md を書く

---
name: pr-review
description: GitHub PRをレビューする。差分の意図・テスト追加・規約違反の3観点で評価する
when_to_use: ユーザーがPRレビュー、差分確認、コードレビューを依頼したとき
allowed-tools: Bash(gh pr diff *) Bash(gh pr view *)
---

# PR Review

## 手順1: 差分の取得
!`gh pr diff || true`

## 手順2: 評価観点
1. 差分の意図がPR本文・コミットメッセージと一致しているか
2. 新しいロジックにテストが追加されているか
3. CLAUDE.md 記載のコーディング規約に反していないか

## 手順3: 出力形式
- 各観点に「OK / 要修正 / 確認希望」を付ける
- 要修正には具体的な修正案を添える

ステップ3: 動作を確認する

Claude Code を起動し、/skills で一覧に pr-review が出るか確認します。次に「PR #42 をレビューして」と依頼すると、description に基づいて Claude が自動で呼び出します。明示的に呼びたいときは /pr-review とタイプします。

既存の skills ディレクトリ配下での追加・編集・削除は再起動なしで即反映されます。ただし、セッション開始時に存在しなかったトップレベルの skills ディレクトリを新規作成した場合だけは再起動が必要です。

ステップ4: チームに配る

.claude/skills/pr-review/ をリポジトリにコミットします。チームメンバーが git pull した瞬間から同じ Skill が使えます。

SKILL.md の書き方とフロントマター

出典: Claude Code 公式ドキュメント

SKILL.md は「YAML フロントマター」＋「Markdown 本文」だけの構造です。フロントマターは全フィールドが任意で、公式が実質必須としているのは description のみです。

フロントマター全フィールド（Claude Code 版・2026年8月時点）

真偽値は true/false に加えて yes/no/on/off/1/0 も受理されます（Claude Code v2.1.218 以降。それ以前は true/false のみ）。

description の書き方が発動率を決める

最も重要なのは description です。description: This skill is for code review のような抽象的な記述では、Claude は「今これを呼ぶべきか」を判断できません。呼ばれるべき状況のフレーズを具体的に並べるのが効きます。

• ❌ 弱い例: PRをレビューするスキル
• ⭕ 強い例: GitHub PRをレビューする。差分の意図・テスト追加・規約違反の3観点で評価する。PRレビュー・差分確認・コードレビュー依頼を受けたときに使う

description と when_to_use は合算して1,536文字で切り詰められます（skillListingMaxDescChars で変更可）。長く書きすぎると末尾が落ちる点に注意してください。

【要注意】標準6フィールドしか使えない配布経路がある

ここは日本語の解説記事でほとんど触れられていない、実務で確実にハマるポイントです。

標準外フィールドが混ざっていると、アップロードやパッケージングがハードエラーで失敗します。

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

Cowork やクラウドセッション向けに personal skill を有効化する場合も claude.ai へのアップロードになるため、同じ6フィールド制限がかかります。「Claude Code で動く SKILL.md がそのまま claude.ai に上げられるとは限らない」と覚えておくと事故を防げます。

なお Agent Skills 標準側では、name は1〜64文字・小文字英数字とハイフンのみ・連続ハイフン不可・親ディレクトリ名と一致必須、description は1〜1024文字と定められています。検証には skills-ref validate ./my-skill が使えます。

文字列置換変数（全11種）

${CLAUDE_SKILL_DIR} と ${CLAUDE_PROJECT_DIR} は本文と allowed-tools の Bash ルールの両方で置換されます。これを利用すると、同梱スクリプトを許可プロンプトなしで実行できます。

---
name: render-chart
description: CSVファイルからチャートを描画する
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---
`${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` を実行してチャートを描画する。

複数語の引数はシェルと同じくクォートで囲みます（/my-skill "hello world" second なら $0 は hello world）。リテラルの $ はバックスラッシュでエスケープします。

呼び出し制御マトリクス

本番デプロイのように誤発動されると困る手順は disable-model-invocation: true、Claude にだけ持たせたい背景知識は user-invocable: false が適しています。v2.1.196 以降は disable-model-invocation: true がスケジュールタスクからの発火も抑止します。

保存場所4種と優先順位

Claude Code が Skill を探す場所は4つです。

managed settings の場所は macOS が /Library/Application Support/ClaudeCode/、Linux / WSL が /etc/claude-code/、Windows が C:\Program Files\ClaudeCode\ です。

優先順位のルール

• レベル間の強さは Enterprise > Personal > Project。「プロジェクト固有の方が強い」と誤解されがちですが、Personal が Project より優先されます
• どのレベルの Skill もバンドルスキルを上書きできますが、バンドルスキルのエイリアスは上書きできません（/code-review は上書きできても /review は元のバンドルが動く）
• Plugin skill は plugin-name:skill-name の名前空間を持つため衝突しません
• 同名の skill と command があれば skill が優先
• ローカルの skill / command は claude.ai から同期された skill より優先

synced というフォルダ名は各 skills ロケーションで予約済みなので、スキル名には使えません。

用途別の置き場所

モノレポでのネスト検出

作業ディレクトリ配下にネストした .claude/skills/ は、起動時にはロードされません。Claude がそのサブディレクトリのファイルを読み書きした時点でロードされ、以降セッション中は有効になります。

同名衝突時はディレクトリ修飾名になります（apps/web/.claude/skills/deploy/ → /apps/web:deploy）。非修飾の /deploy を叩くとプロジェクトルート版が動き、修飾版の一覧が自動で提示されます。

なお、プロジェクト skill は起動ディレクトリからリポジトリルートまでの各親ディレクトリの .claude/skills/ もロードされます。--add-dir / /add-dir で追加したディレクトリも例外的に .claude/skills/ と .claude/commands/ を自動ロードしますが、permissions.additionalDirectories 設定ではロードされません。

カスタムスラッシュコマンドは Skills に統合された

2026年時点の Claude Code では、カスタムコマンドは Skills にマージ済みです。公式ドキュメントは「.claude/commands/deploy.md にあるファイルと .claude/skills/deploy/SKILL.md にあるスキルは、どちらも /deploy を作り、同じように動く」と明記しています。

既存の .claude/commands/ はそのまま動き続けるため、慌てて移行する必要はありません。ただし、補助ファイルを持たせたい・Claude に自動判断させたい場合は Skills に寄せるのが自然です。スラッシュコマンド側の詳細は Claude Code スラッシュコマンド完全ガイド で整理しています。

バンドルスキル（組み込みスキル）一覧

Claude Code には最初からいくつかの Skill が同梱されています。2026年8月時点で確認できる主なものは以下です（バージョンにより増減するため、実環境では /help のコマンド一覧で確認してください）。

バンドルスキルはプロンプトベースで、Claude に詳細な指示を渡してツールで遂行させます。固定ロジックを直接実行する従来の組み込みコマンドとは性質が異なります。また、Skill は最大6個まで連鎖呼び出しできます（/skill-a /skill-b do XYZ のように書ける）。

/run /verify /run-skill-generator の使い方

この3つは Claude Code v2.1.145 以降で利用できます。

/run と /verify は設定なしでも動きますが、DB・env ファイル・GUI セッション・多段ビルドが必要なプロジェクトでは起動手順の推論が不安定になります。そこで一度だけ /run-skill-generator を実行し、クリーン環境から起動を再現した手順を .claude/skills/run-<name>/ にプロジェクト固有スキルとして保存・コミットします。以降はリポジトリ内の全エージェントが同じレシピを使えます。ビルド・起動手順が変わったら再実行します。

/verify 自身もレシピを記録できます（v2.1.200 以降）。リポジトリルートの .claude/skills/verify/SKILL.md に書き込み、ルートに置かれた場合はバンドル版を置き換えます。v2.1.205 以降は「実行が失敗した／手順が欠けていた」ときだけ更新されるようになり、以前のようにマージコンフリクトが頻発することはなくなりました。

なお /verify は v2.1.215 以降、ユーザーが呼んだときだけ実行されます（長時間・高トークンの検査を勝手に走らせないため）。

バンドルスキルを無効化する

disableBundledSkills 設定（環境変数 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1）で無効化できます。プラグイン・.claude/skills/・.claude/commands/ の Skill は影響を受けません。ただし /doctor だけは残ります。/doctor も消したい場合は DISABLE_DOCTOR_COMMAND 環境変数、または skillOverrides で "doctor": "off" を指定します（v2.1.205 以降）。

Skill が発動しない・途中から効かなくなるときの原因

「作ったのに呼ばれない」「最初は効いたのに後半で無視される」は Skills 最大のつまずきポイントです。原因はほぼ次の3系統に分類できます。

原因1: description が弱く、発動判断ができていない

最頻出です。Claude が見ているのは name と description（＋when_to_use）だけなので、ここに「呼ばれるべき状況」が書かれていなければ発動しません。トリガーとなる言い回しを列挙し直すのが第一の対処です。

原因2: スキル一覧のコンテキスト予算を超えている

Skill の数が増えると、一覧（name + description）が常時コンテキストを占めます。この一覧に割り当てられる予算はモデルのコンテキストウィンドウの1%がデフォルトです。

Skill を増やしすぎると、description が切り詰められて発動しなくなるという運用上の壁があります。「たくさん作れば便利」ではなく、常用しないものは隠す設計が必要です。トークン全体の削減については Claude Code コスト最適化ガイド も参考になります。

原因3: スキル本文のライフサイクルを誤解している

これがほとんど解説されていない重要仕様です。

• 呼び出された SKILL.md は1つのメッセージとして会話に入り、セッション終了までそこに残り続ける
• 残るのは指示だけ。allowed-tools の事前承認は次のメッセージ送信でクリアされる
• Claude Code は後続ターンでスキルファイルを再読み込みしない。タスク全体に効かせたい内容は「常設の指示」として書く必要がある
• 同一内容の再呼び出しは「既にロード済み」という短いメモが追加されるだけ。引数や動的コンテキストの出力が変わって内容が異なれば全文が再追加される
• 自動コンパクション時は、各スキルの最新呼び出しを要約の後に再添付するが、各スキル先頭5,000トークンまで／再添付スキル合計25,000トークンという共有予算がある。直近の呼び出しから埋めるため、多数呼んでいると古いスキルは丸ごと落ちる

つまり「最初の応答以降スキルが効かない」ように見えるとき、内容はまだコンテキストにあるのに、モデルが別の手段を選んでいるだけというケースが少なくありません。対処は description と指示文の強化か、hooks による決定論的な強制です。Hooks 側の詳しい使い方は Claude Code Hooks 活用ガイド、両者の役割分担は Claude Code の Skills と Hooks の違い で整理しています。

症状別チェック表

skillOverrides で SKILL.md を編集せず可視性を制御する

.claude/settings.local.json に書きます。/skills メニューでスキルをハイライトし、Space で状態を巡回、Enter で保存することもできます。

v2.1.199 以降、"off" は Remote Control クライアントや Agent SDK の呼び出し側に広告されるコマンド一覧からも隠されます。なお plugin skill には skillOverrides が効きません。プラグイン側は /plugin で管理します。

よく使う応用パターン4つ

1. 動的コンテキスト注入（!`command`）

SKILL.md 本文に !`コマンド` と書くと、本文が Claude に渡る前にシェルコマンドが実行され、出力でプレースホルダが置換されます。git の状態や PR 差分など、毎回最新を取りたい情報を自動で同梱できます。

## 現在のブランチ状況
!`git status --short`

## 最近のコミット
!`git log --oneline -10 || true`

実務上の注意点は以下です。

• 実行ディレクトリはセッションシェルのカレントディレクトリ。パスは ${CLAUDE_SKILL_DIR} / ${CLAUDE_PROJECT_DIR} で指定する
• 1つでもコマンドが失敗すると呼び出し全体が中断され、Claude はそのスキル内容を一切見ない。非ゼロで終わりうるコマンドには || true を付ける（検索・比較系の終了コード1だけは正常扱い）
• タイムアウトは Bash ツール既定の2分。出力が大きい場合はファイルパス＋短いプレビューとして届く
• 注入コマンドは許可プロンプトを出さない。allow 以外（ask を含む）の判定が出た時点で中断される。allowed-tools で事前承認すれば通るが、ask / deny ルールにマッチする場合は allowed-tools があっても中断される
• shell: bash を指定していて bash が存在しない環境（Git Bash 無しの Windows）では呼び出し自体が失敗する

2. サブエージェント分離実行（context: fork）

巨大な探索や多数ファイルの読み込みが必要な Skill は、メインコンテキストを汚さないようサブエージェントに分離できます。

---
name: dependency-audit
description: package.jsonの依存関係を全件監査する
context: fork
agent: Explore
background: false
---

v2.1.218 以降、フォークは既定でバックグラウンド実行になり、作業を続けたまま完了時に結果が返ります。同一ターン内で結果を待ちたい場合は background: false を指定します。非対話モード（-p / Agent SDK）、CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1、同じスキルの先行フォークが実行中、といった条件では指定しなくても待機になります。

注意点として、バックグラウンドフォークは狭いツールセットで動くため、必要なツールが範囲外なら background: false にします。また、バックグラウンドフォークによる編集はセッションのチェックポイント外で適用されるため /rewind では戻せません。git で戻す前提にしてください。

公式は context: fork を「明示的な指示を持つスキル専用」と警告しています。「このAPI規約に従え」のようなガイドライン型では、サブエージェントが実行すべきタスクを受け取れず無意味な結果を返します。サブエージェント全般の設計は Claude Code サブエージェント活用ガイド を参照してください。

3. ツール事前承認（allowed-tools）

定型的な Bash コマンドを毎回承認するのは煩雑です。allowed-tools に指定しておけば、その Skill を呼んだターンだけ承認を省略できます。

allowed-tools: Bash(git add *) Bash(git commit *) Bash(git push *)

allowed-tools はツールを制限するものではありません。未記載のツールは通常の permission 設定に従います。セッション全体に効かせたい場合は permission 設定の allow ルールを使います。

4. ファイルパスベースの自動発動（paths）

特定のファイル glob を扱っているときだけ発動させたい Skill には paths が有効です。

---
name: react-component-style
description: Reactコンポーネントのスタイル規約を適用する
paths:
  - "src/components/**/*.tsx"
---

「TSX を編集する場面でだけスタイル規約を呼ぶ」といった、状況依存の自動発動が実現できます。

Skills と CLAUDE.md・MCP・Hooks・サブエージェントの使い分け

Claude Code には似た拡張機構が複数あり、混同されがちです。「いつ発動するか」と「コンテキストにどう影響するか」で切り分けるのが実務的です。

分かれ目はシンプルです。常時効かせたいなら CLAUDE.md、条件付きで効かせたいなら Skills、絶対に外したくないなら Hooks、外部システムに触るなら MCP です。MCP の基礎は MCP（Model Context Protocol）とは、Claude Code での接続手順は Claude Code × MCP 連携ガイド にまとめています。

Agent Plugins 1.0.0 と Claude Code プラグインの関係

2026年8月時点で押さえておくべき最大の変化は、SKILL.md（Agent Skills 標準）は共通のまま、「束ね方」＝プラグイン形式が2系統に分岐していることです。

Agent Plugins 1.0.0 は 2026年8月に公開された、Agent Skills と MCP サーバーを1フォルダにまとめるベンダー中立のオープン標準です。Vercel が提案し、AWS / Anysphere（Cursor）/ GitHub / Microsoft / OpenAI が改良に加わり、憲章で単一ベンダーがメンテナの過半数を占めることを禁じています。

論点として押さえておきたいのは次の2つです。

• SKILL.md フォーマットを生んだ Anthropic は Core Maintainers に入っていない。標準の起点でありながらガバナンスには参加していない点が海外メディアで指摘されています
• Claude Code のプラグイン形式は Agent Plugins 1.0.0 とは別物。SKILL.md 単体はどちらでも通用しますが、パッケージのレイアウトとマニフェストは互換ではありません

また 1.0.0 の段階では、パーミッションモデル・サンドボックス・署名検証・シークレット機構が未定義であることが仕様側で明記されています（1.1.0 がワーキングドラフト）。配布物を無条件に信頼しない運用が引き続き必要です。

Agent Plugins 側の詳細は Agent Plugins 1.0.0とは？MCPとAgent Skillsを束ねる新標準 で解説しています。

現時点の実務判断としては、Claude Code だけで使うなら Claude Code プラグイン形式、複数のエージェント製品へ配りたいなら SKILL.md 単体（標準6フィールド）で持ち、束ね方は配布先ごとに用意する、という切り分けが安全です。

Skill の入手と配布方法

出典: anthropics/skills GitHub

1. Anthropic 公式スキル（プラグインマーケットプレイス経由）

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

anthropics/skills には Creative & Design / Development & Technical / Enterprise & Communication / Document Skills（PDF・DOCX・PPTX・XLSX）のカテゴリに加え、仕様（./spec）とテンプレート（./template）も同梱されています。

コミュニティ向けには /plugin marketplace add anthropics/claude-plugins-community が用意されており、公式マーケットプレイス claude-plugins-official は初回の対話起動時に自動登録されます。

2. npx skills CLI（Anthropic 公式ではない点に注意）

npx skills は Vercel Labs が開発したオープンソース CLI（vercel-labs/skills）で、Anthropic 公式ツールではありません。レジストリは npm ではなく GitHub で、owner/repo がそのままリポジトリにマップされます。

# リポジトリ内のスキル一覧を確認
npx skills add <owner/repo> --list

# 個別に指定してインストール
npx skills add <owner/repo> --skill <name> --skill <name>

# 対象エージェントを指定
npx skills add <owner/repo> -a claude-code -a opencode

# 非対話（CI/CD向け）
npx skills add <owner/repo> --skill <name> -g -a claude-code -y

取得先は .agents/skills/ または .claude/skills/ です。第三者リポジトリから取得する以上、内容のレビューは自己責任になります。

3. 自作スキルをプラグイン化して配る

Claude Code は、スキルフォルダに .claude-plugin/plugin.json を置くだけで <name>@skills-dir プラグインとして読み込みます。マーケットプレイス登録もインストールも不要です。

claude plugin init my-tool

これで ~/.claude/skills/my-tool/ に plugin.json と SKILL.md の雛形が生成され、次のセッションから自動ロードされます。プラグインが1スキルだけの場合は skills/ を作らずプラグインルート直下に SKILL.md を置けます。ローカルテストは claude --plugin-dir ./my-plugin（zip も可）や claude --plugin-url https://.../my-plugin.zip で行えます。

なお、プロジェクトの .claude/skills/ 配下でプラグイン化する場合は、workspace trust ダイアログでの承認が先に必要です。チーム展開の設計全般は Claude Code チーム導入ガイド が参考になります。

有志が公開しているスキル集を探す場合は Awesome Claude Code ガイド や Superpowers（Claude Code スキル集）ガイド も入口として使えます。

4. スキルを削除する

• Personal / Project: ディレクトリを削除（/skills からは即座に消えるが、既に呼ばれた内容はセッション終了までコンテキストに残る）
• Enterprise: 管理者が managed settings ディレクトリ内の該当ディレクトリを削除
• Plugin: /plugin メニューまたは /plugin uninstall <plugin-name>@<marketplace-name> → /reload-plugins か再起動

Claude Code・claude.ai・API・Cowork での違い

Agent Skills は複数のサーフェスで動きますが、カスタム Skill はサーフェス間で同期しません。claude.ai にアップロードしたものは API では使えず、API にアップロードしたものは claude.ai では使えません。Claude Code の Skill はファイルシステムベースで、どちらとも別物です。

プリビルトの pptx / xlsx / docx / pdf は Claude API・claude.ai・Claude Platform on AWS・Microsoft Foundry で利用でき、Claude Code では使えません。一方、オープンソースの Claude API skill は Claude Code にバンドル済み（/claude-api）です。

Cowork / クラウドセッションでの挙動差

Cowork セッションやクラウドセッション（routines を含む）はローカルの ~/.claude/skills/ を読みません。claude.ai アカウントで有効にしたスキルをセッション開始時に同期します。クラウドセッションは加えて、クローンしたリポジトリの .claude/skills/ も読みます。

ローカルの通常セッションで同期スキルを使うには、非対話モードで一度ダウンロードします。

CLAUDE_CODE_SYNC_SKILLS=1 claude -p "List the skills you have available"

~/.claude/skills/synced/ に保存され、以降のローカルセッションでも読まれます。claude.ai 側で変更したら再実行が必要です。

同期スキルの扱いには重要な差があります。

• 名前が組み込みコマンド・バンドルスキル・ローカル各レベル・plugin skill・.claude/commands/・MCP prompt のいずれかと衝突すると、同期スキル側がスキップされます
• デスクトップの Cowork セッションでは ! コマンド行がすべてプレースホルダに置換されます
• それ以外のローカルセッションでは ! コマンドは実行されず、@ 参照のファイル添付も行われず、${CLAUDE_PROJECT_DIR} などの置換も起きません（リテラル文字列として Claude に届きます）

Routines での実行を前提に Skill を書く場合は、この差分を想定した内容にしておく必要があります。詳細は Claude Code Routines 活用ガイド を参照してください。

料金：Skills 自体は追加課金なし

Skills 機能そのものに追加料金はかかりません。 Claude Code に含まれる機能で、実質的なコストは消費トークンです。

2026年8月時点の公式料金ページの記載は以下のとおりです（価格は改定されることがあるため、契約前に公式で確認してください）。

claude.ai 側でカスタム Skill をアップロードできるのは Pro / Max / Team / Enterprise かつコード実行が有効な場合です。Claude API で使う場合は code execution tool の実行時間とコンテナストレージが標準課金されます。

コスト面で注意すべきは、Skill の数が増えるほど一覧が常時コンテキストを占める点です。プラン別の詳細な違いは Claude Code の料金プラン解説 にまとめています。

セキュリティと法人導入時の確認事項

Anthropic 公式は Skills について「自分で作ったもの、または Anthropic から入手したものだけを使うこと」と明確に警告しています。Skill は指示とコードで Claude に新しい能力を与えるため、悪意ある Skill は本来の目的と異なる形でツール実行やコード実行を指示できます。

公式が挙げる主なリスク

• 徹底的な監査が必要: SKILL.md・スクリプト・画像・その他リソースを全ファイル確認し、想定外のネットワーク呼び出しやファイルアクセスがないか探す
• 外部ソースは特に危険: 外部 URL からデータを取得する Skill は、取得内容に悪意ある指示が混入しうる。信頼できる Skill でも依存先が後から侵害される可能性がある
• ツールの悪用: ファイル操作・bash・コード実行を有害な形で呼び出せる
• データ露出: 機微データにアクセスできる Skill は、情報を外部へ送り出すよう設計されうる

Claude Code 固有の注意点

日本語の解説であまり触れられていない、Claude Code 特有の穴が3つあります。

1. allowed-tools にワークスペーストラストのゲートがかからない。一度も信頼していないフォルダで -p 実行した場合でも、プロジェクト skill の allowed-tools は適用されます。→ リポジトリにコミットされた skill の allowed-tools は、そのリポジトリで Claude Code を動かす前にレビューする必要があります
2. 動的コンテキスト注入は許可プロンプトを出しません。ask ルールでは中断されますが、allowed-tools で事前承認していれば黙って実行されます
3. バックグラウンドの context: fork による編集は /rewind で戻せません。git を安全網にしてください

法人導入チェックリスト

ZDR 対象外である点は、機密性の高い業務で Claude Code を導入する組織にとって見落とせない条件です。セキュリティ設計全般は Claude Code セキュリティ対策ガイド を合わせて確認してください。

バージョン要件早見表

Skills の機能はバージョン依存が大きいため、claude --version で確認してから設計するのが確実です。

（2026年8月21日時点の最新版は v2.1.237 系）

Skill を「育てる」運用と評価

Skill は書いて終わりではなく、実タスクで使いながら磨くものです。公式が提供する評価ツールを使うと、感覚ではなく数値で改善できます。

skill-creator プラグインで評価する

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

Marketplace "claude-plugins-official" not found が出た場合は /plugin marketplace add anthropics/claude-plugins-official を先に実行します。インストール後は「skill-creator で summarize-changes スキルを評価して」のように依頼します。

skill-creator が生成・実行するものは以下です。

• テストケース: スキルディレクトリ内 evals/evals.json にプロンプト・入力ファイル・期待挙動を保存
• 隔離実行: テストケースごとにサブエージェントを起動し、トークン数と所要時間を記録
• 採点: 各アサーションを検証し grading.json に pass / fail と根拠を記録
• ベンチマーク: スキルあり／なしの合格率・時間・トークンを benchmark.json に集約
• バージョン比較: 2バージョンのブラインド A/B
• description チューニング: 発動すべき／すべきでないプロンプトを生成してヒット率を測り、修正案を提示

評価の基本はベースライン比較

同じプロンプトを「スキルあり」と「skillOverrides で off にした状態」で実行して比べます。このとき必ず新規セッションで行うのがポイントです。作成中の会話コンテキストが残っていると、指示の穴が見えません。

Claude 自身に手順を書き起こさせる方法もあります。実作業の記録から Skill を起こす機能については Claude Code のスキル記録機能 や Skill Recorder とは で解説しています。

こんな方におすすめ／おすすめしない方

おすすめする方

おすすめしない方

よくある質問

Q1. SKILL.md はどのくらいの長さに収めるべきですか？

公式推奨は500行以内です。それ以上の情報は references/ などの参照ファイルに分割し、SKILL.md 本体には参照だけを書きます。本文が長いほど、呼び出し時にコンテキストを圧迫します。

Q2. .claude/commands/ の旧スラッシュコマンドはまだ使えますか？

使えます。公式ドキュメントに「カスタムコマンドは Skills にマージされた」と明記されており、.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy を作ります。ただし .claude/commands/ 側ではフロントマターの name と paths が無視され、補助ファイルの同梱や Claude による自動ロードもできません。

Q3. Personal と Project、どちらが優先されますか？

Personal（~/.claude/skills/）が Project（.claude/skills/）より優先されます。プロジェクト固有の方が強いと誤解しやすい部分です。全体の順は Enterprise > Personal > Project です。

Q4. Claude Code で作った SKILL.md を claude.ai にアップロードできますか？

そのままではできない場合があります。claude.ai・Skills API へのアップロードで許可されるのは name・description・license・compatibility・metadata・allowed-tools の6フィールドのみで、argument-hint などの Claude Code 拡張が含まれるとハードエラーになります。アップロード用には拡張を削ったバージョンを用意してください。

Q5. プリビルトの PowerPoint / Excel スキルは Claude Code で使えますか？

使えません。pptx / xlsx / docx / pdf のプリビルト Skills は Claude API・claude.ai・Claude Platform on AWS・Microsoft Foundry でのみ利用できます。Claude Code で同等のことをしたい場合は自作するか、対応するプラグインを導入します。

Q6. Skill を大量に作ると何か問題がありますか？

はい。スキル一覧（name + description）は常時コンテキストを占め、既定の予算はモデルのコンテキストウィンドウの1%です。数が増えると description が切り詰められ、発動精度が落ちます。skillOverrides で常用しないものを name-only や off にするか、skillListingBudgetFraction で予算を広げてください。

Q7. Skills を使うと請求額は増えますか？

Skills 機能自体に追加課金はありません。増えるのは消費トークン分です。Claude API 経由で使う場合のみ、code execution tool の実行時間とコンテナストレージが標準課金されます。

Q8. Agent Plugins 1.0.0 に対応すれば Claude Code でも動きますか？

SKILL.md 自体は共通ですが、プラグインのマニフェストとレイアウトは互換ではありません。Claude Code は .claude-plugin/plugin.json を使う独自形式で、Agent Plugins 1.0.0 は plugin.json ＋ skills/ ＋ mcp.json という構成です。両方に配りたい場合は、SKILL.md を共通資産として持ち、束ね方を配布先ごとに用意するのが現実的です。

Q9. npx skills は Anthropic 公式のツールですか？

いいえ。npx skills は Vercel Labs が開発したオープンソース CLI で、Anthropic 公式ツールではありません。レジストリは GitHub で、owner/repo がそのままリポジトリにマップされます。取得元の信頼性は利用者側で判断する必要があります。

Q10. Agent Skills は Zero Data Retention（ZDR）の対象ですか？

対象外です。公式ドキュメントは「Agent Skills は ZDR の取り決めの対象ではない。スキル定義と実行データは Anthropic の標準的なデータ保持ポリシーに従って保持される」と明記しています。ZDR 契約下で運用している組織は、社内規程との整合を事前に確認してください。

まとめ

Claude Code Skills は、.claude/skills/<スキル名>/SKILL.md を置くだけで動く、シンプルかつ強力な仕組みです。CLAUDE.md が「常に効くルール」なら、Skills は「必要なときだけ呼ばれる手順書」と位置づけると設計に迷いません。

実務で押さえるべき要点は次の5つです。

1. description に「呼ばれるべき状況」を具体的に書く — 発動率はここでほぼ決まる
2. SKILL.md 本体は500行以内に保ち、詳細は参照ファイルへ逃がす
3. Skill を増やしすぎない — 一覧はコンテキストウィンドウの1%が既定予算。常用しないものは skillOverrides で隠す
4. スキル本文はセッション中残り続け、再読み込みされない — 「途中から効かない」の正体はここにある
5. 配布経路でフロントマターの制約が変わる — claude.ai / Skills API は標準6フィールドのみ

そして2026年8月時点の最新事情として、カスタムスラッシュコマンドは Skills に統合済みであること、SKILL.md は多くのエージェント製品が対応する共通フォーマットになったこと、束ね方は Claude Code 独自形式と Agent Plugins 1.0.0 の2系統に分岐していることを踏まえた設計が必要です。

最初の一歩は、CLAUDE.md の中で「手順」に育ってしまった節をひとつ切り出して Skill にすることです。1個動けば、あとは同じ要領で増やせます。

関連記事

• Claude Codeとは？特徴・料金・使い方を完全解説 — Claude Code の全体像
• Agent Plugins 1.0.0とは？MCPとAgent Skillsを束ねる新標準 — Skills を束ねる業界標準の最新動向
• Claude Code の Skills と Hooks の違い — 「判断に任せる」と「必ず実行する」の切り分け
• Claude Code Hooks 活用ガイド — ライフサイクルを決定論的に制御する
• Claude Code サブエージェント活用ガイド — context: fork のベースになる仕組み
• Claude Code スラッシュコマンド完全ガイド — Skills に統合されたコマンド体系
• Claude Code × MCP 連携ガイド — 外部ツール接続との使い分け
• Claude Code セキュリティ対策ガイド — 権限設計と監査
• Claude Code コスト最適化ガイド — コンテキスト予算とトークン削減
• Claude Code チーム導入ガイド — 組織展開の設計
• Claude Code の料金プラン解説 — プラン別の違い