こんにちは、Lenaです。2025 年の終わりごろ、静かに何かが変わりました。すぐには気づかなかったんです。たいていの本当の変化がそうであるように、少しずつやってきました。
Claude Code が、プロジェクトをまたぐ繰り返し作業をどう扱うのかを私は見ていました。見えていたパターンはおなじみのものでした。同じ指示を、毎回少しずつ言い換える。同じ文脈を、何度も説明し直す。足りなかったのは、モデルそのものではなく、モデルと実作業のあいだのレイヤー だった気がします。
そのレイヤーには、いま名前があります。Claude Code Skills です。
Claude Code Skills とは何か
いちばん単純に言えば、Claude Code スキル はフォルダです。その中に SKILL.md というファイルがあります。Claude Code はそのフォルダを見つけると、ファイルを読み、指示をコンテキストへ読み込み、それに応じて振る舞いを調整します。
私は何度もこの説明に立ち戻ります。あまりにも単純に聞こえるからです。けれど、少し腰を据えて考えてみると、その含意は最初の印象より大きい。
スキルは、会話の冒頭で毎回貼り付けるプロンプトではありません。Claude が自動で見つけて適用する、再利用可能な振る舞いのパッケージ です。一度インストールしておけば、Claude は関連する場面でその文脈を自分で拾います。毎回言い直す必要はありません。
SKILL.md フォーマットの仕組み
どのスキルも、同じ 2 部構成から始まります。SKILL.md は、frontmatter と content から成る Markdown ファイルです。frontmatter はスキルの 動き方 を設定します。permissions、model、metadata です。Markdown の content は、Claude に 何をするか を伝えます。
最小構成の例はこんな感じです。
---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name
[Instructions Claude will follow when this skill is active]
name フィールドはスラッシュコマンドになります。description フィールドは、Claude がそのスキルを読み込むべきかどうかを判断するときに参照するものです。スキル選択では description が決定的です。Claude は、場合によっては 100 を超える利用可能なスキルの中から、これを手がかりに正しいものを選びます。description には、いつ このスキルを選ぶべきかが分かるだけの具体性が必要で、SKILL.md の残りが実装の詳細を担います。
この最後の点は、軽く見積もりやすいところです。私も最初の数回は間違えました。技術的には正しいけれど、振る舞いとしては曖昧な description を書いてしまったんです。すると、スキルが違うタイミングで読み込まれたり、そもそも読み込まれなかったりする。description は単なるメタデータではありません。ルーティングの判断そのものです。
仕様の全体像は、official Claude Code Skills documentation を読むのがいちばん確実です。
どんな振る舞いをエンコードできるか
ここからが面白くなります。スキルは、単なるテキスト指示にとどまりません。各スキルはディレクトリとして構成され、メインの SKILL.md、Claude が埋めるテンプレート、期待する出力形式を示すサンプル、Claude が実行できるスクリプトなどを含められます。
実際には、次のようなものをエンコードできます。
- コーディング規約 — 関数名の付け方、テスト構成、エラーハンドリング
- ワークフローパターン — レポート生成やファイル処理で Claude がたどるべき多段の手順
- 実行可能スクリプト — 検証ロジック、ファイル変換、外部 API 呼び出しのような決定的処理
- 参照ドキュメント — 毎回のセッションを太らせず、必要なときだけ Claude が読む詳細仕様
重要な設計上の気づきはここです。スキルがトリガーされると、Claude は bash を使ってファイルシステムから SKILL.md を読み込み、その指示をコンテキストウィンドウへ持ち込みます。もしその指示が別ファイルを参照していれば、Claude はそれも読みます。実行可能スクリプトに触れていれば、それを実行し、受け取るのは出力だけです。スクリプト本体のコードはコンテキストに入りません。
これは細かいけれど大事な点です。スキルは lazy-loaded です。50 ページの参照資料を 1 つのスキルに束ねても、Claude が取り込むのは本当に必要な部分だけです。
最初の Claude Code スキルを作る
正直に言うと、最初のスキルは出来がよくありませんでした。壊れていたわけではありません。ただ、曖昧だった。広く発火しすぎたし、会話の指示と競合したし、結局、自分で打ち込んだほうが早かったくらいです。
いまなら、こうやります。
ファイル配置と形式
Claude Code では、スキルはプロジェクトディレクトリ内の .claude/skills/、またはグローバルに効く個人用スキルなら ~/.claude/skills/ に置きます。Claude Code がサポートするのは Custom Skills のみで、SKILL.md を含むディレクトリとして作成します。
フォルダ名が、そのスキルの識別子になります。小文字で、単語はハイフンでつなぎます。中身はこんな構成です。
my-skill/
├── SKILL.md ← required
├── examples/ ← optional but helpful
│ └── sample.md
└── scripts/ ← optional
└── validate.sh
SKILL.md の frontmatter で必須なのは name と description の 2 つです。name は小文字、数字、ハイフンだけで書きます。description は必ず三人称で書くべきです。description は system prompt に注入されるため、視点がぶれると discovery に問題が出やすくなります。
スキルが適用されているかを検証する
ここは最初かなり戸惑いました。UI 上に「スキルを読み込みました」という明示的な通知はありません。私がいま有効だと感じている方法は、Claude に直接聞くことです。「どんなスキルにアクセスできますか」と尋ねると、たいてい一覧が出ます。あとは、そのスキルが発火すべきタスクを投げて、振る舞いが変わるかを見る。
より確かな検証は、振る舞いベースです。同じタスクを、スキルあり / なしで実行して比べる。もし出力パターンが、自分がエンコードした方向へ変わるなら、スキルは機能しています。トリガーの仕組みを理解すると、よりよいスキル設計ができます。スキルは名前と description 付きで Claude の利用可能スキル一覧に現れ、Claude はその description を見て参照するかを判断します。Claude がスキルを参照するのは、自力で簡単には処理できないタスクが来たときだけです。単純で 1 ステップの問いは、description が一致していても発火しないことがあります。
スキル設計でよくある失敗
Anthropic skill authoring best practices guide がここをよく整理していますが、私がいちばんよく見た失敗は次のとおりです。
- description が曖昧 — Claude は、正確に理解できないスキルへはルーティングできません
- SKILL.md に詰め込みすぎる — 1 ファイルに全部を押し込まず、詳細は参照ファイルへ分ける
- 例がない — 具体例のないスキルは、出力がぶれやすい
- 指示が古い — すぐ古くなる情報は入れない。バージョン依存の内容は折りたたみセクションや明確な日付で囲う
プロジェクトやチームをまたいでスキルを共有する
ここから、スキルは本当に便利になります。同時に、いまの限界も見え始めます。
SKILL.md 共有の現状と限界
スキルはファイルベースです。つまり、共有にはファイル配布が必要になります。zip で渡す、Git リポジトリで配る、手動でコピーする。現在の配布モデルでは、各ユーザーがスキルフォルダをダウンロードし、Claude Code の skills ディレクトリへ置かなければなりません。組織向けスキルは管理者がワークスペース全体へ展開できるようになっており、これは 2025 年 12 月に出荷されました。自動更新と一元管理もあります。
これは確かに大きな改善です。けれど、それでもスキルは静的な成果物として存在します。そこにエンコードされたワークフローが変わっても、スキルは自動更新しません。誰かが保守し続ける必要があります。
2025 年 12 月、Anthropic は Agent Skills specification をオープンスタンダードとして公開し、OpenAI も Codex CLI で同じ形式を採用しました。スキルは model-invoked です。AI が文脈を見て、いつ使うかを自動判断します。この相互運用性は、本当に意味があります。Claude Code 向けに作ったスキルが、原理上は Cursor やそのほかの互換環境でも動くわけです。コミュニティの実例は、Anthropic skills GitHub repository で見られます。
クロスエージェント共有レイヤーに必要なもの
ここが、私がまだ考え続けている部分です。
いまのスキルは、人が書き、人がレビューし、手作業で配布します。エージェントはそれを実行しますが、改善はしません。結果から学ばないし、成功したバリエーションを伝播もしないし、指示が現実の成功パターンからズレたときに知らせてもくれません。
本当にクロスエージェントな共有レイヤーを作るなら、もっと別のものが必要になります。実行の検証、品質スコア、バージョンの系譜です。静的な SKILL.md は 意図 をうまく残せます。でも、結果 は残せません。
この問題をきれいに解いた例を、私はまだ見たことがありません。
限界: Claude Code Skills だけでは届かないところ
静的なファイルと適応的な学習
スキルは指示です。自分のパフォーマンスを観察しません。6 か月前には有効だったデバッグパターンが、モデル更新や API 変更のせいでいまは信頼性を失っていても、スキルはそれに気づきません。気づくのは、最終的にはあなたです。
スキルは生きた文書です。時間とともにどう機能するかを見ながら、反復していく前提で扱うべきです。これは良い助言です。ただ、その反復の負担を、完全に作者へ載せてしまう。エージェント自身は、従っている指示を改善する側に回れません。
実行の検証がなく、修復ループもない
スキルが実行されて、出力が間違っていても、スキル機構自体はそれを捕まえません。Claude は SKILL.md に書かれたことを実行するだけです。結果が意図とずれていても、ループは自動では閉じません。
これは、安定した規約をエンコードするスキル、たとえばコードスタイルや文書構造ではそれほど問題になりません。けれど、正しさがタスク依存になる動的なワークフローをエンコードするスキルでは、話が変わってきます。
再利用ネットワークがない
いまのスキルは、ローカルにあるものか、GitHub 上で公開されているものかのどちらかです。ある種の問題に対する成功した解法が、テストされ、検証され、バージョン追跡され、類似の問題に取り組む別のエージェントから見つけられ、継承される。そうした常在的なレイヤーはまだありません。
SkillsMP community marketplace は、その方向への初期的な動きです。ほかの人が何を作ったかを見つけるには便利です。ただし、そこに並ぶスキルも依然として静的ファイルです。監査記録は持たず、何回使われたのかも、どんな結果だったのかも、自分では知りません。
Skills の次に来るもの
静的な指示から、検証済みで継承・流通できる能力へ
私はこの問いを、ずっと頭の片隅に置いています。
Claude Code skills は現実の問題を解いています。エージェントの振る舞いを繰り返し可能にし、移植可能にしてくれる。それは小さなことではありません。スキル以前は、文脈をセッションごとに組み直す必要がありました。いまは違います。
けれど、スキルは依然として人間の成果物です。そこに記録されるのは、誰かが 効くはずだと思ったこと です。どんな条件で、どの程度成功し、どんな失敗モードがあったのかという、実際に効いたこと の証拠は持ちません。
次のレイヤーがどんなものになるにせよ、おそらくそれはファイルフォーマットというより、出自を持つ能力に近いはずです。つまり、「この手法はこういう条件で試され、この成功率で動き、このエッジケースで失敗し、この作者たちが改訂し、似た状況でこれらのエージェントに適用された」と語れるものです。
それは、Markdown ファイルとは別の種類のインフラです。
このギャップを、私はまだうまく言葉にできません。ただ、偶然ではない気がします。次に見ておくべきものが、ここにある。
FAQ
- Claude Code における SKILL.md ファイルとは何ですか。
SKILL.md には主要な指示が入り、すべての Claude Code スキルで必須です。構造は 2 つで、Claude に「いつ使うか」を伝える YAML frontmatter と、呼び出されたときに Claude が従う Markdown の指示本文から成ります。オンボーディング文書だと考えると近いです。ただし、エージェントはそれを忘れません。
- Claude Code スキルはどう書けばいいですか。
まず frontmatter から始めます。name は小文字でハイフンのみ、description は三人称で、いつ呼び出すべきかを具体的に書きます。そのあと Markdown 本文に、明確で命令形の指示を書きます。補助ファイル、つまり例、スクリプト、参照資料は、本当に振る舞いを改善する場合にだけ追加します。検証は、同じタスクをスキルあり / なしで比較するのが基本です。詳細は Anthropic's skill authoring best practices が参考になります。
- Claude Code skills はチームメンバー間で共有できますか。
組織管理者は、ワークスペース全体へスキルを配布できます。自動更新と一元管理にも対応しており、これは 2025 年 12 月に出荷されました。オープンソースとして共有するなら、現状の配布チャネルは GitHub です。Agent Skills オープンスタンダードにより、Claude Code 向けに作ったスキルは他の互換ツールでも動かせます。相互運用性はすでに現実です。ただし、実行履歴まで持つ一元的な再利用ネットワークは、まだこれからの課題です。
これがどう進化していくのか、これからも見ていこうと思います。ここでは何かが起きています。ただ、その終着点がどこなのかは、まだ私にも見えていません。
