2026年の Claude Code Skills：自分用の Skills ライブラリを構築する方法

Ailoot ドキュメント：API、キー、セットアップ。

Claude Code の Skill とは？なぜ「大きなプロンプト」ではないのか？#

Claude Code Skills は、Anthropic が2025年10月に Pro/Max/Team/Enterprise 向けに公開した Claude Code のネイティブ機能です。その後、Claude 以外でも使える標準として Agent Skills 仕様を公開しました。コード上では、単なるフォルダーです。

.claude/skills/
├── deploy-to-prod/
│   ├── SKILL.md
│   └── scripts/
│       └── check-migrations.sh
├── weekly-content-plan/
│   └── SKILL.md
└── triage-support-tickets/
    └── SKILL.md

各フォルダーが1つの skill です。SKILL.md ファイルは、先頭に YAML frontmatter、その下に通常の指示を記述した Markdown です。ユーザーが「本番環境にデプロイしよう」と頼むと、Claude は deploy-to-prod skill の description を確認し、「本番環境にデプロイ」というトリガーを認識して、SKILL.md の本文をコンテキストに読み込み、手順に従います。

段階的読み込みの3つのレベル

Anthropic は、必要に応じてデータを段階的に読み込む仕組みを採用しました。Anthropic Engineering のブログでは、チームがこれを「Agent Skills を柔軟かつスケーラブルにする中核的な設計原則」と説明しています（Anthropic Engineering）。

読み込みは次の3段階です。

1. メタデータ（常時） - セッション開始時、Claude が確認するのは各 skill の name と description だけです。予算：約100トークン/skill。
2. 指示（トリガー時） - ユーザーが関連することを言うと、Claude は SKILL.md の本文を読み込みます。予算：5000トークン未満。
3. リソース（要求時） - 同梱ファイル（例、テンプレート、データセット）は、モデル自身が参照したときだけ取得されます。予算：無制限。

以前は、AI に「覚えて」おいてほしいことをすべて CLAUDE.md に書く必要がありました。ルールが50個あるプロジェクトでは、すぐにコンテキスト上限に達していました。skill なら、最初のコンテキストに入るのは description だけなので、1つのプロジェクトに数十個を無理なく置けます。

Skill の配置場所：4つのレベル

優先順位は、enterprise が personal を上書きし、personal が project を上書きします。プラグインは plugin-name:skill-name 名前空間を使うため、競合しません。一般的な専門スキルは ~/.claude/skills/ に、プロジェクト固有のものはリポジトリの .claude/skills/ に置くと便利です。

SKILL.md の中身は？#

最小限の例を示します。20行で skill の完成です。

---
name: weekly-content-plan
description: Prepares a weekly post plan for a Telegram channel and short-form video platforms. Triggers - "make a post plan", "what should I post this week", "a 7-day channel plan". Do not activate if the request is about a website or email newsletter.
---

# Weekly Content Plan

## Steps

1. Read `knowledge/audience.md` - who we're writing for
2. Read `knowledge/tone-of-voice.md` - how we write
3. Read the last 10 posts in the channel - what has already been covered
4. Come up with 7 topics for the week: 3 sales-focused, 2 expert, 2 personal
5. For each, provide one hook line and three bullets about the post
6. Output as a table: day of the week | type | hook | plan

これで十分です。ユーザーが「今週の投稿を計画しよう」と入力すると、Claude は description にあるトリガーを確認し、SKILL.md を読み込み、指定されたファイルを読み、表を出力します。

覚えておきたい制限

Claude の公式 API ドキュメントには、厳格な制限が定められています。

• name：最大64文字。小文字、数字、ハイフンのみで、XML タグは不可。anthropic と claude は予約語です。
• description：API では最大1024文字。必須で、XML タグは不可。
• 一覧表示の予算：Claude Code では、すべての skill の description を合わせると、コンテキストウィンドウの約1%を使います。skill が多いと description は切り詰められ、Claude が照合に必要とするキーワードが消える場合があります。
• SKILL.md の本文：Anthropic は本文を500行以内にすることを推奨しています。それより長い内容は references/、scripts/、examples/ の各ファイルに移し、指示から読み込むようにします。

