Claude Codeのスキル（Skills）の作り方（2026年6月）

今回は、Claude Codeのスキル（Skill）の作り方を、最小構成から順に整理します。

あくまで筆者の環境での運用に基づく内容なので、お使いの環境やバージョンによって異なる場合があります。また、2026年6月時点の情報である点にご留意ください。

スキルは、繰り返す作業手順をフォルダにまとめて、必要なときだけClaudeに読み込ませる仕組みです。設定ファイルの使い分けの記事ではSkillsの位置づけを紹介しましたが、この記事では実際にSKILL.mdを書くところに絞って解説します。

この記事のターゲット

• Claude Codeのスキルを自分で書いてみたい方

• SKILL.mdのfrontmatterに何を書けばいいのか知りたい方

• スキルが自動で起動する仕組みと、起動しないときの勘所を知りたい方

スキルとは何か

スキル（Skill）は、SKILL.md という1枚のMarkdownファイルを中心にした、再利用可能な作業手順の置き場所です。コードレビューの観点、記事の文体チェック、リリースノートの生成手順など、「毎回同じ説明をするのが面倒な作業」をここにまとめておきます。

CLAUDE.mdとの住み分けは「事実か、手順か」で考えると整理できます。CLAUDE.mdには、アーキテクチャや命名規約のように常に真であってほしい事実を、毎ターン読まれる前提で短く書きます。

スキルには、特定のタスクをこなす手順を、起動したときだけ読み込まれる前提で書きます。CLAUDE.mdが常駐する前提知識、スキルが呼び出し式のレシピ、という分担です。

最小のSKILL.mdを作る

スキルは1ファイルから始められます。プロジェクトで使うなら、リポジトリ直下に次のように置きます。

.claude/skills/ └── release-notes/ └── SKILL.md

SKILL.mdの中身は、frontmatterと本文だけのシンプルなものでかまいません。

Claude Codeでは、frontmatterの項目はすべて任意です。実用上は description だけ書いておけば動きます。name を省略するとフォルダ名が、description を省略すると本文冒頭の段落が、それぞれ代わりに使われます。

個人の全プロジェクトで使いたい場合は、リポジトリ内ではなくホーム配下の ~/.claude/skills/ に同じ構成で置きます。

frontmatterを書く

frontmatterは、スキルの振る舞いを決めるYAMLのヘッダです。Claude Codeでよく使う項目は次の通りです。

最も大事なのは description です。後述するように、Claudeがスキルを起動するかどうかは基本的にこの説明文を手がかりに判断します。「何をするスキルか」と「いつ使うか」の両方を、三人称の説明調で書いておくのがポイントです。

ほかにも argument-hint、context、agent、paths といった項目があります。たとえば、このブログのリポジトリで使っている repo-audit というスキルのfrontmatterは次のようになっています。

context: fork は、スキルを独立したサブエージェントで実行する指定です。agent: Explore でその種別を、allowed-tools でそのサブエージェントが使えるツールを読み取り系に限定しています。設定を監査するだけで、ファイルは書き換えてほしくないスキルなので、この絞り込みが効いています。

スキルの置き場所とスコープ

スキルは置き場所によってスコープが変わります。大きく分けて、組織管理（Enterprise）、個人（Personal、~/.claude/skills/）、プロジェクト（Project、.claude/skills/）、プラグイン同梱の4種類です。

注意したいのは優先順位です。同名のスキルがある場合、組織 > 個人 > プロジェクトの順で優先されます。settings.jsonの優先順位とは逆向きなので、チーム共有のプロジェクトスキルが、各自の個人スキルに気づかないうちに上書きされることがあります。

スラッシュコマンドとして呼ぶときの名前は、原則としてフォルダ名で決まります。release-notes/SKILL.md なら /release-notes です。frontmatterの name が呼び出し名を決めるのは、プラグインのルートにあるSKILL.mdだけで、それ以外では name は一覧に出る表示ラベルにすぎません。

既存のスキルフォルダの中でSKILL.mdを追加・編集・削除した場合は、再起動なしで反映されます。新しくトップレベルのスキルフォルダを作ったときだけ、再読み込みが必要です。

段階的開示

スキルの設計で意識しておきたいのが、段階的開示（progressive disclosure）という考え方です。スキルは3段階に分けて読み込まれます。

メタデータは常にコンテキストに乗るので、スキルが増えるほど固定コストがかさみます。逆に参照リソースは、本当に必要になったときだけ読まれます。よって、SKILL.md本文は短く保ち（公式の目安は500行未満）、長い資料やデータは別ファイルに逃がすのが基本です。

参照ファイルはSKILL.mdから1階層下までにとどめ、100行を超える資料には冒頭に目次を付けると探しやすくなります。

先ほどの repo-audit は、実際にこの形をとっています。

