TL;DR
- Skillsとは「Claudeへの手順書」であり、ドメイン知識の提供が本来の主目的。現在はワークフロー自動化やサブエージェント的な使い方まで拡張されている
- descriptionの設計が最重要。Claudeはアンダートリガーしやすいので「pushy」に書き、ネガティブトリガーで判断精度を上げる
- Skillsは事前に全部用意するものではなく、開発中に発見した繰り返しパターンを抽出して段階的に構築する
- skill-creator 2.0のdescription改善にはAPI従量課金が別途発生する（MAXプラン等の定額サブスクとは別）
- 実運用後の評価にはトランスクリプト分析が有効。特にSkillsが意図したように活性化したか、という定量的評価には利用できる。公式の継続的評価の仕組みは未提供。
背景
Anthropicが公開した「The Complete Guide to Building Skills for Claude」は、Skills構築の包括的なガイドである。
これを読み解き、実際にClaude CodeでSkillsを運用する視点で何が重要なのかを整理する。
自身の経験を踏まえ、公式PDFガイドに加えてAgent Skills Best Practices、Claude Code公式ドキュメントと照合しながら理解を深めまた。
本記事は、これらの資料の要約に加え、個人的な理解と実用方針を整理した記録となる。
本記事の内容は2026年3月15日時点の情報に基づいています。
前提条件
- Claude Codeの基本的な使用経験がある
- Skillsの存在を知っている（作成経験はなくてもOK）
- MCP（Model Context Protocol）の概念を大まかに理解している
Skillsとは何か
Skillsとは、Claudeに特定のタスクやワークフローの処理方法を教える指示セットである。シンプルなフォルダとしてパッケージ化される。
Instead of re-explaining your preferences, processes, and domain expertise in every conversation, skills let you teach Claude once and benefit every time.
（毎回の会話で好みやプロセス、ドメインの専門知識を説明し直す代わりに、Skillsを使えば一度教えれば毎回活かせる）
Skillsの登場時の主目的はドメイン知識・専門知識の提供だった。そこからワークフロー自動化、判断基準の提供、context: forkによるサブエージェント的な使い方へと用途が拡張されてきた。この流れを理解しておくと全体像が掴みやすくなる。
2つのルート：スタンドアロン Or MCP強化
ガイドは「何をしたいか」によって2つのルートを提示している。
スタンドアロンSkills
Claude単体の能力で完結するSkillsを作りたい場合に該当する。
- ドキュメント&アセット作成 - 一貫した高品質な成果物の生成（例：frontend-design, docx, pptx）
- ワークフロー自動化 - 手順化されたプロセスの自動化（例：skill-creator）
MCP強化Skills
MCPサーバーと連携するClaudeの使い方を強化したい場合に該当する。自前で構築したMCPサーバーだけでなく、コミュニティ提供のMCPサーバー（Notion、GitHub等）を使っている場合も含まれる。
MCPのツールアクセスにワークフローの知恵を加える。
資料のキッチンの例えがわかりやすい。
- MCP = プロの厨房（ツール・食材・設備へのアクセス）
- Skills = レシピ（それらをどう組み合わせて価値を生むかの手順）
| スタンドアロン | MCP強化 | |
|---|---|---|
| Skillsが提供するもの | 手法の全て（手順 + 実行手段） | 手法のみ（手順・ベストプラクティス・判断基準） |
| 実行手段 | Claudeの組み込み能力 | MCPが提供 |
| 原文の整理 | - | MCP = "What Claude can do" / Skills = "How Claude should do it" |
Skillsの構造と段階的な読込
必須なのはSKILL.mdだけ
Skillsの技術的な構造として、必須なのはSKILL.mdのみ。
your-skill-name/
├── SKILL.md # 必須 - メインSkillファイル
├── scripts/ # 任意 - 実行可能コード
├── references/ # 任意 - 参照ドキュメント
└── assets/ # 任意 - テンプレート、フォントなど
PDFガイドではscripts/、references/、assets/というディレクトリ名が紹介されているが、これらは推奨的な整理例であって技術的な制約ではない。
Claude Code公式ドキュメントでは固定のディレクトリ名を規定しておらず、SKILL.mdから正しくリンクされていれば名前も構造も自由である。
それぞれの役割の違いは以下の通り。
| ディレクトリ | Claudeの使い方 | 具体例 |
|---|---|---|
| scripts/ | スクリプトを実行して出力を受け取る（コード自体はコンテキストに入らない） | validate.py, fetch_data.sh |
| references/ | 読み込んで理解・判断に使う | APIガイド, コーディング規約 |
| assets/ | 成果物に組み込む素材として使う | テンプレート, フォント, アイコン |
Skillsの段階的な読込
ClaudeCodeは、Skillsを以下3段階で読み込む。
| レベル | 内容 | 読み込みタイミング |
|---|---|---|
| 1 | YAMLフロントマター（name + description） | 常にシステムプロンプトに読み込まれる |
| 2 | SKILL.md本体 | Skillsが関連するとClaudeが判断した時 |
| 3 | リンクされたファイル | Claudeが必要と判断した時のみ |
第3レベルのファイルは活用される可能性がSKILL.md本体より低くなる。
これは設計上意図されたものであり、重要な記述はなるべくリンク先ファイルに書くべきではない。
ベストプラクティスでは以下の注意点が示されている。
- Claudeが
head -100でプレビューだけして済ませる場合がある - 参照は1階層までに留める（参照ファイル → 更に別ファイルへの参照は避ける）
- 長い参照ファイルには目次をつける（部分的に読まれても全体像が把握できるように）
- 頻繁に参照されるならSKILL.md本体に昇格させる
SKILL.mdは500行以下が推奨である（ベストプラクティス）。コンテキストウィンドウは「公共の財産」であり、全てのSkillsのdescriptionが常にシステムプロンプトに入る。
descriptionの設計：最重要ポイント
YAMLフロントマターのdescriptionフィールドは、Skillsが発火するかどうかを決定する最も重要な要素である。
構造
[何をするか] + [いつ使うか（トリガー条件）]
ClaudeはSkillsを見逃しやすい
skill-creatorの公式SKILL.mdに明記されている。
currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy".
「少しpushy(=積極的に、強引に、はっきりと)に書く」ことが推奨されている。
トリガー設計のポイント
- ユーザーが実際に言いそうな言葉を使う - Claudeはdescriptionを読んで判断している（キーワードマッチではない）
- 具体的なファイル拡張子を含める -
.xlsx、.pdfなど - 類義語・言い換えを列挙する - 1つの表現だけだとアンダートリガーの原因になる
- ネガティブトリガーを活用する -
Do NOT use for...で誤発火を防止する - 三人称で書く - descriptionはシステムプロンプトに挿入されるため
三人称の具体例（日本語）は以下の通り。
# 良い（客観的な記述）
description: Qiita記事の作成・編集を支援する。「記事を書きたい」「技術記事を作成」と言われた場合に使用する。
# 悪い（一人称）
description: 私がQiita記事の作成をサポートする。
# 悪い（二人称）
description: あなたがQiita記事を書くときに使えます。
日本語は主語省略が自然なので英語ほど問題になりにくいが、「お手伝いします」のような主語を暗示する表現は避けるべきである。
ネガティブトリガーの重要性
Skillsの発火はClaudeがdescriptionを読んで判断しているため、「何をしないか」を明示することで判断精度が上がる。
人間に対して懇切丁寧に説明した方が「いつ、何をするべきか」がわかりやすくなるのと同じ理屈である。
特に以下の場面で効果的だ。
- 似たSkillsが複数ある場合
- 汎用的な言葉がトリガーになりうる場合
- ドメインが隣接している場合
少ない文字数で判断精度を大きく上げられる効率の良い手法である。
ただし、descriptionは最大1024文字という制限があり、全Skillsのdescriptionが常にシステムプロンプトに入るため、簡潔さとのバランスが必要になる。
Skillsの活用パターン
ガードレールと考え方のプラットフォーム
ベストプラクティスの「自由度の設計」セクションでは、Skillsの活用を自由度のスペクトラムとして捉えている。
ガードレールとしてのSkills（低い自由度）
「両側に崖がある狭い橋」：前に進む安全な方法は1つだけです。具体的なガードレールと正確な指示を提供してください。
例：DBマイグレーションスクリプトの実行（変更禁止）、コンプライアンスチェック
考え方のプラットフォームとしてのSkills（高い自由度）
「危険のない開けた野原」：多くのパスが成功につながります。一般的な方向を示し、Claudeが最適なルートを見つけることを信頼してください。
例：API規約、コーディング規約、決定ツリー。user-invocable: falseでバックグラウンド知識として機能させることも可能。
5つの設計パターン
第5章のパターンを実用的に分類すると、3種類に整理できる。
| 分類 | 資料上のサンプルパターン | 概要 |
|---|---|---|
| ワークフロー自動実行 | 1: 順序付きワークフロー / 2: マルチMCP調整 / 3: 反復的な改善 | 手順の自動実行、複数サービスの連携、品質チェックループ |
| AI判断基準の知識提供 | 4: コンテキスト対応のツール選択 | コンテキストに応じた意思決定のガイド |
| ドメイン知識の提供 | 5: ドメイン固有のインテリジェンス | 専門知識による成果物の質のコントロール |
パターン3（反復的な改善）は単独で使うものではなく、他のパターンの最終プロセスとして組み合わせるのが実用的である。例えばパターン1のワークフロー最終工程でバリデーションスクリプトを実行する、ドキュメント生成後にスタイルガイド準拠チェックを行う、といった使い方になる。
Skills作成のタイミング
注: ガイドの冒頭に「コードを書く前にユースケースを特定してください」とあるが、ここで言う「コード」はSkills自体のコードであり、アプリケーションのプログラムコードのことではない。
現実的なアプローチ
上述の通り先にユースケースを特定するべき、とあるが現実的には特定することは難しい。
Anthropic自身がPro Tipとして認めている。
We've found that the most effective skill creators iterate on a single challenging task until Claude succeeds, then extract the winning approach into a skill.
先にタスクを実行して、うまくいったやり方をSkillsに抽出するのが最も効果的との事。
実用的な戦略として、汎用フレームワーク（cc-sdd、aidlc-workflow等）を先に導入し、開発中に発見したパターンをスキル化していく段階的アプローチが有効と考えられる。
スキル化のシグナルは以下のようなものがある。
- 繰り返し同じ情報・指示を提供している
- 同じ種類のミスが繰り返し発生する
- 何度も同じ手順を説明している
skill-creatorによる反復的な改善
Skillsは「生きたドキュメント」であり、一度作って終わりではない。
skill-creatorを使えば、実運用中に発見した問題を迅速にフィードバックループに乗せられる。
例えば「このチャットで特定されたissueとソリューションを使って、Skillsの処理を改善して」とskill-creatorに依頼するだけで、エッジケースへの対応を反映できる。
Skillsの評価と運用
skill-creator 2.0の評価機能
2026年3月のアップデートで、skill-creatorに4つのモードが追加された。
| モード | 目的 |
|---|---|
| Create | Skillsの新規作成 |
| Eval | テストプロンプトのpass/fail判定 |
| Improve | 評価結果に基づくSkills改善 |
| Benchmark | 全評価セットの実行とパフォーマンス記録 |
Eval/Improve/Benchmarkは既存Skillsの運用後の改善・評価にも使える。
ただし、これらはあくまでユーザーが能動的に実行するものであり、実運用中にSkillsの発火状況を自動的・継続的に追跡する仕組みではない。
コストに関する注意点
skill-creator 2.0のdescription最適化ループは、内部でanthropic.Anthropic() APIを直接呼び出す。
- トリガーテスト（
run_eval.py）：claude -pコマンド経由 → サブスクリプション内 - description改善（
improve_description.py）：Anthropic API直接呼出 → 別途APIキーと従量課金が必要
MAXプラン等の定額サブスクリプションとは別途料金が発生する。この点はPDFガイドには明記されていない。
実運用での評価課題
現時点で以下の課題が残っている。
- 評価シナリオの定義はユーザー任せ
- 評価期間の追跡・リマインド機能はない
- 実運用中のトリガー状況、誤発火、ユーザー補正の減少等を追跡する仕組みは未提供
トランスクリプト分析が現時点ではこのギャップを埋める有効な手段と考えられる。
~/.claude/projects/配下のJSONLファイル（セッションのトランスクリプト）を分析することで、Skillsのトリガー状況を確認できる。
評価期間の自動検知（個人的なアイデア）
新規Skills作成後の評価期間を管理する仕組みとして、以下のアイデアを検討している。
- Skillsを作成した際、メモリファイルにSkillsの評価期間情報（作成日・期限・評価観点）を記録
- CLAUDE.mdに評価トラッカーへの参照を記載（毎セッション読み込まれる）
- 評価用Skills（
user-invocable: false）がバックグラウンドで評価状況を確認
セッション開始時と終了時で役割を分けるのが現実的なアプローチだと考えている。
- セッション開始時：CLAUDE.md経由で「対象Skillsが評価期間中であること」を検知・通知する
- セッション終了時：ユーザーの終了宣言（例：「今回の作業はここまで」）を検知し、当該セッションのトランスクリプトに対してSkills分析を半自動的に実行する
セッション終了時に分析することで、もしユーザが対象のSkillsをその作業工程で利用したつもりであったり、Skillsの結果が成果物に繋がっていると思っていても、実はそうではなかったと認識する。
分析結果を経て以下のアクションに繋げる。
- Skillsのdescription改善: トリガ精度を改善し、期待のタイミングで実行されるようにする
- Skills本体の改善: 求める成果物・手順遵守を得られるように改善する
- Skills削除の判断: Skillsが利用されなかったとしても期待の結果を得られているならば、もはや不要と考えてカットする。
Claudeのモデル自体が進化することで、以前は必要だったSkillsが不要になるケースもある。
定期的な棚卸しにもこの分析は有効と考えている。
この仕組みはskill-creator 2.0のBenchmarkとも連携できる。
評価期間中にトランスクリプト分析で発見した問題（誤発火、トリガー漏れ、想定外の使われ方など）を、Benchmarkのテストケースに追加していくことで、評価の精度を段階的に上げていける。トランスクリプト分析が「実運用の観測」、Benchmarkが「制御された実験」という役割分担で、両者を組み合わせることでSkillsの品質を継続的に改善できる。
Skillsとサブエージェントの関係
context: fork
context: forkは、Skillsをメインの会話と隔離されたサブエージェント内で実行するための設定である。
| 通常のSkills | context: fork | |
|---|---|---|
| 実行場所 | メインの会話内 | 隔離されたサブエージェント |
| 会話履歴 | アクセスできる | アクセスできない |
| SKILL.mdの役割 | 参照知識や手順ガイド | サブエージェントへのタスク指示そのもの |
MCPインテグレーション強化や純粋なワークフロー自動化のケースでは、メインエージェントのコンテキスト節約効果が大きいため有効である。
Skills/SubAgents の棲み分け
Skillsとサブエージェントの関係は双方向である。
- Skills → サブエージェント：
context: fork（Skillsがサブエージェントとして動く） - サブエージェント → Skills：
skillsフィールドでプリロード（サブエージェントがSkillsを参照する）
基本的な役割分担は以下の通り。
- Skills = 「何を知っているか」（知識・手順の提供）
- サブエージェント = 「何をするか」（独立した作業の委任）
context: forkの登場により両者の境界は曖昧になっているが、繰り返し参照される知識はSkills、独立完結するタスクはサブエージェントという使い分けが基本である。
サブエージェント内でのSkills発火
通常のセッションではSkillsのdescriptionがコンテキストに事前ロードされるが、サブエージェント内ではこの事前ロードが行われない。
そのため、サブエージェント内でSkillsを自発的にトリガーすることは困難である。
サブエージェントでSkillsを使いたい場合は、skillsフィールドで明示的にプリロードする必要がある。
Skillsの配置と管理
どこに配置するか
| 配置場所 | パス | 適用範囲 |
|---|---|---|
| Enterprise | managed settings経由 | 組織全体 |
| Personal | ~/.claude/skills/ |
全プロジェクト共通 |
| Project | .claude/skills/ |
そのプロジェクトのみ |
| Plugin | <plugin>/skills/ |
プラグイン有効時 |
同名Skillsがある場合の優先順位は Enterprise（最優先） > Personal > Project の順である。
一般的な設定ファイルの優先順位（より具体的なスコープが優先される）とは逆順である。Skillsではガバナンスの観点から、組織管理者の設定が最も強く、プロジェクト固有の設定が最も弱くなる。
※通常はProject固有のSkillsとPersonalのSkillsは異なる名前で共存するため、この優先順位が問題になることは少ないです。
実用的な使い分けは以下の通り。
- 汎用的なSkills → Personal（
~/.claude/skills/） - プロジェクト固有の知識 → Project（
.claude/skills/）でリポジトリにコミット
ポータビリティ
PDFガイドの「ポータビリティ」は、プラットフォーム間の互換性を意味する。同じSKILL.mdがclaude.ai、Claude Code、APIのどれでも動作する。Agent Skillsはオープンスタンダードとして公開されている。
ただし、claude.aiデスクトップアプリとClaude Code CLIは別のSkills管理体系を持っており、~/.claude/skills/のSkillsがclaude.aiに自動連携されるわけではない。この点についてはGitHub issue #20697で共有の提案がされている。
Skillsの重複管理
skill-creatorには既存Skillsとの重複確認機能がない。Skillsが増えると以下のリスクがある。
- 類似Skillsの重複でどちらが発火するか不安定になる
- 同じトリガーフレーズで意図しない方が選ばれる
- コンテキスト予算（コンテキストウィンドウの2%）超過で一部のSkillsが除外される
ベストプラクティスでは20〜50以上のSkillsの同時有効化は要評価とされている。
ユーザー領域レベルでClaude Code環境を育てていく観点では、Skills重複チェック用のSkills（既存の全Skillsのfrontmatterを走査して類似性を判定するもの）があると有用だと考えている。
第4章（配布と共有）について
第4章は主にSkillsを配布する側（MCPサーバー提供ベンダー、組織管理者、アプリケーション開発者）向けの内容である。個人でSkillsを作って使うユーザーにとっては、大部分を読み飛ばして問題ない。
ここでの「API」はベンダー側のAPIではなく、AnthropicのClaude API（/v1/skillsエンドポイント）を指しており、アプリケーションからSkillsをプログラム的に管理・実行するためのインターフェースである。