コンテキスト圧縮（/compact）後、Claude は以前に呼び出した各 skill の先頭5000トークンを保持します。再付与されるすべての skill の合計予算は25 000トークンです。skill が収まらなければ、その振る舞いは「忘れられます」。

Frontmatter の全スキーマ

最低限、name と description を使います。本番環境向けの skill では、ほかのフィールドも使います。

disable-model-invocation: true フィールドは、自動実行してはならないものに必須です。たとえば、このフラグを付けた deploy-to-prod skill は、ユーザーが明示的に /deploy-to-prod と入力した場合にだけ呼び出せます。このフラグがなければ、「コードの準備ができているように見える」という理由で Claude がデプロイする可能性があります。

Description が作業の90%を占めるのはなぜ？どう書けばよい？#

vibe-coder に最もよくある間違いは、「X 用ヘルパー」のような description を書くことです。skill はフォルダー内に確かに存在するのに、Claude が呼び出しません。

悪い Description

description: Build dashboards.

Claude に判断できないことは何でしょうか。ユーザーが「今週の売上を見せて」と言ったとき、それはダッシュボードのことなのか。ユーザーが「売上チャート」と言ったとき、それはダッシュボードなのか、それとも一般的なチャートなのか。ユーザーが「月次レポート」と言ったとき、それは間違いなくダッシュボードではないのか。

Anthropic の独自の skill-creatorには、推奨事項が明記されています。

良い Description の公式

要素は3つです。

1. 何をするか - 手順ではなく、結果を1文で説明します。「SQL を生成する」ではなく、「売上を Telegram チャンネル用の表に出力する」と書きます。
2. いつ呼び出すか - ユーザーが実際に使う3～5個の表現を引用符で囲みます。推測せず、自分のチャットやサポート履歴を確認します。
3. いつ呼び出さないか - skill が応答すべきではない類似タスクを1～2個挙げます。この節がないと、似た2つの skill が競合し続けます。

私のプロジェクトで使っている、強い description の例を示します（簡略化して匿名化済み）。

description: |
  Writes and publishes an SEO guide to the blog, following the editorial policy.
  Triggers: "write a guide about X", "let's make a new pillar",
  "a blog article about Y", "build a blog guide about Z".
  Do not activate if the request is about an email newsletter,
  a Telegram post, or an internal team instruction—
  those are other skills.

ここで効果を発揮している点は次のとおりです。

• 「helps with」ではなく「writes and publishes」という動詞を使い、具体的な成果を示しています。
• 引用符で囲んだ4つのトリガー表現が、異なる言い回しをカバーします。
• 英語のトリガーも含まれています。ユーザーがチームの言語を切り替えても、skill が機能します。
• 独立した「do not activate if」の節が、メールと投稿の skill との競合を防ぎます。

Description のテスト方法

Anthropic は skill-creator に trigger-evals 方式を組み込み、skill が有効になるかを調べる20個のプロンプトを用意しました。10個は有効になるべきもの、10個は有効にならないべきものです（表現が似ていてタスクが異なる、紛らわしいケースも含みます）。

vibe-coder 向けに言い換えると、description を書いたら、新しいチャットを開いて、実際によく使う5つの表現と、似ているが別の意味の3つの表現を試します。本来有効になる場面で有効にならない、または有効になるべきでない場面で有効になるなら、description を修正します。指示本文を書くのはその後です。

最初にインストールする5つの Skill は？#

最初の2週間を自作 skill の作成に費やすのは得策ではありません。まず既成のものをインストールして作り方を確認し、その後、同じ方法で自分の skill を追加しましょう。すべてをゼロから作るより、実績のあるコレクションを取り入れてカスタマイズするほうが低コストです。最初に試したい5つのコレクションを紹介します。

1. anthropics/skills - skill-creator を含む公式コレクション

リポジトリ：github.com/anthropics/skills。GitHub stars は138,000。Anthropic チームによる公式 skill が含まれています。skill-creator（ほかの skill を作るメタスキル）、claude-api（API 統合の構築を支援）、PowerPoint、Excel、Word、PDF 用の既成ドキュメント skill などです。

