Claude Code Skillsがトリガーされないときはどうすれば？

原因の大半はdescriptionの表現が自然でないことです。自分が実際に使うときに口にするフレーズをdescriptionのトリガー例として追加し、CLAUDE.mdに登録されているかも確認します。

スクリプトが動かない（venv・パス問題）ときはどうすれば？

Pythonスクリプトを使う場合は、仮想環境（venv）のパスとスクリプトの実行パスをSKILL.mdに明示的に記述します。venvが存在しない場合は先に作成してから実行します。

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

2026年3月28日

このトピックの全体像Claude Code 完全ガイド｜料金・使い方・法人導入の全体像機能・設定の記事

公開日: 2026年3月28日最終更新: 2026年10月2日

執筆・編集：株式会社Nexa 編集部（下書きと機械検査はAI、公開前に人が確認）／約14分で読めます。公式ドキュメント・公式発表などの一次情報を確認したうえで執筆・更新しています。AIツールの仕様や料金は変わることがあるため、導入判断の前に各公式サイトの最新情報もご確認ください。記事の作り方と検査の方針

Claude Code Skillsは、SKILL.mdに手順を書くだけで繰り返し業務を自動化できる仕組みで、プログラミング不要で5分で作成可能です。

要点1: SKILL.mdはfrontmatter（name/description）+ 本文（手順）の2部構成。descriptionがトリガー判定のカギ
要点2: APIキー等の認証情報はSKILL.mdに直書きせず、macOS Keychainで安全管理するのが原則
要点3: 10以上の関連スキルは「サブスキル群＋共通context.md」の傘型設計でまとめると管理が楽になる

対象: Claude Codeを使い始めて、カスタムスキルを作りたい経営者・DX推進担当者・個人開発者

今日やること: まず単機能スキルを1つ作り、CLAUDE.mdにトリガーワードを登録する

この記事の著者

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

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

詳しく見る AI顧問の無料相談

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

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

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

本記事の仕組み・仕様に関する記述は、Anthropic公式ドキュメント「Agent Skills」および「Skill authoring best practices」を2026年10月2日時点で確認し、内容を反映しています。

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

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

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

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

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

スキルが特に役立つ場面

用途	具体例
SEO・コンテンツ制作	KW選定→記事執筆→WP公開のフロー自動化
Google Workspace連携	Gmail検索・カレンダー取得・Driveアップロード
SNS運用	ツイート生成→下書き投稿の自動化
データ分析	GA4・GSCのデータ取得・レポート生成
APIツール連携	Slack通知・X API操作・外部サービス呼び出し

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

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

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

frontmatterのname/description/metadataの書き方

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

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

フィールド	役割
name	スキルの識別名（英数字・ハイフン）
description	Claude がスキルをいつ使うかを判断する材料。最重要フィールド
metadata	バージョンなどの補足情報（任意）

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

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

Anthropic公式のベストプラクティスでも、descriptionは三人称で、「何をするスキルか」と「いつ使うか」の両方が分かるように具体的に書くことが推奨されています。スキルが呼び出されない場合は、まずこのdescriptionの表現を見直すのが最初の対処です。

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

descriptionに含めるべき情報:

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

本文（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自動化スキルでも、詳細なコマンドリファレンスをreferences/へ分離したことで、SKILL.md本文のサイズを大きく圧縮できました。

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

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

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

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

APIキーやシークレットをスキル内にハードコードせず、環境変数など実行時に注入する方式を使うのがセキュリティ上の基本です。

macOS Keychainへの登録方法

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

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

オプション	意味
`-a`	アカウント名（通常は `$USER`）
`-s`	サービス名（キーの識別子）
`-w`	パスワード（APIキーの値）

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

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

import subprocess
import getpass

def 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本文にはキーの値が一切含まれない設計になっています。

AI導入に関するお困りごとは、株式会社NexaのAI顧問がサポートします。「何から始めればいいか分からない」という段階からご相談いただけます。

AI顧問の無料相談はこちら →

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

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

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

種類	適するケース	例
単機能スキル	独立した1つのタスク	cron一覧表示、GSCデータ取得
サブスキル群	関連する複数タスクのワークフロー	SEO記事制作フロー、Google Workspace一括操作

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ドラフト作成→現実的なテストケースでの検証→フィードバックを踏まえた改善、というループを繰り返し、仕上げにdescriptionの表現を最適化してトリガー精度を高めてくれます。CLAUDE.mdへのトリガーワード登録はこのスキルの作業範囲外のため、傘型設計で使う場合などは別途自分で追記する必要があります。

活用フロー

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

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

skill-creatorを使うと、ゼロから手順を書き起こすよりも早くSKILL.mdのドラフトに到達できます。ポイントは「既存スキルを参照させること」です。類似構造のスキルがあれば、そのパターンを踏襲した高品質なドラフトが生成されます。

イテレーションのコツ

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

＼ AI活用の「次の一手」を一緒に考えませんか／

AI顧問の無料相談はこちら

よくある問題と解決策

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

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

解決手順:

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

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

5,000トークン（目安として日本語で約3,000〜4,000文字程度）を超えたら分離を検討します。

コマンドリファレンスや詳細な設定値 → references/ フォルダへ移動
実行ロジック → scripts/ フォルダへPythonスクリプトとして分離

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

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

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

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

source /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

Q. SKILL.mdのfrontmatterにはどんなフィールドを書けますか？

必須はnameとdescriptionの2つだけです。加えて、バージョンなど自由形式の情報を書けるmetadata、ライセンスを示すlicenseのほか、Claude Code固有の設定として実行を承認するallowed-toolsや使用モデルを指定するmodelなども指定できます（Anthropic公式ドキュメント「Agent Skills」2026年10月2日確認）。