repo-audit/ ├── SKILL.md # 手順本体 ├── analyzer.sh # 同梱スクリプト ├── reference.md # 参照ファイル（1階層下） └── README.md

SKILL.mdの本文からは、bash "${CLAUDE_SKILL_DIR}/analyzer.sh" のように同梱スクリプトを実行しています。${CLAUDE_SKILL_DIR} はスキル自身の場所を指す変数で、どこに配置されても自分のスクリプトを呼べます。

重い処理や決まりきった集計はスクリプトに任せ、SKILL.md本文は手順の説明に専念させる、という分担です。

動的なコンテキスト注入

SKILL.mdには、読み込まれる瞬間にコマンドの実行結果を埋め込む記法があります。バッククォートの前に感嘆符を付けて !git branch --show-current`` と書くと、その箇所が実行結果に置き換わります。

現在のブランチ: !`git branch --show-current` 直近のコミット: !`git log -1 --oneline`

ここで押さえておきたいのは、これが前処理だという点です。置き換えはスキルが読み込まれる前に一度だけ行われ、Claudeは置き換わったあとの結果だけを見ます。再帰的には展開されず、感嘆符が行頭か空白の直後にあるときだけ認識されます。

先ほどの repo-audit がスクリプトをBashツールで実行していたのとは、性質が違います。!command`` は「読み込み時点の状況をスキルに刷り込む」ためのもので、「Claudeが判断してから実行する」用途には使えません。状況に応じてコマンドを使い分けたいなら、allowed-tools でツールを許可して、本文に手順として書くほうが向いています。

ちなみに、引数を受け取りたい場合は $ARGUMENTS や $1（最初の引数）といった変数も使えます。セッションIDを指す ${CLAUDE_SESSION_ID} のような変数も用意されています。

自動起動と手動起動の切り替え

スキルには、Claudeが文脈から自動で起動する経路と、利用者が /スキル名 で明示的に起動する経路の2つがあります。disable-model-invocation と user-invocable の組み合わせで、どちらを許すかを制御します。

2つのフラグは向きが逆なので混同しやすいところです。disable-model-invocation: true はClaudeに勝手に起動させない設定で、ユーザー専用のコマンドになります。説明文がシステムプロンプトに常駐しなくなるため、自動起動の判断材料からも外れます。一方の user-invocable: false はメニューに出さない設定で、Claudeが裏で使う専用スキルになります。

自動起動を効かせたいなら、description の質がそのまま命中率になります。動名詞形の名前（たとえば processing-pdfs）にして、「PDFからテキストを抽出するとき」のように起動条件を説明文に織り込むと、Claudeが拾いやすくなります。

スキルを評価して磨く

スキルは一度書いて終わりではなく、効いているかどうかを確かめながら直していくものです。公式のベストプラクティスでは、詳しいドキュメントを書き込む前に、まず評価を用意することが勧められています。

手順としては、スキルなしで代表的なタスクをやらせてみて、どこでつまずくかを確かめます。そのギャップを埋める最小限の指示だけをSKILL.mdに書き、スキルあり・なしを毎回まっさらなセッションで比べます。最初から盛り込みすぎず、失敗した分だけ足していくほうが、無駄のないスキルになります。

この評価の流れ自体を自動化してくれる skill-creator という公式スキルもあります。スキルを本格的に育てるなら、導入を検討してみてください。

注意点

書いていてつまずきやすい点をいくつか挙げておきます。

frontmatterのキー名は表記が揃っていないので、ドキュメントからそのまま写すのが安全です。allowed-tools や disable-model-invocation はハイフン区切り、when_to_use はアンダースコア区切りです。allowedTools のようなキャメルケースは認識されないようです。

description の文字数上限は1,024文字です。一覧表示のときに切り詰められる長さとは別の値なので、説明文そのものはこの範囲に収めます。特にClaudeでは、name に claude や anthropic といった予約語は使えない点にも注意してください。

git worktreeを切ると、.claude/skills/ がまるごと複製されます。同名のスキルが並存して、修飾名（worktree名:スキル名）で衝突して見えることがあります。

まとめ

Claude Codeのスキルの作り方で押さえておきたいポイントは次の通りです。

• スキルは .claude/skills/スキル名/SKILL.md の1枚から始められ、description の質が起動の命中率を決める

• 本文は短く保ち、長い資料やスクリプトは別ファイルに逃がす（段階的開示）

• !command`` は読み込み時の前処理、allowed-tools で許したツールは実行時の判断、と役割が分かれている

• 自動起動と手動起動は disable-model-invocation と user-invocable で切り替える

まずはひとつ、繰り返している作業をSKILL.mdに書き出してみると、勘所がつかみやすいと思います。ぜひ小さいスキルから試してみてください。

参考にしたドキュメント

• Skills（Claude Code Docs）

• Agent Skills overview（Claude Docs）

• Agent Skills best practices（Claude Docs）

• Agent Skills specification（agentskills.io）