Claude Code へのインストール方法：

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

最大の価値は skill-creator です。説明に基づいて SKILL.md を作成し、20個の trigger-evals を実行します。そして、skill が適切な場面で有効になるまで description を修正します。要するに、「skill を作るための skill」です。

2. mattpocock/skills - TypeScript エキスパートによる話題のコレクション

現在、12個の skill が含まれています。たとえば次のとおりです。

インストール：

npx skills@latest add mattpocock/skills
/setup-matt-pocock-skills

3. coreyhaines31/marketingskills - マーケター向けコレクション

オンライン講座を運営している、フリーランスのマーケターとして働いている、または代理店を経営しているなら、自分の skill を書くのに半年かける必要はありません。作業の半分はすでにパッケージ化されています。

4. vercel-labs/agent-skills - AI らしく見えないデザイン

リポジトリ：github.com/vercel-labs/agent-skills。主力の skill は web-design-guidelines で、週あたり約133,000回インストールされています。100を超えるアクセシビリティ、パフォーマンス、使いやすさのルールに照らして UI コードを監査します。

これに加えて、Anthropic の frontend-design があり、週あたり110,000回以上インストールされています。コードを書き始める前に、AI にスタイルを選ばせます。これがないと、Claude が生成するページはどれも Inter フォント、紫のグラデーション、グリッドカードになります。誰が作っても同じ結果です。

5. obra/superpowers - マルチエージェントのワークフロー

総じて、最初の3つ、つまり anthropics/skills、mattpocock/skills、coreyhaines31/marketingskills をインストールすれば、Claude Code には起業家の最初の1か月の作業の大半をカバーする、すぐ使える skill が数十個揃います。

どのような反復作業を Skill にすべき？#

クライアントワークや他人のプロジェクトで、私はこのパターンを何十回も見てきました。「毎回ゼロからやる作業」がある人です。毎週月曜日、同じ種類のレポートを書く。新しいクライアントが加わるたび、同じ手順を進める。すべての投稿が同じテンプレートに従う。それでも、手順を思い出し、適切なファイルを開き、Claude 用プロンプトをまた作る必要があるため、毎回30～90分かかります。

解決策は、作業を一度 skill にまとめることです。その後は、ひと言伝えるだけで Claude が方法論を読み込み、必要な情報源を確認し、結果を作成します。異なる分野から3つの例を紹介します。

例1. フリーランスのマーケター - weekly-content-plan Skill

手作業で行っていること：毎週月曜日、3人のクライアント向けに1週間分の Telegram 投稿を準備します。クライアントのブランドボイスガイドを開き、最近の投稿を確認し、商品カレンダーをもとにトピックを考えて、フックと箇条書きを含む表を作成します。

skill にすると、5段階の指示になります。クライアントの tone-of-voice ファイルを読み、商品カレンダーを確認し、直近10件の投稿を見て重複を避け、種類別（販売重視、専門的、個人的）に7つのトピックを考え、表を出力します。

「今週のクライアントXの投稿を計画しよう」というコマンドで、1時間の準備が3分の待ち時間になります。マーケターは結果を確認し、必要な箇所を編集してクライアントに送ります。

例2. 外部委託の会計士 - monthly-receipts-close Skill（筆者の例）

手作業で行っていること：ポートフォリオ内の各クライアントについて、毎月銀行明細をエクスポートし、会計システムの支払いと照合し、分類されていない支払いに印を付け、暫定的な収入レポートを作成し、収入の内訳を前月と比較します。

この skill は6段階の指示と、銀行明細を解析するための scripts/ フォルダー内のシェルスクリプト数本で構成されます。「クライアントXの5月分を締めて」というトリガーで、Claude は異常に印を付けたレポートを4～5分で作成します。

例3. オンラインプログラムの運営者 - welcome-letter-new-participant Skill

手作業で行っていること：新しい参加者が支払いを済ませたら、ウェルカムメールを書く必要があります。良いウェルカムメールは個別対応です。どのチャネル経由で来たか、どの商品を購入したか、どのコホートに所属するか、どの資料を一緒に送るかを考慮します。「こんにちは、ようこそ」というテンプレートでは対応できません。

