やす研究所 AI Lab
戻る

Claude Code Skills自作入門2026:SKILL.mdで専門化する実装手順

Claude Code Skills自作入門2026:SKILL.mdで専門化する実装手順

Claude Code を毎日使っていると、同じ指示を何度も貼り直している自分に気づくはずです。「このリポジトリのコミット規約はこうで、テストはこう書いて、デプロイ手順はここを見ろ」——私もそうでした。

それ、Agent Skills に切り出すと一気に楽になります。先週、自分の Astro ブログ用に小さな skill を3つ書いてみたら、プロンプト冒頭の定型文がほぼゼロになりました。本記事では、SKILL.md の最小構成から、.claude/skills 配下に置いて自動ロードさせるまでを、実際のコード例で説明します。

結論:Skills は「フォルダ単位のプロンプトキャッシュ」だと考える

先に結論を書きます。Agent Skills の本質は、必要なときだけ Claude が自分で読みに行く、フォルダ形式の手順書です。サブエージェントが「別のセッションで動く実行体」だとすれば、Skills は「Claude 本人が参照するナレッジモジュール」。レイヤーが違います。

Anthropic の公式ドキュメントでは、Skills を「ワークフロー、コンテキスト、ベストプラクティスを提供する、再利用可能でファイルシステムベースのリソース」と定義しています。プロンプトとの違いは、会話のたびに同じ指示を貼り直さなくていいこと。Claude が必要だと判断したときだけ on-demand でロードされます。

しかも 2025年12月18日にオープン標準として公開されたので、Claude.ai・Claude Code・Agent SDK のどこでも同じ形式で動きます。一度書けば使い回せる、これが地味に効くんですよね。

なぜ今 Skills を学ぶ価値があるのか

2026年5月29日のリリースで .claude/skills ディレクトリ配下のプラグインがマーケットプレイスなしで自動ロードされるようになりました。さらに claude plugin init <name> で新しいスキルの雛形をワンコマンドでスキャフォールドできます。要するに、参入コストが過去最低です。

Anthropic のエンジニア自身が「社内で Claude Code 用に何百ものスキルを本番運用している」と書いていて、もはや一部のヘビーユーザー向けの飛び道具ではありません。むしろ標準装備に近づいています。

正直に言うと、私も最初は「CLAUDE.md でいいじゃん」と思っていました。でも skill はフォルダである、という一点が決定的に違うんです。スクリプト・参考データ・サブドキュメントを束ねて、Claude が必要に応じて読み分けてくれる。これは想像以上に効きました。

SKILL.md の最小構成:まず動くものを作る

スキルの実体は、SKILL.md を含む1個のディレクトリです。YAML フロントマターに name と description を書く、それだけが必須要件。

---
name: astro-blog-publisher
description: Astro ブログの記事を新規作成・公開する手順。frontmatter のスキーマ、slug 命名規則、`pnpm build` での検証フローをカバー。記事の追加・更新時に使う。
---

# Astro Blog Publisher

## いつ使うか
ユーザーが「新しい記事を書く」「ブログを更新する」と言ったとき。

## 手順
1. `src/content/posts/YYYY-MM-DD/` に Markdown ファイルを作成する
2. frontmatter は `references/frontmatter-schema.md` を参照
3. 本文を書き終えたら `pnpm build` で型エラーがないか確認
4. `git add` → コミットメッセージは `post: <title>` 形式

## Gotchas(よくある落とし穴)
- slug に日本語を入れると Vite のビルドが失敗する
- `pubDate` は ISO8601 で書かないと RSS が壊れる
- 画像は `public/images/posts/` に置く(`src/assets/` ではない)

ポイントは description の書き方です。何をするか + いつ使うか の両方を入れる。これがないと Claude は「このスキル、今呼ぶべきだっけ?」を判断できません。

起動時に Claude はインストール済みすべての skill の name と description だけをシステムプロンプトに読み込みます。本文は呼ばれたときだけロードされる、これが progressive disclosure と呼ばれる設計です。だから description は妥協してはいけない。

フォルダ構造を活かす:references と scripts の分け方

SKILL.md 1ファイルで終わらせるのはもったいない。Anthropic の中の人も「skill はフォルダであって、ただの Markdown ではない」と強調しています。

私が運用している構成はこんな感じです。

.claude/skills/astro-blog-publisher/
├── SKILL.md
├── references/
│   ├── frontmatter-schema.md
│   └── seo-checklist.md
├── examples/
│   ├── tech-article.md
│   └── essay.md
└── scripts/
    └── validate-frontmatter.ts

SKILL.md 本体には手順の骨格とファイル一覧の説明だけを書きます。詳細は references/ に逃がす。Claude は SKILL.md を読んで「あ、frontmatter のスキーマは references/frontmatter-schema.md にあるんだな」と判断し、必要なときだけ開きます。

コンテキスト消費が抑えられるので、長い手順書を抱えてもトークンを食い潰しません。実質「無限に詰め込める」設計、と公式ブログでも表現されています。

Gotchas セクションは妥協しない

Anthropic のエンジニアが書いていて、私も同意したのが「スキルで一番価値があるのは Gotchas(つまずきポイント)セクション」という指摘です。

