こんにちは、Lena です。去年の終わりごろ、Claude Code との付き合い方に、静かな変化がありました。気づこうと思っていたわけではありません。ただ、同じことを何度も説明するのをやめたかっただけです。セッションが新しくなるたびに、私は同じことをもう一度説明していました。エラー形式の規約。commit message の組み方。まず手に取る Python ライブラリ。Claude はそれを理解し、その場ではきちんと応えてくれる。でも次のセッションになると、またすべて忘れている。失敗というほどではありません。ただ、毎回、同じ出発点に戻っているだけでした。
そこで Claude Code Skills 機能 を見始めたとき、少しだけ景色が変わりました。
Claude Code Skills 機能とは何か
SKILL.md の正体
いちばん単純に言えば、スキルとは SKILL.md ファイルを含むディレクトリです。指示、スクリプト、リソースを整理して入れたフォルダで、エージェントはそれを見つけ、必要に応じて動的に読み込み、特定のタスクでよりうまく働けるようになります。
ファイルは 2 つの部分から成ります。上部の YAML frontmatter（--- のあいだ）と、その下の Markdown 指示 です。name フィールドはスラッシュコマンド名になり、description は Claude が自動読み込みすべきタイミングを判断する手がかりになります。
実際には、こんな形です。
---
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
なるほど、魔法ではないわけです。必要な瞬間に Claude が読む、構造化されたテキストファイルなんですね。
Skills は system prompts や project rules と何が違うのか
ここは最初、少し分かりづらいと感じました。
プロンプトのような、その場限りのタスクに対する会話レベルの指示とは違って、Skills はオンデマンドで読み込まれ、複数の会話にまたがって同じガイダンスを繰り返し与える必要をなくしてくれます。違いの核心は、いつ 読み込まれるかです。system prompt は常に存在します。スキルはファイルシステム上で静かに待機し、Claude が「今の作業に関係ある」と判断したときだけコンテキストへ引き込まれます。
この設計がおもしろいのは、コアの system prompt を書き換えずに、必要なときだけプロンプトを拡張できることです。スキルは、必要になった時点で Claude が読み込む実行可能な知識パッケージであり、メインプロンプトを軽いまま保ちながら能力を拡張します。
この違いは、私にはかなり意味があるように感じられました。ただ、Claude が「関係ある」と判断する瞬間がどこなのかは、まだ完全には見えていません。
Claude Code Skills の使い方
SKILL.md をどこに置くか
スキルは複数の場所から検出され、読み込まれます。Claude Code は、ユーザー設定、プロジェクト設定、プラグイン提供のスキル、組み込みスキルを走査して、利用可能なスキル一覧を組み立てます。
つまり、ユーザーレベルのスキルは ~/.claude/skills/skill-name/SKILL.md に置きます。プロジェクトレベルのスキルは、リポジトリ内の .claude/skills/skill-name/SKILL.md に置きます。各スキルには専用のサブディレクトリが必要です。--add-dir で追加したディレクトリ内の .claude/skills/ に定義したスキルも自動的に読み込まれ、ライブ変更検知にも対応しているので、セッションを再起動せずに編集中の変更を反映できます。
この最後の点、つまり セッション中に編集しても再起動がいらない というのは、私は予想していませんでした。作業の途中でスキルを調整し、その変化を見ることができる。ここは注目しておく価値があります。
Claude がどんな指示に従うのか
スキルファイルにはどんな指示でも書けます。ただ、どう呼び出したいかを考えると、何を含めるべきかが見えやすくなります。参照コンテンツは、Claude が今の作業へ適用する知識です。規約、パターン、スタイルガイド、ドメイン知識。タスクコンテンツは、デプロイ、コミット、コード生成のような具体的アクションに対するステップごとの指示です。
補助ファイルも束ねられます。Claude が実行できるスクリプト、埋められるテンプレート、必要なときだけ読み込む参照文書。Claude は、最初からコンテキストを使い切るのではなく、必要に応じて段階的に情報を読み込みます。いわば progressive disclosure のパターンです。 だから、1 つのファイルに収まらない豊かなスキルも、毎回のコンテキストを圧迫せずに持てます。
スキルが実際に適用されているかを検証する
ここは、今でも少し分かりづらさが残っています。
official Claude Code skills documentation によると、自動トリガーを決めるのは description フィールドです。Claude は起動時に利用可能なスキル description をすべて読み、そこからどのスキルを呼ぶかを判断します。200 を超えるプロンプトでの実地検証では、発火の安定性にはかなり差がありました。description を適切に最適化すると、発火率は 20% から 50% へ改善し、例を追加すると 90% まで上がります。
だから、スキルが発火しないときに最初に見直すべきなのは、たいてい description です。より具体的な言い方、より明示的なトリガー条件。Anthropic skills GitHub repository でも、この点ははっきり触れられています。Claude は発火を控えめにしがちなので、いつ 有効化すべきかを description へやや明示的に書いたほうがうまくいきます。
Skills が得意なこと
プロジェクト規約をエンコードする
ここで、私はこの仕組みの価値がはっきり見えてきました。チームに特有のパターン、たとえば API 応答の構造、エラーオブジェクトの形、非同期フローの扱い方があるなら、それを一度スキルへ書いてしまえば、毎回説明し直さなくてよくなります。
エージェント向けのスキルを作ることは、新しく入ったメンバー向けのオンボーディングガイドを作ることに近い。私にはその比喩がしっくりきました。永続メモリではない。どちらかといえば、Claude が必要なときに手を伸ばせる参照シートです。
繰り返せる出力フォーマット
スラッシュコマンドで呼び出すタイプのタスク指向スキルは、commit message 生成、PR 説明、デプロイチェックリストのような用途に向いています。欲しいのが一般論ではなく、出力の一貫した 形 である場合に効きます。
Claude にドメイン固有の文脈を与える
スキルは、あなたの専門知識を組み合わせ可能なリソースとして束ねることで Claude の能力を拡張し、汎用エージェントを、あなたのニーズに合った特化型エージェントへ変えていきます。ニッチな技術領域、たとえば独自 DSL、社内ツール、特殊なコンプライアンス規則を扱うチームでは、ここがかなり実用的に見えてきます。
Skills にできないこと
セッションをまたぐ学習がない
スキルは自分で更新しません。何がうまくいったかを観察して、自分の指示を書き換えることもありません。セッション開始時に SKILL.md に入っている内容が、そのまま Claude の出発点になります。変更したければ、手で編集するしかありません。Anthropic engineering blog on Agent Skills でも、こう明確に書かれています。「Claude と一緒に反復しましょう。Claude とタスクを進める中で、うまくいったアプローチをスキルへ取り込むよう Claude に頼んでください。」取り込むのは人間のステップです。Claude が自動でやるわけではありません。
実行フィードバックループがない
Claude がスキルを使って望ましくない出力を返しても、それを受けてスキル側が更新されることはありません。指示セットへ戻っていくシグナルがないからです。前回何が起きたかに関係なく、次回も同じガイダンスが適用されます。
チームやエージェントをまたいだ共有がない
Custom skills は各ユーザー個人のものです。組織全体では共有されず、管理者による一元管理もできません。ある開発者が書いたスキルが、勝手にチームメイトの環境へ伝播することはありません。ローカルに存在するか、共有したいならプロジェクトディレクトリへ手動で入れるしかない。
私はこの点を何度も考えてしまいます。一貫したエージェントの振る舞いを定義できる力は確かにある。でも、配布の問題はまだ残ったままです。
静的な Skills の先にあるもの
ファイルベースの指示から、検証済みで継承可能な能力へ
Skills 機能は、確かに現実の問題を解いています。繰り返し説明する負担を減らし、文脈をエンコードできるようにすることです。
でも、私はその先にあるギャップを何度も感じます。うまくいった修復、苦労して見つけたデバッグパターン、やっと安定して機能したプロンプトの流れ。そうした経験は、まだ移動しません。セッションの中にとどまるか、誰かが覚えていて、手作業で SKILL.md に畳み込んだときだけ残ります。
この下には、もっと大きな問いがあります。与えられた指示 と、多くのエージェントをまたいで検証された振る舞い の違いです。Skills は前者です。設計はよくできているし、組み合わせやすく、実用的です。でも、依然として静的な成果物でもある。人が作り、手で保守し、ローカルに閉じるものです。
似た問題に直面する他のエージェントへ、成功したアプローチを可視化し、検証し、利用可能な形で渡せたらどうなるのか。それは Skills format が扱っていない、そしておそらく扱おうともしていない、別種のインフラの問いです。
…もう少し考え続けてみます。
FAQ
- Claude Code の Skills 機能とは何ですか。 Claude Code Skills 機能 は、YAML frontmatter と Markdown 指示を含む構造化された SKILL.md ファイルを通じて、Claude の振る舞いを拡張する仕組みです。タスクがスキル description と一致したときに、Claude がそれを動的に読み込みます。
- Claude Code 用の SKILL.md ファイルはどう作りますか。
.claude/skills/your-skill-name/にフォルダを作り、その中へ SKILL.md を置きます。YAML frontmatter から始め、name と description を書き、その後に Markdown で指示を続けます。Anthropic skills repository には、出発点として使える template-skill があります。 - Claude Code Skills はセッション間で持続しますか。 持続するのは ファイル です。Claude がそれを使った記憶は持続しません。セッションごとに、Claude は description と指示をあらためて読み直します。セッションをまたぐ学習は組み込まれていません。
- Claude Code Skills をチームで共有できますか。 スキルディレクトリを手動で共有することはできます。リポジトリ内の
.claude/skills/フォルダを通す方法や、クロスプラットフォーム移植性を支える Agent Skills オープンスタンダード を使う方法です。ただし、現時点では組織的な自動同期はありません。 - Claude Code Skills と project rules の違いは何ですか。 Project rules（たとえば CLAUDE.md）は、プロジェクト全体の一般的な振る舞いを設定します。Skills は、タスクごとに使い分けるモジュール型の能力パッケージです。常時有効な文脈ではなく、Claude が何をしているかに応じて条件付きで読み込まれます。CLAUDE.md が環境としての指示なら、Skills はオンデマンドの専門知識です。
