Claude Code Skillsの作り方｜実践で50個作った設計パターンと注意点【2026年版】

この記事の著者

株式会社Nexa 代表取締役川島 陸

一橋大学経済学部卒業後、フォーティエンスコンサルティング株式会社（旧 株式会社クニエ）にて法人向けAI導入支援等を経験。独立後、AI系メディア運営やDify/n8nの導入支援を経て、株式会社Nexaを創業。法人向けAI研修・AI導入支援・AI関連メディア運営を手掛ける。

詳しく見る無料相談をする

Claude Code Skillsを使えば、「毎回同じプロンプトを打ち込む手間」をゼロにできます。SKILL.mdというテキストファイルに手順を書くだけで、プログラミング不要でカスタムスキルが完成します。

「スキルを作りたいが、何から始めればいいかわからない」——多くの方がこの段階で立ち止まります。

この記事では、あるメディア運営で50個以上のカスタムスキルを実際に構築した経験をもとに、SKILL.mdの設計パターン・Keychainを使った認証管理・サブスキル化の構成例まで、実践的に解説します。（Claude Code Skills の基礎からおさらいしたい方はこちら →）

Claude Code Skillsとは何か — 「繰り返し指示ゼロ」を実現する仕組み

Claude Code Skillsとは、Claude Codeに「カスタム機能」を追加できる拡張の仕組みです。Anthropic社が提供するこのAIコーディングツール（ターミナル上で対話しながらコードの生成・修正・実行を行えるCLIツール）に、独自の作業手順を「スキル」として登録しておくと、次回からは短い一言で同じ作業を再現できます。

スキルがない場合との違い

スキルを使わない場合、毎回同じ指示をゼロから打ち込む必要があります。

たとえば「Googleスプレッドシートのデータを取得して整形する」作業を毎週行うなら、毎回「GSheets APIで…認証は…対象のシートID…」と詳細を伝え直す必要があります。スキルとして登録すれば、「スプレッドシートを取得して」の一言だけで同じ処理が走ります。

スキルが特に役立つ場面

Anthropicの公式仕様によると、スキルはシステムプロンプトに1件あたり約100トークンが注入されます。スキル本文（SKILL.md）は5,000トークン以内に収めることが推奨されており、このサイズに収まるよう設計することで応答速度と精度が最適化されます。

SKILL.mdの基本構造 — frontmatter + 本文の書き方

SKILL.mdは大きく2つのパートで構成されます。

frontmatterのname/description/metadataの書き方

ファイルの先頭に---で囲まれたYAML frontmatterを記述します。

---name: my-skilldescription: Googleスプレッドシートのデータを取得・整形するスキル。「スプレッドシートを取得して」「Sheets APIで読み込んで」などのリクエストでトリガー。metadata:  version: 1.0.0---

descriptionがトリガー判定のカギになる理由

Claudeはスキルを呼び出す際、まずfrontmatterのnameとdescriptionだけを読み込みます（本文はまだ読まれません）。この段階でスキルを使うかどうかを判断するため、descriptionの書き方が「スキルが発動するかどうか」を決定します。

Anthropicの公式ベストプラクティスには次のように書かれています。「スキルが呼び出されない場合は、まずdescriptionを見直せ。Claudeが自然に依頼するときの言葉でdescriptionを書くこと」

実際に、あるメディア運営の事例でもX APIスキルを構築した際、最初はトリガーされず、descriptionに「X APIを使って競合アカウントを調査したいとき」という具体的な言い回しを追加したところ正しく動作するようになりました。

descriptionに含めるべき情報:

1. スキルが何をするか（三人称で記述）
2. いつ使うか（ユーザーが自然に口にするフレーズ）
3. トリガーになるキーワード例（「〜などのリクエストでトリガー」という形式が効果的）

本文（Markdown）に書く内容

frontmatterの後、---以降の通常のMarkdown部分が「Claudeが実行時に読む手順書」になります。

# スキル名## 入力情報- **取得対象のスプレッドシートID**（必須）- **シート名**（省略可、省略時はSheet1）## 手順1. gws コマンドでデータ取得2. JSON形式で整形3. 指定フォーマットで出力## 出力フォーマット| 列1 | 列2 | 列3 ||-----|-----|-----|

ポイントは「手順を箇条書きで明確に」「入力と出力フォーマットを明示する」の2点です。曖昧な表現（「適切に処理する」など）は避け、具体的な手順を記述します。

ディレクトリ構成 — SKILL.md / scripts / references の役割分担

スキルフォルダの典型的な構成は次の通りです。

my-skill/├── SKILL.md          # 必須：手順書（メイン）├── scripts/          # 任意：実行スクリプト（Python, shell等）│   └── process.py└── references/       # 任意：詳細リファレンス    ├── config.md    └── examples.md

