こんにちは。Tradivanceです。
同じ指示を、何度も貼り直していませんか。「この形式でまとめて」「この順番で確認して」——毎回同じことを書いているなら、それは手順として渡せる形にできます。その仕組みがSkillsです。
作り方そのものは簡単で、ファイルを1つ置くだけです。ところが、作ったあとに効かなくなるという相談が出てきます。呼ばれない。呼ばれても言うことを聞かない。増やしたら前より悪くなった。
公式ドキュメントを読むと、その理由が書かれています。たとえば、こういう一文です。
「レンダリングされた SKILL.md コンテンツは会話に単一のメッセージとして入力され、セッションの残りの間そこに留まります」
本記事では、作り方を押さえたうえで、この「留まる」という性質から出てくる設計上の制約まで2026年8月時点の公式情報で扱います。当社もSkillsを実際の業務で運用しており、そこで分かったことも交えます。
本記事で分かること
- SKILL.mdの書き方と、設定できること
- 呼び出したスキルが会話に残り続けるという仕様（本体を短く保つ理由）
- 増やすほど説明が短縮されて、呼ばれにくくなること
- 効いているかを確かめる方法と、組織で配るときの権限
Claude Code Skillsとは｜同じ手順を貼り直すのをやめる仕組み
公式の説明はこうです。「スキルは Claude ができることを拡張します。SKILL.md ファイルに指示を記述すると、Claude はそれをツールキットに追加します」
ファイルを置くと、その中身が使える道具の1つとして登録されるというイメージです。呼び方は2通りで、関連する場面でClaudeが自分で読み込むか、スラッシュに続けて名前を入力して直接呼ぶかです。
どういうときに作るのか
作るタイミングも明記されています。「同じプレイブック、チェックリスト、または複数ステップの手順をチャットに何度も貼り付けるとき」、そして「CLAUDE.md のセクションが事実ではなく手順に成長したとき」です。
後半が要点です。「うちはこうしている」という事実の記述が、「こういう順で進める」という手順に育ってきたら、置き場所を変える合図ということです。
CLAUDE.mdとの違いは「いつ読まれるか」
| 置き場所 | いつ読まれるか | 向いている中身 |
|---|---|---|
| CLAUDE.md | 常に読まれます | 短く、いつも効いていてほしい前提 |
| SKILL.md | 使うときにだけ読まれます | 長い手順、参照資料 |
公式にはこう書かれています。「CLAUDE.md コンテンツとは異なり、スキルの本体は使用されるときにのみ読み込まれるため、長いリファレンス資料は必要になるまでほぼコストがかかりません」
もう1つ、古い解説記事と食い違う点があります。「カスタムコマンドはスキルにマージされました。」以前からある設定ファイルは引き続き動きますが、これから作るならスキルの側で作るほうが機能が多くなります。
なお、この仕組みは「Agent Skills オープンスタンダードに従い、複数の AI ツール全体で機能します」とされています。1つのツールに閉じた設定ではない、という点は社内で説明するときに効きます。
Claude Code Skillsが向く場面と、向かない場面
公式は、スキルの中身を2種類に分けて説明しています。この分け方が、向き不向きの判断にそのまま使えます。
| 種類 | 中身 | 呼び方 |
|---|---|---|
| リファレンス | 規約、パターン、スタイルガイド、その分野の知識 | 関連する場面でClaudeが読み込みます |
| タスク | 手順そのもの（決まった順で進める作業） | 名前を指定して自分で呼びます |
タスクの側について、公式は「多くの場合、Claude が実行を決定するのではなく、/skill-name で直接呼び出したいアクション」と書いています。実行のタイミングを自分で握りたいもの、という意味です。
向く形をつかむには、最初から入っているスキルを見るのが早道です。公式によれば、設定で無効にしない限り「すべてのセッションで利用可能な一連のバンドルされたスキル」があり、点検・レビュー・デバッグ・反復といった用途のものが含まれています。
ここに性質がよく表れています。公式は「固定ロジックを直接実行する組み込みコマンドとは異なり、バンドルされたスキルはプロンプトベースです。Claude に詳細な指示を提供し、ツールを使用して作業を調整させます」と説明しています。決まった処理を走らせるのではなく、進め方を渡して判断させるのがスキルだということです。
当社の実運用でうまくはまったのは、次のようなものでした。いずれも開発の作業ではありません。
- 動画企画を地域ごとに量産する手順（調べる順番と、出す形式が毎回同じ）
- 月次レポートの納品前チェック（見るべき項目が決まっている）
- 記事を入稿する前の点検（形式の確認が10項目以上ある）
共通しているのは、やることは同じで、対象だけが毎回変わるという形です。逆に、一度きりの作業や、その場の状況で判断が変わる仕事は向きません。手順に落とせないものを無理に落とすと、あとで読み返せない文章が残ります。
Claude Code Skillsの作り方｜SKILL.mdを1本書いてみる
作る手順は3つです。特別なツールは要りません。
ディレクトリを作る
個人用のスキルフォルダに、スキル名のディレクトリを作ります。ここに作ると、すべてのプロジェクトで使えます。公式には個人用が~/.claude/skills/の下、プロジェクト用が.claude/skills/の下と示されています。
SKILL.mdを書く
公式によれば、このファイルは「2 つの部分があります」。前半のフロントマターは「Claude にスキルをいつ使用するかを伝え」、後半のマークダウンは「スキルが実行されるときに Claude が従う指示」です。いつ使うかと、何をするか。この2つを分けて書きます。
呼んで確かめる
説明文に一致することを聞いて自動で呼ばれるか試し、次にスラッシュと名前で直接呼びます。自動では呼ばれないが直接なら動く場合、原因は本文ではなく説明文の側にあります。
ここで2つ、覚えておくと迷わない点があります。1つは「ディレクトリ名はコマンドになり」という仕様です。ファイルの中で名前を書き換えても、呼ぶときの名前は変わりません。フォルダ名がそのまま呼び名になります。
もう1つは分量です。公式は「SKILL.md を 500 行以下に保ちます」と書いています。なぜ上限があるのかは、この記事の後半で扱います。先に理由を知っておくと、書き方そのものが変わります。
長くなったら、別のファイルに逃がします
手順を書き始めると、たいてい長くなります。公式は、スキルは1つのディレクトリで、複数のファイルを持てると案内しています。狙いはこう説明されています。
「SKILL.md は本質的なものに焦点を当てながら、Claude は必要な場合にのみ詳細なリファレンス資料にアクセスできます」
| ファイル | 役割 |
|---|---|
| SKILL.md | 必須。全体の見取り図と、どこに何があるかの案内 |
| 参照用の資料 | 詳しい仕様や規約。必要になったときだけ読まれます |
| 例を書いたファイル | 期待する出力の見本 |
| スクリプト | 読み込まれるのではなく、実行されます |
1つだけ守ることがあります。公式は「SKILL.md からこれらのファイルを参照して、Claude が各ファイルの内容と読み込むタイミングを知るようにします」としています。置いただけでは使われません。本体から「これはこういう資料で、こういうときに見る」と書いておく必要があります。
当社でも、手順が育ってきた段階でこの形に移しました。本体には判断の順番だけを残し、細かい書式や事例は別ファイルに出すと、あとから直す場所も分かりやすくなります。
Claude Code Skillsのフロントマターで設定できること
フロントマターは、スキルの振る舞いを決める設定欄です。公式には「すべてのフィールドはオプションです。Claude がスキルをいつ使用するかを知るために、description のみが推奨されます」とあります。
よく使うフィールド
| フィールド | 何を決めるか |
|---|---|
| description | 何をするか、いつ使うか。Claudeが読み込むかどうかの判断に使われます |
| when_to_use | 呼ぶべき場面の追加説明（トリガーになる言い回しなど） |
| allowed-tools | このスキルが動いている間、承認を求めずに使えるツール |
| disable-model-invocation | Claudeが自動で読み込むのを止めます |
| user-invocable | スラッシュのメニューから隠します |
| context / agent | 別のコンテキストで動かすかどうかと、その実行役 |
| paths | どのファイルを扱っているときに読み込むかを絞ります |
| model / effort | このスキルが動いている間のモデルと、考える深さ |
誰が呼べるかを決める3パターン
設定の中でも、先に決めておく価値があるのが呼び出しの制御です。既定では、あなたもClaudeも呼べます。
| 設定 | 呼べる人 | 向いている中身 |
|---|---|---|
| （既定） | あなたとClaudeの両方 | ふつうの手順 |
| disable-model-invocation | あなただけ | 副作用があるもの |
| user-invocable: false | Claudeだけ | 背景知識（実行するものではない） |
公式が挙げている理由が具体的です。前者について、「/commit、/deploy、/send-slack-message など、副作用があるワークフロー、またはタイミングを制御したいワークフロー用です」とし、続けてこう書いています。
「コードが準備完了に見えるため、Claude がデプロイを決定することは望ましくありません」
ここは業務でもそのまま当てはまります。送信、公開、請求、削除。取り消せない操作を含む手順は、自動で呼ばれないようにしておくという設計です。当社でも、外に出るものを扱う手順にはこの設定を入れています。
Claude Codeのスキルを置く場所｜4段階と優先順位
置く場所によって、誰が使えるかが変わります。公式は4段階を示しています。
| 場所 | 適用対象 |
|---|---|
| Enterprise | 組織内のすべてのユーザー（管理設定から配ります） |
| Personal | 自分のすべてのプロジェクト |
| Project | そのプロジェクトだけ |
| Plugin | プラグインが有効な場所 |
同じ名前があったときの優先順位
名前がぶつかったときの順番も決まっています。「enterprise は personal をオーバーライドし、personal はプロジェクトをオーバーライドします」
組織が配ったものがいちばん強い、という並びです。さらに「任意のレベルのスキルは、同じ名前のバンドルされたスキルもオーバーライドします」とされており、最初から入っているものも同名で置き換えられます。
会社として下限を引きたい場合、この順番が効いてきます。各自の手元の設定で緩められない位置に置けるということだからです。
直したその場から効きます
編集の反映についても記載があります。ファイルの変更は監視されており、「再起動せずに現在のセッション内で有効になります」。手を入れながら試す進め方ができます。
ただし例外があります。「セッション開始時に存在しなかった最上位のスキルディレクトリを作成するには、Claude Code を再起動」する必要があるとされています。いちばん最初の1本だけは、作ったあとに立ち上げ直すと覚えておくと迷いません。
下の階層に置いたスキルも拾われます
大きなリポジトリで、部分ごとにやり方が違う場合の仕組みもあります。公式によれば、「Claude がサブディレクトリ内のファイルを読み取りまたは編集する場合、そのサブディレクトリのスキルが利用可能になります」とされています。
上の階層で作業を始めても、触っているファイルの近くにあるスキルが、その場で効くようになるということです。
名前が上の階層のものとぶつかった場合はディレクトリ名を付けた形で区別され、公式は「Claude は、作業しているファイルに一致するバリアントを選択します」と説明しています。
Claude Code Skillsは呼び出すと会話に残り続ける
ここが、本記事でいちばんお伝えしたい部分です。スキルは、呼んだあとも会話の中に居座ります。
読み直されるのではなく、置かれたままになります
公式の記述です。「レンダリングされた SKILL.md コンテンツは会話に単一のメッセージとして入力され、セッションの残りの間そこに留まります」。続けて「Claude Code は後のターンでスキルファイルを再度読み込まない」とあります。
つまり、呼んだ瞬間に中身が丸ごと会話に貼られ、そのあとは貼られたものを見ているという動きです。ファイルを直しても、すでに始まっている会話の中身は差し替わりません。
だから書き方が変わります
公式はこの性質から、書き方の指針を1つ導いています。「タスク全体を通じて適用すべきガイダンスを、1 回限りのステップではなく、スタンディング指示として記述します」
「まず〜する」「次に〜する」という一過性の順番より、「この作業の間は、常にこうする」という立ち続ける指示のほうが噛み合うということです。当社でも、手順書をそのまま貼ったスキルより、判断の基準を書いたスキルのほうが最後まで効きました。
500行という上限の理由
先ほど保留にしていた話につながります。公式は本体を簡潔に保つ理由をこう説明しています。「スキルが読み込まれると、そのコンテンツはターン全体でコンテキストに留まり、すべての行が繰り返されるトークンコストになります」
長く書くほど、そのあとのやり取りすべてに重さが乗ります。1回読まれて消えるものではないため、分量がそのまま持ち出しになるという構造です。詳しい資料は別ファイルに逃がして、本体からは参照だけする形が推奨されています。
会話が長くなったときの挙動も書かれています。要約が入る際、各スキルの最新の呼び出しは再び付け直されますが、保持されるのは先頭部分だけで、しかも付け直される分には全体の上限があります。
その結果として、公式はセッション内で多くのスキルを呼び出した場合、要約のあとに古いスキルがまるごと落ちる可能性があると述べています。たくさん呼んだ日ほど、最初に呼んだものが消えているということです。
効かなくなったように見えるときの見立ても示されています。「コンテンツは通常まだ存在し、モデルは他のツールまたはアプローチを選択しています」。消えたのではなく、選ばれていないということです。長い作業の途中で怪しくなったら、もう一度呼び直すのが早い対処になります。
Claude Codeのスキルを増やすほど、説明が短縮される
もう1つ、増やしていくと出てくる制約があります。スキルの説明文は、多くなると削られます。
削られると、呼ばれなくなります
公式の記述です。「リストには常にすべてのスキル名が含まれていますが、多くのスキルがある場合、Claude Code はリストの文字予算に合わせて説明を短縮する可能性があり、Claude が要求と一致するために必要なキーワードを削除できます」
名前は残るが、呼ばれるかどうかを決めている説明のほうが削られるという動きです。しかも削られる順番も決まっていて、呼び出しの少ないものから短くされます。使っていないスキルほど、さらに使われなくなっていきます。
この予算は「モデルのコンテキストウィンドウの 1% でスケーリングされます」とされています。会話に使える容量に比例する形で、リストの取り分が決まるということです。
気づく方法と、打てる手
削られていることは、黙って起きます。公式は確認の方法として「/doctor を実行して、リストのコンテキストコストとその最大の貢献者の推定値を確認します」と案内しています。どのスキルが場所を取っているかまで分かります。
打てる手は3つです。予算そのものを設定で上げる。使用頻度の低いものを名前だけの表示に落とす。そして説明文を短く書き直すことです。
3つ目に関わる仕様も明記されています。説明と補足を合わせたテキストには文字数の上限があり、超えると短縮されます。だからこそ公式は「主要なユースケースを前置きしてください」と書いています。後ろに置いた言葉は、削られたときに真っ先に消えます。
Claude Code Skillsに引数を渡す・実行結果を差し込む
同じ手順を対象だけ変えて回すなら、呼ぶときに値を渡す形にしておくと1本で済みます。
値を受け取る
スキルの本文に置いたプレースホルダーが、呼び出し時の入力に置き換わります。まとめて受け取る書き方と、位置を指定して個別に受け取る書き方があり、フロントマターで名前を付けておくこともできます。
気が利いているのは、入れ忘れたときの動きです。公式によれば、プレースホルダーが本文に無い場合でもスキルの末尾に入力内容が追記されるため、渡した言葉は届きます。
実行結果をあらかじめ差し込む
もう一段強力なのが、コマンドの実行結果をスキルの中に埋め込む書き方です。公式はこう説明しています。「スキルコンテンツが Claude に送信される前にシェルコマンドを実行します」
順番が大事です。「これは前処理であり、Claude が実行するものではありません。Claude は最終結果のみを見ます」。Claudeに「調べてきて」と頼むのではなく、調べた結果を持たせた状態で渡すということです。手順の最初の数往復がまるごと消えます。
書き方にも決まりがあります。複数行を実行したいときは、インラインではなく専用の書き方をしたコードブロックを使うとされています。また、記号が「行の開始時または空白の直後に表示される場合にのみ認識されます」と明記されており、文中の途中に置くとそのまま文字として残ります。
もう1点、「置換は元のファイルに対して 1 回実行されます」という記述があります。実行結果の中にさらに書いておいても、それは展開されません。入れ子にした処理は組めない、という前提で設計します。
組織で使うときは、この動きを止める設定もあります。公式は無効化の設定を挙げたうえで、「この設定は管理設定で最も有用です。ユーザーはそれをオーバーライドできません」と書いています。手元で緩められない位置から止められるという意味です。
Claude Code Skillsをサブエージェントで動かす
長い調査や、途中経過を本筋に混ぜたくない作業は、別の場所で動かす設定にできます。フロントマターで指定すると、スキルの中身がそのまま別担当への依頼文になります。
その代わり制約があります。公式には「会話履歴にアクセスできません」と明記されています。ここまでのやり取りを踏まえた作業には向きません。
もう1つ、注意書きが親切です。「context: fork は明示的な指示を含むスキルにのみ意味があります」とされ、指示ではなく心構えだけを書いたスキルをこの設定で動かすと「実行可能なプロンプトがなく、意味のある出力なしで返されます」と説明されています。
別の場所に投げるなら、そこには「やること」が書かれていなければなりません。規約集のようなスキルは、この設定と相性が悪いということです。実行役は指定でき、省略した場合の既定も決まっています。
スキルと別担当の関係は2方向で整理されています。スキルの側から別担当を呼ぶ形では、指示の土台は担当の種類から来て、やることはスキルの中身になります。逆に、担当の側があらかじめスキルを抱えておく形もあり、こちらは担当の本文が土台になります。
選ぶときの目安も書かれています。調査や計画に特化した担当は「CLAUDE.md と git status をスキップしてコンテキストを小さく保つ」とされています。身軽に動かしたいなら、前提を読み込まない担当を選ぶという設計です。
Claude Code Skillsが効いているかを確かめる
作ったスキルが呼ばれると、うまくいった気がします。公式は、そこを明確に否定しています。
「スキルがトリガーされるのを見ることは、Claude がそれを見つけたことを示しており、意図したことをしたことを示していません」
2つに分けて測ります
見るべきものは2つです。呼ぶべき場面で呼ばれるかと、呼ばれたときの出来が期待どおりか。この2つは原因も対処も違います。
| 症状 | 疑うところ |
|---|---|
| そもそも呼ばれない | 説明文（読者が自然に使う言葉が入っているか） |
| 呼ばれるが出来が悪い | 本文の指示（判断の基準が書かれているか） |
| 関係ない場面で呼ばれる | 説明文が広すぎます |
当社の実運用でも、直すべきは本文ではなく説明文だった、という場面が繰り返しありました。中身をいくら磨いても、呼ばれなければ出番が来ません。
比べ方には作法があります
測り方も示されています。「両方のチェックはベースライン比較です」——同じ問いを、スキルがある状態とない状態の両方で回して見比べます。
ここに落とし穴があります。「新しいセッションが重要です。スキルの作成から残っているコンテキストは、書かれた指示のギャップをマスクするためです」
作った直後の会話でそのまま試すと、書き忘れたことを、その会話の流れが埋めてしまいます。自分の環境ではうまく動くのに他の人が使うと動かない、という現象の正体はここにあります。
この比較を自動で回すプラグインも提供されています。提供元の記事は「テストは、動いているように見えるスキルを、動くと分かっているスキルに変える」という趣旨を述べたうえで、自社の文書作成スキルに適用した結果として公開しているスキル6本のうち5本で呼ばれ方が改善したと報告しています（2026年3月3日公開）。同記事は「説明の精度が決定的になる。広すぎれば誤って発火し、狭すぎれば一度も発火しない」とも書いています。
Claude Codeのスキルを組織で配るとき｜権限と確認
1人で使っていたものを配る段になると、見るところが変わります。配布の経路は3つあり、プロジェクトに入れて共有する／プラグインにまとめる／管理設定から組織全体に配ると示されています。
誤解しやすい設定が1つあります
先ほどの表に出てきたallowed-toolsです。名前から「使えるツールを絞る設定」に見えますが、逆です。公式にはこう書かれています。
「リストされたツールの権限を付与するため、Claude はあなたに承認を求めることなくそれらを使用できます」「これは利用可能なツールを制限しません」
絞るのではなく、確認を省く設定です。他人が書いたスキルを入れるときは、ここに何が書かれているかで挙動がまるで変わります。公式も注意を促しています。「スキルが広範なツールアクセスを許可できるため、リポジトリを信頼する前にプロジェクトスキルを確認してください」
止める側の設定
絞りたい場合は、権限の側で指定します。スキルの機能そのものを拒否することも、名前を指定して個別に許可・拒否することもできると案内されています。
もう1つ、ファイルを書き換えずに見せ方だけを変える設定もあります。公式には4つの状態が示されており、名前と説明の両方を出す、名前だけにする、Claudeには見せずメニューにだけ出す、両方から隠す、という段階が選べます。共有リポジトリに入っていて中身を直したくないスキルは、この設定で扱います。
当社が伴走の場面でお伝えしているのは、設定より先に決めることがある、という点です。配る前に「中身を誰が読むか」を決めておくことです。読む人が決まっていないまま便利なスキルが回り始めると、あとから止められません。
Claude Code Skillsのよくある質問
プログラミングができなくても作れますか？
作れます。SKILL.mdは、前半に「いつ使うか」を書き、後半に「何をするか」を日本語で書くだけの文書です。公式のフィールドはすべて任意とされており、推奨されているのは説明の欄だけです。当社が運用しているものにも、動画企画の手順やレポートの点検手順など、開発とは関係のないものが含まれています。
CLAUDE.mdとどう使い分けますか？
読まれるタイミングが違います。CLAUDE.mdは常に読まれるため、短くていつも効いていてほしい前提を置きます。スキルは使うときにだけ読まれるため、長い手順や参照資料を置けます。公式も、CLAUDE.mdのセクションが事実ではなく手順に育ってきたらスキルを作るタイミングだと案内しています。
なぜ500行以下にするのですか？
呼び出したスキルの中身が、会話にそのまま残り続けるためです。公式は「すべての行が繰り返されるトークンコストになります」と説明しています。1回読まれて消えるものではないので、書いた分量がそのあとのやり取り全体に乗ります。詳しい資料は別ファイルに移し、本体からは参照だけする形が推奨されています。
スキルが呼ばれないときは何を見ますか？
まず説明文です。自分が自然に使う言葉が入っているかを確認します。次に、スラッシュと名前で直接呼んで動くかを試します。直接なら動くのに自動では呼ばれない場合、原因は本文ではなく説明文の側にあります。なお公式には、フロントマターの書式が壊れていると本体だけが読み込まれて説明が空になる、という記述もあります。
スキルを増やしすぎるとどうなりますか？
説明が短縮されます。公式によれば、名前は全件残る一方で説明は文字予算に合わせて削られ、呼び出しの少ないものから短くなります。呼ばれるかどうかを決めているのは説明のほうなので、使っていないスキルはさらに使われなくなります。どれが場所を取っているかは公式が案内している確認コマンドで見られます。
勝手に実行されないようにできますか？
できます。フロントマターで自動の読み込みを止めると、自分がスラッシュで呼んだときだけ動くようになります。公式もこの設定を、副作用があるワークフローやタイミングを制御したいワークフロー向けだと説明しています。送信・公開・削除のように取り消せない操作を含む手順には入れておくことをおすすめします。
チームで共有するにはどうしますか？
3つの経路が案内されています。プロジェクトのフォルダに入れてバージョン管理に含める方法、プラグインとしてまとめる方法、管理設定から組織全体に配る方法です。名前が重なった場合は組織のものが優先されるため、会社として下限を引きたい場合はいちばん上の階層に置きます。
他のAIツールでも使えますか？
公式には、Agent Skillsというオープンスタンダードに従っており、複数のAIツール全体で機能すると記載されています。Claude Code側では呼び出しの制御や別コンテキストでの実行といった拡張が加えられているため、その部分は環境によって扱いが変わります。書いた手順そのものは持ち運べる、という理解でよいと考えています。
まとめ｜Claude Code Skillsは「手順を資産にする」
2026年8月時点の公式情報から、要点を4つにまとめます。
- 呼び出すと会話に残り続けます。だから本体は短く、立ち続ける指示として書きます
- 増やすほど説明が短縮されます。削られるのは呼び出しの少ないものからです
- 呼ばれた＝うまくいった、ではありません。呼ばれるかと、出来がよいかを別々に測ります
- allowed-toolsは制限ではなく事前承認です。他人のスキルを入れる前に中身を読みます
作ること自体は、ファイルを1つ置くだけで終わります。差が出るのはそのあとです。毎回貼り直していた手順が、読み返せて、直せて、人に渡せる形になる。これは業務そのものを言語化する作業でもあります。
当社では、AIに任せる業務の切り出しから、こうした手順を社内で回せる状態にするところまでご支援しています。使ってはいるが属人的なまま、という段階からのご相談も承っています。お気軽にご相談ください。
