今日はこれを深掘りするつもりはありませんでした。同僚の Claude Code の設定が、なぜ自分のものとあんなに違って見えるのかを知りたかっただけです。答えは、ほとんど気にも留めていなかったフォルダの中にありました。
Claude Code Skills Documentation が扱うもの
"anthropic claude code skills documentation" という語句が、開発者の検索にかなり出てくるのには理由があるのだと思います。skills の仕組みは実際、いくつかの場所に分散していて、それぞれがどうつながるのかを自分の中で組み立てるまでに少し時間がかかります。
この記事は Anthropic の公式ソースを土台にしています。ただ、公式ドキュメントだけでは拾いきれないものもあります。観察から少しずつ積み上がってくる、もう少しゆっくりした理解の層です。
公式ドキュメントはどこにあるか
正面から入るなら、Anthropic's Claude Code skills reference がいちばん確かな起点です。skills のライフサイクル全体、SKILL.md の形式、そして Claude が skills をどう見つけて自動ロードするかまで、ひと通りまとまっています。
skills をもっと大きな agent の文脈に置いて理解したいなら——Projects、MCP、subagents と比べたときにどこに位置づくのかまで含めて——Anthropic が出しているこちらのブログも役に立ちました：Skills explained: How Skills compares to prompts, Projects, MCP, and subagents。あの記事が整理してくれたのは、単なる what だけではなく、when でもありました。
この記事が公式ドキュメントに足すもの
公式ドキュメントは正確ですし、構成もよくできています。ただ、そこだけでは見えにくいものがあります。ある skill が発火しない瞬間、逆に広く発火しすぎる瞬間、あるいは SKILL.md と CLAUDE.md を同じ役割のものだと思っていたのに、実は少し違う仕事をしていたと気づく瞬間。そういう小さなずれです。
ここで追いかけたいのは、そのあたりです。
SKILL.md フォーマットリファレンス
ファイルの置き場所と命名
どの skill にも SKILL.md ファイルが必要です。内容は 2 つに分かれます。1 つは --- に挟まれた YAML frontmatter で、Claude にその skill をいつ使うかを伝える部分。もう 1 つは Markdown 本文で、skill が呼ばれたときに Claude が従う指示です。
Claude Code では、skills は Project 内の .claude/skills/<skill-name>/SKILL.md に置くことも、ユーザー全体の ~/.claude/skills/<skill-name>/SKILL.md に置くこともできます。フォルダ名と frontmatter の name フィールドがスラッシュコマンドになるので、たとえば .claude/skills/explain-code/SKILL.md に name: explain-code と書けば、/explain-code コマンドが作られます。
また、.claude/skills/ に置かれ、--add-dir で追加したディレクトリ配下にある skills は自動的に読み込まれ、ライブ変更検知にも反映されます。つまり、セッションを再起動せずに途中で編集できる。ここは少し意外でした。私は再起動が必要だと思っていたので。
対応している指示の種類
Skills は、指示とコードを通じて Claude に新しい能力を与えます。実際には、Markdown 本文には Claude が推論できるものならかなり自由に入れられます。手順、スタイル規則、出力テンプレート、ドメイン用語、参照情報、インラインの例。指示を書くなら、命令形を基本にしたほうが扱いやすいです。
公式の skill-creator ドキュメントで一つ印象に残ったのは、description フィールドこそが主要なトリガーだという点です。この skill が何をするのかと、どんな場面で使うべきか。その両方をここに書く。いわゆる「いつ使うか」の情報は本文ではなく、ここに置くべきです。
構文と構造
最小構成の SKILL.md は、こんな形です。
---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name
[Instructions Claude follows when this skill is active]
起動時に agent は、インストール済みの各 skill の name と description を system prompt へ先に読み込みます。このメタデータは progressive disclosure の最初の層です。Claude がどの skill をいつ使うべきかを判断するのに十分な情報だけを先に渡し、全文をいきなりコンテキストへ詰め込まないためです。
Skills には補助ファイルも持たせられます。参照ドキュメント、スクリプト、アセットをサブディレクトリへ置けます。フォーム入力のような詳細な手順を別ファイルに逃がせば、skill の中心部分は細く保てますし、Claude も必要なときだけそのファイルを読めばよくなります。
文字数と長さの上限
SKILL.md 自体に厳密な文字数上限はありません。skill に抱えられるコンテキスト量は、理屈の上ではほぼ無制限です。progressive disclosure があるので、Claude は必要な追加ファイルだけを読めばいいからです。ただ実務では、SKILL.md は中核の指示に絞って 500 行以下に保つほうが、コンテキストの膨張を避けやすい。詳しい内容は references/ に移して、そこへリンクするのがよさそうです。
Claude Code Skills が指示できること
スタイルと書式の好み
Skills は、出力標準を埋め込むのに向いています。レポートをどう構成するか、どんなトーンにするか、どの見出しを入れるか。会社のカラーパレット、タイポグラフィ、レイアウト規則を含んだブランドガイドライン skill を作ることもできます。そうしておけば、Claude がプレゼン資料や文書を作るときに、その標準を毎回説明しなくても自然に適用してくれます。
ドメイン固有の知識
日々の仕事では、ここがいちばん効く場面かもしれません。Claude が一般的な学習だけでは知りようのないこと、それでも実務上は知っていてほしいこと——社内 API の慣習、独自データ形式、会社固有のワークフロー——そうしたものは skill にまとめておけば、毎回プロンプトで繰り返さずに済みます。
ツール利用の好み
Skills では、どのツールを優先するか、どんな順番で使うか、どんな条件で使うかまで指定できます。Claude が skill を呼ぶとき、システムがやっていることは案外シンプルです。SKILL.md を読み込み、そこから詳細指示を展開し、それを新しい user messages として会話コンテキストへ注入し、実行コンテキスト（使えるツールやモデル選択）を調整し、その拡張された状態で会話を続けます。
出力構造の要件
skill の中で、かなり厳密な出力テンプレートを定義することもできます。Anthropic skills GitHub repository には、Claude を具体的な形式へきちんと寄せる例がいくつもあります。レポート構成、commit message のパターン、テストファイルのレイアウトなどです。
Skills にできないこと
コードを実行すること
SKILL.md は指示の内容であって、実行可能コードではありません。Claude にタスクへどう向き合うかを伝えるものであり、それ自体が何かを実行するわけではありません。skill の /scripts ディレクトリにあるスクリプトは、タスク実行中に Claude から呼ばれることがありますが、SKILL.md そのものはただのテキストです。
エラーから学ぶこと
Custom Skills は surface をまたいで同期されません。ある surface にアップロードした skill が、別の surface で自動的に使えるようになることはありません。もっと言えば、ある session で何が起きたかを受けて、skill 自身が更新されることもありません。編集しない限り、指示は静的なままです。私はこの点を忘れないようにしています。skill は知見のスナップショットであって、学習ループではありません。
agents や sessions をまたいで自動共有すること
Skills のスコープは、どの surface にインストールされているかで決まります。Claude Code で作った skill が、Claude.ai や API で自動的に使えるようになるわけではありません。使いたければ、別途アップロードが必要です。
Skills、System Prompts、Project Rules、Memory の違い
ここは、私がいちばん長く迷ったところです。今のところ、違いはこう捉えています。
| 仕組み | 役割 | スコープ | セッションをまたいで残るか |
|---|---|---|---|
| SKILL.md | 必要に応じて読み込まれるドメイン固有の指示 | Project または user-global | はい（ファイルベース） |
| CLAUDE.md | 常に読み込まれる Project の文脈と規約 | Project レベル | はい（ファイルベース） |
| System prompt | モデルの基本動作を定める | API/SDK レベル | 毎回設定した場合のみ |
| Projects (claude.ai) | 進行中の仕事のための持続的な文脈を持つ | Claude.ai workspace | はい |
| Memory | 会話をまたいで好みを思い出す | ユーザーレベル | はい（有効時） |
Skills は、Claude に how を教えるものです。たとえば Project があなたの製品ローンチに関する背景を丸ごと抱える一方で、skill はチームの文章スタイルやコードレビュー手順を教えられます。
CLAUDE.md は、Claude が会話の冒頭で毎回読む特別なファイルです。Bash commands、コードスタイル、workflow ルールをここへ入れておけます。コードだけからは推測できない持続的な文脈を与えるわけです。SKILL.md との核心的な違いはここです。CLAUDE.md は always 読み込まれ、skills は when relevant のときだけ読み込まれます。
Claude Code の system prompt には、もともとおよそ 50 個の個別指示が入っています。モデルにもよりますが、それだけで agent が安定して従える指示の総量の 3 分の 1近くを使っている計算です——rules、plugins、skills、user messages を足す前の段階で。私はこの数字がずっと頭に残っています。どの層にどれだけ載せるかの考え方が変わるからです。
FAQ
1 公式の Claude Code Skills documentation はどこにありますか？
主な参照先は Claude Code skills documentation です。より広い Agent Skills 標準——pre-built skills と custom skills が Claude.ai や API でどう機能するかまで含めて——を見るなら、Anthropic platform docs の Agent Skills overview が参考になります。
2 SKILL.md はどんな形式ですか？
SKILL.md は YAML frontmatter を持つ Markdown ファイルです。frontmatter には name と description の 2 つが必須で、Claude は session の開始時にそれを読んで、この skill をいつ読み込むべきかを判断します。Markdown 本文には、skill が呼ばれたときに Claude が実際に従う指示が入ります。高度な実行制御をしたい場合は、context や agent のような任意フィールドも使えます。
3 SKILL.md ファイルはどれくらい長くできますか？
強制される厳密な上限はありません。Agent Skills を柔軟で拡張可能なものにしている設計原則は progressive disclosure で、skills は Claude に必要な情報だけを必要なときに読ませます。だから skill に持たせられるコンテキスト量は、理論上かなり大きい。それでも実用的な指針としては、中核の SKILL.md は 500 行以下に抑え、詳しい内容は references/ へ逃がすほうがよいと言われます。
ここにある境界条件を、私はまだ全部描き切れたとは思っていません。skill の発火挙動——Claude がいつ「これは relevant だ」と判断し、いつそうしないのか——は、フォーマットの説明だけから想像するよりずっと読みづらい。Claude は skills をやや undertrigger する傾向があります。使えたはずの場面で使わない。その点は description フィールドを書くときに覚えておいたほうがよさそうです。
このあたりがどう落ち着いていくのか、もう少し見ていこうと思います。