シンプルスキル（SKILL.mdだけで完結するケース）

単機能で内容が少ない場合は、SKILL.mdだけで完結させます。前述のcron一覧表示スキルがこれに当たります。作成した事例では、~/.openclaw/cron/jobs.jsonを読んでジョブ一覧を表示するだけのシンプルなスキルをSKILL.md1ファイルで完成させ、数分で動作確認まで完了しました。

スクリプト連携型（scripts/フォルダにスクリプトを配置）

APIアクセスやデータ処理など、Pythonスクリプトが必要な場合はscripts/フォルダに格納します。

ある事例では、X（Twitter）APIを操作するスキルを構築しました。認証・検索・投稿の機能を持つ共通クライアント x_api.py を scripts/ に置き、複数のサブスキル（research/post/analytics/timeline）から呼び出す構成にしました。

x-skills/├── context.md             # 共通設定（認証情報の参照先、エンドポイント一覧）├── scripts/│   └── x_api.py           # 共通APIクライアント├── research/│   └── SKILL.md           # アカウント調査・ツイート検索├── post/│   └── SKILL.md           # ツイート投稿├── analytics/│   └── SKILL.md           # エンゲージメント分析└── timeline/    └── SKILL.md           # タイムライン取得

リファレンス分離型（references/フォルダで肥大化を防ぐ）

SKILL.mdが長くなりすぎると（5,000トークンを超えると）、Claude の処理精度が低下します。詳細なオプション一覧・コマンドリファレンス・設定値の説明などは references/ フォルダに分離し、SKILL.mdからは「詳細は references/config.md を参照」とだけ書くのが効果的です。

ある企業のSEO自動化スキルでは、この分離により SKILL.md のトークン数を当初の9割以上から大幅に削減することができました。

認証管理のベストプラクティス — APIキーはKeychainで管理する

セキュリティリスク — SKILL.mdにAPIキーを書いてはいけない理由

SKILL.mdはプレーンテキストファイルです。APIキーをSKILL.mdに直書きすると、以下のリスクが生じます。

• Gitにコミットした場合、履歴に残り漏洩する
• 共有・バックアップ時に誰でも閲覧可能
• スキルをチームに展開した際に全員がキーを共有することになる

Anthropic公式も「認証情報はスキルのコンテンツから分離すること」を明記しています。

macOS Keychainへの登録方法

macOS標準のsecurityコマンドを使って、APIキーをKeychainに安全に保存します。

# APIキーをKeychainに登録security add-generic-password \  -a "$USER" \  -s "MY_API_KEY" \  -w "sk-xxxxxxxxxx"

スクリプト内からKeychainを読み込む方法

Pythonスクリプトからは以下の方法で取得します。

import subprocessimport getpassdef get_api_key(service_name: str) -> str:    result = subprocess.run(        ["security", "find-generic-password",         "-a", getpass.getuser(),         "-s", service_name,         "-w"],        capture_output=True, text=True    )    return result.stdout.strip()# 使用例api_key = get_api_key("MY_API_KEY")

ある事例では、X APIスキルを構築する際にOAuth 2.0 PKCEの認証フローを実装し、Bearer Token（X_BEARER_TOKEN）とクライアントID（X_CLIENT_ID）をそれぞれKeychainに登録しました。スクリプトは起動時にKeychainから自動取得するため、SKILL.md本文にはキーの値が一切含まれない設計になっています。

Claude Codeの導入や活用方法について、個別にご相談いただけます。「どの機能から使えばいいか」「自社業務への適用方法を知りたい」といった段階から対応しています。

Claude Code個別指導の無料相談はこちら →

サブスキル設計パターン — 大規模ワークフローを効率よく管理する

10以上の関連スキルを管理する場合は、「傘型（サブスキル群）設計」が効果的です。

単機能スキル vs サブスキル群の使い分け

context.mdで情報共有する傘型設計

あるメディア運営では、SEO記事の制作フローをKW選定から公開まで10のサブスキルに分解しました。

seo-workflow/├── context.md          # 全サブスキル共通：サイト情報・文体ルール・CTA設定├── keyword-planning/│   └── SKILL.md├── research/│   └── SKILL.md├── outline/│   └── SKILL.md├── writing/│   └── SKILL.md├── review/│   └── SKILL.md...（以下10スキル）

context.mdには全スキルで共通して参照する情報（サイトURL、文体ルール、出力フォルダパスなど）をまとめます。各サブスキルの SKILL.md には「ワークフロー内では context.md を再読み込み不要」と明記することで、トークンの無駄を防ぎます。