この skill は Claude に、knowledge/audience.md（どのような人たちか）、knowledge/products/<product>.md（何を受け取るか）、直近3通のウェルカムメール（重複を避けるため）を読み、この構成でメールを書くよう指示します。フック - 商品の詳細 - 最初の3つのステップ - 結び。

手作業より何倍も速くなります。人は急いでいると3つの情報源のうち1つを飛ばすことがありますが、Claude は必ず確認するため、品質の一貫性も高まります。

Skill にすべきでないもの

• 一度きりの作業。確定申告のときに年1回だけ行うなら、チャットで Claude に説明すれば十分です。skill の効果が出るのは3回以上繰り返してからです。
• 範囲が広すぎる作業。「マーケティングを手伝って」は skill ではなく、マーケティング全般です。skill にするなら「毎週のコンテンツ計画」のように、具体的な結果につながる行動にします。
• 繰り返せる手順がない作業。毎回プロセスが異なるなら、skill ではなく単発の作業です。

Skill Creator はどうやって Skill を作成する？#

良い skill を最初から書くのは難しいものです。description が狭すぎたり広すぎたり、実際に使われる表現を見落としたり、近くにある別の skill と競合したりしがちです。Anthropic はこの問題に対応するため、ほかの skill を作成できるメタスキル skill-creator を公開しました。

anthropics/skills をインストールしたら、Claude に /skill-creator と伝える（または「週次レポート用の skill を作ろう」と頼む）ことで、次の6段階の流れを進められます。

1. 下書き - skill-creator が、skill に何をさせるか、どのトリガー表現を使うか、どの情報源を読むか、どの手順に従うかを質問します。最初の SKILL.md ができます。
2. テスト - skill-creator が20個のテストプロンプトを生成します。skill が有効になるべきプロンプトが10個、有効になるべきではないがトリガーに似ているプロンプトが10個です（ニアミス）。
3. 評価 - 新しいチャットで各プロンプトを実行し、skill が有効になったか確認します。有効になるべきでない場面で有効になる、または有効になるべき場面で有効にならない場合は、結果に印を付けます。
4. 反復 - 失敗に基づいて description を書き直し、もう一度テストします。
5. 最適化 - 最終調整として、1024文字の上限を超えていないか、既存のプロジェクト skill と競合していないか確認します。
6. パッケージ化 - 最終版の SKILL.md と参照ファイルを、適切な構造にまとめます。

実際には、Claude と15～20分話し、確認の質問に7～8個答えると、適切なトリガーで有効になる、テスト済みの skill が完成します。

もう1つの利点は、skill-creator が SKILL.md の模範的な書き方を示してくれることです。自身のファイルを開けば、手順の形式、トーン、構成を確認できます。ツール自身が使い方を示す例です。ファイルを読めば、自分の skill の書き方がわかります。

Skills、CLAUDE.md、Subagents、MCP、Hooks：何を使うべき？#

私がレビューしたプロジェクトで最もよく見かけた問題は、CLAUDE.md にプロジェクトのルール、公開手順、コミットテンプレート、データベースの説明を一緒に書いていることです。コンテキストを圧迫するうえ、実際の動作にも支障が出ます。「ユーザーが公開を頼んだときに実行する」という指示を Claude は実行しません。モデルは CLAUDE.md の内容を、明示的なトリガーのない一般的なコンテキストとして扱うためです。

解決策は、項目ごとに適切な基本機能を割り当てることです。

シンプルに整理すると、Skills と MCP でほとんどのワークフローをカバーし、Hooks はコードチェック、テスト、ガードレールなどの定型作業を自動化します。コンテキストが重いときに Subagents が必要です。よくある間違いは、skill を使うべき場面で subagent を作ることです。

判断のフローチャート

「Claude に X をさせたい」と思ったとき：