なぜか。Claude はそのライブラリや CLI の一般的な使い方はだいたい知っています。差別化になるのは、Claude がデフォルトで間違える箇所を先回りで書いてあげること。日本語の slug でビルドが落ちる、特定のバージョンで挙動が変わる、そういう生々しい情報こそが効きます。

私の場合、Claude が実際に間違えた瞬間にすぐ Gotchas に追記する運用にしています。スキルが少しずつ賢くなる感覚があって、ちょっと楽しい。

自動ロードさせる3つの配置パターン

スキルを Claude Code に読み込ませる場所は、大きく3つあります。

1. プロジェクトローカル: .claude/skills/<name>/SKILL.md リポジトリにコミットして、チーム全体で共有するパターン。2026年5月29日のアップデートでマーケットプレイス登録なしに自動ロードされるようになりました。これが今のおすすめです。

2. ユーザーグローバル: ~/.claude/skills/<name>/SKILL.md 自分専用、全プロジェクトで使い回したいもの。Anthropic 公式ブログでも「手動でインストールするなら ~/.claude/skills に置けばいい」と案内されています。

3. プラグイン経由: anthropics/skills マーケットプレイス 公式やコミュニティが配布している skill を取り込むパターン。たとえば PDF 処理や Excel 生成は Anthropic 製のものが用意されています。

雛形を作るなら claude plugin init <name> を .claude/skills 配下で叩くだけ。これで SKILL.md と最小のディレクトリが生成されます。

実例:claude-api skill から学ぶ「賢い skill」の書き方

参考になるのが、Claude Code にバンドルされている公式 claude-api skill です。中身が公開されているので、構成を覗いてみると勉強になります。

この skill のすごいところは、いつ起動するかの条件が極めて具体的なこと。たとえば「コードが anthropic SDK(Python)や @anthropic-ai/sdk(TS/JS)を import している」「Claude API や Managed Agents の機能(prompt caching、adaptive thinking、tool use、batch、citations、memory など)を追加・修正・チューニングしている」といった起動トリガーが列挙されています。

逆に、一般的なプログラミングタスクや OpenAI SDK を使っているコードでは起動しない、と明示している。この「起動しない条件」まで書くのが、誤発火を防ぐコツなんですよね。

さらにモデル ID の差し替え(Model.CLAUDE_OPUS_4_7 → Model.CLAUDE_OPUS_4_8)や、Opus 4.8 / 4.7 で temperature・top_p・top_k が削除された破壊的変更、thinking: {type: "enabled", budget_tokens: N} から thinking: {type: "adaptive"} への変換まで自動でやってくれる。ここまでくると、もはやマイグレーションツールです。

自作 skill でも、description にいつ動くか・いつ動かないかを両方書く癖をつけると、精度が一段上がります。

サブエージェントや MCP との使い分け

ここがよく混乱するところ。私なりに整理するとこうです。

公式ブログでも「Skills は MCP サーバーを補完するもので、外部ツールやソフトウェアを伴う複雑なワークフローを agent に教えるために使える」と説明されています。つまり競合ではなく重ね使い。

私の運用だと、たとえば「Supabase に接続する」のは MCP、「Supabase スキーマを変更する手順」は skill、「マイグレーションを本番に流す」のは権限を絞ったサブエージェント、という棲み分けにしています。料理で言えば、MCP が食材、skill がレシピ、サブエージェントが調理担当、みたいな関係です。

セキュリティ:信頼できないスキルは入れない

地味だけど重要な話。Skills は Claude にコード実行権限を与える機能なので、出所不明なものを入れるのは危険です。Anthropic も公式に「自分で作ったか、Anthropic から取得した、信頼できるソースのものだけ使え」と注意喚起しています。

GitHub で「claude skills」と検索すると有志のコレクションリポジトリがいくつも出てきますが、production 投入前には必ず SKILL.md と scripts/ の中身を目で読んでください。scripts/setup.sh がこっそり curl で何かを落としてくる、みたいなパターンは普通にあり得ます。

また、Custom Skills は Pro・Max・Team・Enterprise プランで code execution が有効なときに使えますが、ユーザー個人に紐づく仕様で、組織全体で一括管理する仕組みは別途用意されている、という点も押さえておきましょう。

まとめ:今日からやる4つのアクション

長くなったので、今日のうちに手を動かせる手順だけ残します。

  1. 既存プロジェクトで .claude/skills/ を作る ── まず空ディレクトリでいい。claude plugin init my-first-skill で雛形を生成
  2. CLAUDE.md に書いてある定型指示を1つ skill に切り出す ── コミット規約、テスト方針、デプロイ手順あたりが最初の候補
  3. description に「いつ使うか」「いつ使わないか」を1文ずつ書く ── 誤発火を防ぐ最重要ポイント
  4. 1週間運用したら Gotchas セクションを追記する ── Claude が間違えた瞬間が、最高の教材です

スキルは一度書いて終わりではなく、育てていくものです。私自身、ブログ用の skill は2週間で3回書き直しました。でも書き直すたびに Claude の振る舞いが安定していくのが体感できるので、面倒というよりは投資感覚に近い。

次に Claude Code を開いたら、まずは小さな skill を1つ。そこから始めてみてください。

参考リンク

この記事をシェア:
X で共有 Facebook で共有 Telegram で共有
次の記事
Perplexity vs ChatGPT 2026:リサーチで使い分ける7つの判断軸