スキル間のデータ受け渡し

サブスキルはファイルシステム経由でデータを受け渡します。前のスキルが出力ファイルを保存し、次のスキルがそのファイルを読み込む設計です。

記事/[KW名]/├── リサーチ.md   ← research スキルが作成├── 構成案.md     ← outline スキルが作成├── 記事.md       ← writing スキルが作成└── レビュー.md   ← review スキルが作成

このパターンにより、途中で失敗してもファイルが残るため再実行が容易になります。

skill-creatorで効率よくスキルを量産する

skill-creatorとは — スキルを作るスキル

skill-creator はAnthropic公式が提供する「スキル作成専用スキル」です。Claude Codeに「このスキルを作りたい」と伝えると、要件整理→SKILL.mdドラフト生成→ディレクトリ構成の提案→CLAUDE.mdへの登録まで一連の作業を代行してくれます。

活用フロー

ある事例では、X APIスキルをskill-creatorを使って構築しました。プロセスは次の通りです。

1. 要件を伝える: 「X APIで競合アカウントをリサーチしたり、ツイートを投稿したりするスキルを作りたい」
2. 既存スキルの確認: skill-creatorが類似の既存スキルを参照し、構造パターンを提案
3. ドラフト生成: context.md・scripts/x_api.py・各サブスキルのSKILL.mdを自動生成
4. テスト実行: APIキーを登録後、実際に動かして確認
5. CLAUDE.mdへの登録: トリガーワードと合わせて登録

skill-creatorを使うことで、スキル1個あたりの構築時間が手動の約1/3程度に短縮できます。ポイントは「既存スキルを参照させること」です。類似構造のスキルがあれば、そのパターンを踏襲した高品質なドラフトが生成されます。

イテレーションのコツ

最初のドラフトで完璧を目指さず、まず動かしてからチューニングするアプローチが効率的です。特に description は実際に使いながら「どう言ったらトリガーされるか」を確認しつつ調整します。

よくある問題と解決策

Q. スキルがトリガーされないときはどうすれば？

原因の大半はdescriptionの表現が自然でないことです。

解決手順:1. 自分が実際に使うときに口にするフレーズを書き出す2. そのフレーズを description のトリガー例として追加する（「〜などのリクエストでトリガー」）3. CLAUDE.mdに登録されているか確認する

Q. SKILL.mdが長くなりすぎた場合は？

5,000トークン（目安として日本語で約3,000〜4,000文字程度）を超えたら分離を検討します。- コマンドリファレンスや詳細な設定値 → references/ フォルダへ移動- 実行ロジック → scripts/ フォルダへPythonスクリプトとして分離

Q. 複数のスキルが同時にトリガーされてしまう場合は？

各スキルのdescriptionを見直し、トリガーワードが他のスキルと重複しないようにします。また、スキルを傘型設計にまとめることで管理がしやすくなります。

Q. スクリプトが動かない（venv・パス問題）

Pythonスクリプトを使う場合は、仮想環境（venv）のパスとスクリプトの実行パスをSKILL.mdに明示的に記述します。

## 実行方法```bashsource /tmp/my-skill-venv/bin/activate && \python3 ~/.claude/skills/my-skill/scripts/process.py

venvが存在しない場合は先に作成してください:`python3 -m venv /tmp/my-skill-venv && /tmp/my-skill-venv/bin/pip install requests““

まとめ

Claude Code Skillsは、繰り返し業務の指示を一度だけ書いておけば以降は自動化できる強力な仕組みです。

設計のポイントをまとめると:

• SKILL.mdの構成: frontmatterのdescriptionがトリガー判定のカギ。本文は5,000トークン以内を目標に
• ディレクトリ設計: シンプル→スクリプト連携型→リファレンス分離型と、規模に応じて構成を変える
• 認証管理: APIキーはKeychainで管理し、SKILL.mdには直書きしない
• サブスキル設計: 10以上のスキルは傘型設計＋context.mdでまとめる
• skill-creator活用: 既存スキルを参照させながら高速ドラフト生成

最初の1つはシンプルなものから始め、動作確認後に機能を拡張していくアプローチが最も効率的です。まずは日常業務の中で「毎回同じプロンプトを打っている作業」を1つ選んで、スキル化してみてください。

Claude Codeの導入・活用をサポートします

株式会社Nexaでは、Claude Codeを活用した業務自動化の個別指導・企業研修を提供しています。「スキルの設計方法を一緒に考えてほしい」「自社業務に合ったカスタマイズを知りたい」といった段階からご支援いたします。詳しい設定方法やカスタマイズについては無料相談でお伝えしています。

Claude Code個別指導の詳細・無料相談はこちら →