1. この知識は常に必要か？ たとえば「プロジェクトで使う言語は決まっている」「em dash は使わない」など。→ CLAUDE.md に書きます。
2. 手作業で行っている、トリガーで始まる手順か？ たとえば「毎週月曜日にレポートを書く」など。→ skill にします。
3. 外部システムにアクセスする必要があるか？ たとえば Stripe API や CRM など。→ MCP server に接続します。
4. Claude Code にイベントへの自動応答をさせたいか？ たとえば Edit の後に毎回 linter を実行するなど。→ hook を作成します。
5. 作業が重く、コンテキストを使い切りそうで、並行して別のことを行う必要があるか？ → subagent で実行します。

起業家や vibe-coder の作業の90%は、カテゴリ1～3に入ります。Hooks と subagents は、「一度に1つの作業」という段階を超えたときに使う次の段階のツールです。

Slash Commands と Skills は同じもの

Claude Code の重要な変更点として、旧 slash-command システム（.claude/commands/）と skills は実質的に統合されています。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md は、どちらも /deploy コマンドを作成します。名前が一致する場合は skill が優先されます。まだ旧 slash-command 形式を使っているなら、skills に移行しましょう。構文がより明確で、機能も豊富です。

Skill が機能しなくなる7つの間違い#

1. トリガーのない Description：Skill が有効にならない

症状：skill を書き、構造を確認し、すべて有効なのに、Claude がユーザーの依頼に対して呼び出さない。原因はたいてい同じです。「コンテンツ作成用ヘルパー」のような description です。Claude はどの表現に応答すべきかわかりません。修正方法：実際にユーザーが使う3～5個の表現を引用符に入れ、description に直接書きます。

2. 500行を超える SKILL.md：注意が散漫になる

Anthropic は明確に推奨しています。ファイルの本文を500行以内に収めてください。指示が2000行もあると、Claude は集中力を失い、手順を部分的にしか守らず、順序も混乱します。修正方法：長い節を近くのファイル、たとえば examples/、references/、scripts/ に移し、SKILL.md から参照します。

3. コンテンツ全般向けの1つの Skill ではなく、小さな3つの Skill を作る

魅力的に見える構成は、Telegram 投稿、ランディングページ、メールを1つにまとめた大きな content skill です。しかし、うまくいきません。依頼と合わない場面で有効になり、方法論が混ざり、平均的な結果を出します。修正方法：1つの skill に、1つの反復可能な行動を割り当てます。「コンテンツ」に関するルーティンが3つあるなら、telegram-post、landing-section、email-broadcast の3つの skill を作ります。

4. 「使ってはいけない場面」のない Skill：競合が起きる

症状：プロジェクト内に似た skill が2つあり、Claude が間違った方を呼び出します。たとえば、一方はメールニュースレター向け、もう一方はプログラム参加者へのウェルカムメール専用です。「一般的なメーリングリストについての依頼では有効にしない」という明示的な条項がないと、ウェルカムメール用 skill は「メール」という言葉が出るたびに有効になります。修正方法：description に該当しないケースを明記します。

5. プロジェクト内に Skill が50個：Description が切り詰められる

Claude Code ドキュメントより：

マーケットプレイスから50個の skill コレクションをダウンロードすると、一部の description が切り詰められます。頼りにしていたキーワードが消えるかもしれません。修正方法：アクティブなプロジェクトでは、特に役立つ10～15個の skill を使います。残りは、検出対象のskillsディレクトリの外にある非アクティブな保管先へ置きます。たとえば自分の資料内の別フォルダーskill-archive/です。必要なスキルだけをプロジェクトか個人のスコープへ導入してください。~/.claude/skills/は全プロジェクトから見えるインストール済みの個人ライブラリで、移しても検出対象から外れません。

6. 未検証の提供元からの Skill：セキュリティリスク

Anthropic は公式ドキュメントで警告しています。

無作為な GitHub リポジトリには、最初に呼び出したときに API キーを漏えいさせる skill が含まれているかもしれません。修正方法：インストール前に SKILL.md を開き、自分で読みます。重要なプロジェクトでは、見知らぬ作者の skill を実行しないでください。

7. Knowledge フォルダーがない Skill は「平均的な ChatGPT」の結果を出す

最も見えにくく、よくあるアンチパターンです。skill は方法論ですが、コンテキストがなければ方法論だけでは意味がありません。「ウェルカムメールを書く」skill を作っても、プロジェクトに対象読者を説明するファイルやブランドボイスのファイルがなければ、Claude は誰が書いても同じような、平均的な ChatGPT のメールを作成します。

skill が最もよく機能するのは、CLAUDE.md のガイドの原則に従って、プロジェクトの Second Brain をすでに構築している場合です。まず知識構造を作り、それを利用する skill を作成します。順番を逆にすると、あなたのスタイルに合った仕事ではなく、定型的で平均的な品質の結果になります。

最初の Skill を30分で作る方法#

私が自分のプロジェクトで最初の skill を作ったときの具体的な計画を紹介します。

ステップ1. 反復作業を1つ選ぶ

過去1か月分のカレンダーを開きます。少なくとも4～5回行い、毎回30～60分かかる作業を探します。「マーケティング」のような広い作業ではなく、「月曜日の売上レポート」「新しいクライアントのオンボーディング」「キャンペーン用価格表の更新」など、具体的な作業を選びます。

表現が具体的なほど、skill は簡単になり、トリガーも明確になります。

ステップ2. 手順を自分で書き出す

別のファイル、または Claude とのチャット（skill 用ではなく、下書き用）に、普段の手順を書き出します。

1. Open the client database
2. Filter by status "awaiting welcome email"
3. Check which channel the client came from
4. Get the email template for that channel from the "templates" folder
5. Fill in the name, product, and start date
6. Send

これはまだ skill ではなく、メモです。しかし、メモがなければ SKILL.md を書き始めた時点で混乱します。

ステップ3. フォルダー構造を作る

mkdir -p .claude/skills/welcome-email-new-client
touch .claude/skills/welcome-email-new-client/SKILL.md

すべてのプロジェクトで skill を使いたい場合は、~/.claude/skills/ に置きます。

ステップ4. テンプレートを使って SKILL.md を書く

ひな型：

---
name: welcome-email-new-client
description: |
  Prepares a welcome email for a new client using the template for their acquisition channel.
  Triggers: "write a welcome email for new client X",
  "onboard new participant Y", "welcome email for client from channel Z".
  Do not activate if the request is about a general mailing list
  or an email campaign—those are other skills.
---

# Welcome Email for a New Client

## Steps

1. Read `knowledge/audience/segments.md` - what client segments we have
2. Read `knowledge/templates/welcome/` - templates by channel
3. Identify the client's channel from the request context
4. Insert the client's name, product name, and start date
5. Check the length—it should be no more than 800 characters
6. Output the final email text in a copy-ready format

## Important

- Do not use “dear friend” or “hello”—use natural speech
- One paragraph, one idea
- End with one call to action, not two

ステップ5. 5～8個のプロンプトでテストする

このプロジェクトで Claude Code の新しいチャットを開きます。実際に使う5つの表現と、skill が有効になるべきでない似た表現を3つ試します。

有効になるべきもの：

• “Write a welcome email for new client Ivanov”
• “Onboard a new participant who bought program X”
• “Welcome email for a client from Instagram”

有効になるべきでないもの：

• “Send a promotion email to the whole list”
• “Email campaign for the New Year holidays”
• “Write a follow-up to a client who hasn't paid”

それぞれについて、skill が有効になったか確認します。誤ったケースで有効になるなら description を絞ります。有効になるべき場面で有効にならないなら、トリガー表現を広げます。

ステップ6. Description を反復する

各テストに失敗したら、指示本文には触れず、description だけを編集します。2～3回反復すると、skill は安定して有効になります。保存してコミットし、毎日使いましょう。

最後に、最初の skill を完璧にしようとしないでください。まず動くものを作ります。磨き込みは5つ目や10個目の skill の後でかまいません。表現のパターンや Claude の応答に共通点が見えてくるからです。

今週のカレンダーから、繰り返し行っている作業を1つ選び、30分を確保して上記6つの手順に取り組みましょう。そうすれば、Claude は推測するのではなく、あなたの方法論に沿って作業します。

Ailoot 経由で AI モデルを使う必要がある場合は、Ailootをご覧ください。