skill-optimizer

スキル作成ガイド

このスキルでは、効果的なスキルを作成するためのガイダンスを提供します。

スキルについて

スキルは、専門知識、ワークフロー、ツールを提供することで Claude の機能を拡張する、モジュール式の自己完結型パッケージです。特定の分野やタスク向けの「オンボーディングガイド」と考えてください。汎用エージェントである Claude を、どのモデルも完全には備えていない手順に関する知識を持つ、専門エージェントへと変えます。

スキルは Agent Skills オープンスタンダードに準拠しており、呼び出し制御、サブエージェントの実行、動的なコンテキスト注入のための Claude Code 拡張機能も備えています。

スキルが提供するもの

1. 専門的なワークフロー - 特定の分野向けの複数ステップの手順
2. ツール連携 - 特定のファイル形式や API を扱うための手順
3. 分野の専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
4. 同梱リソース - 複雑で反復的なタスク向けのスクリプト、リファレンス、アセット

スキルの構成

すべてのスキルは、必須の SKILL.md ファイルと任意の同梱リソースで構成されます。

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts)

SKILL.md（必須）

メタデータの品質： YAML フロントマターの name と description によって、Claude がスキルを使用するタイミングが決まります。スキルの機能と使用するタイミングを具体的に記述してください。「このスキルを使用してください」ではなく、「このスキルは次の場合に使用します」のように、三人称で記述してください。

フロントマターのフィールド：

フィールド	必須	説明
name	いいえ	表示名（最大 64 文字、小文字とハイフンを使用）。デフォルトはディレクトリ名です。
description	推奨	スキルの機能と使用するタイミング（最大 1024 文字）。
argument-hint	いいえ	オートコンプリート時に表示されるヒント（例：[issue-number]）。
disable-model-invocation	いいえ	true = /name による呼び出しはユーザーのみ可能です。
user-invocable	いいえ	false = / メニューに表示しません（Claude 専用のバックグラウンド知識）。
allowed-tools	いいえ	スキルが有効なときに使用できるツールを制限します（例：Read, Grep, Glob）。
model	いいえ	スキルが有効なときに使用するモデルを指定します。
context	いいえ	fork = 分離されたサブエージェントで実行します。
agent	いいえ	サブエージェントの種類：Explore、Plan、general-purpose、または .claude/agents/ 内のカスタムエージェント。
hooks	いいえ	スキルのライフサイクルに適用するフック。Hooks docsを参照してください。

すべてのフィールドを含む例：

---
name: deploy-production
description: Deploy the application to production. Use after all tests pass.
argument-hint: [environment]
disable-model-invocation: true
allowed-tools: Bash(deploy:*), Read
context: fork
agent: general-purpose
---

文字列の置換

スキルでは、Markdown コンテンツ内の値を動的に置換できます。

変数	説明
$ARGUMENTS	呼び出し時に渡されたすべての引数（例：/my-skill arg1 arg2）
${CLAUDE_SESSION_ID}	ログ記録やセッション固有のファイルに使用する現在のセッション ID

コンテンツに $ARGUMENTS が含まれていない場合、引数は ARGUMENTS: <value> として末尾に追加されます。

例：

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

Log progress to logs/${CLAUDE_SESSION_ID}.log

動的なコンテキスト注入

感嘆符とバッククォートを使う構文は、スキルのコンテンツが Claude に渡される前にシェルコマンドを実行します。コマンドの出力でプレースホルダーが置き換えられます。

構文： 感嘆符の後にバッククォートで囲んだコマンドを続けます：EXCLAIM + BACKTICK command BACKTICK

スキルコンテンツの例：

## PR Context
- Diff: EXCLAIM-BACKTICK gh pr diff BACKTICK
- Comments: EXCLAIM-BACKTICK gh pr view --comments BACKTICK
- Changed files: EXCLAIM-BACKTICK gh pr diff --name-only BACKTICK

Summarize this pull request...

（実際のスキルでは、EXCLAIM を感嘆符に、BACKTICK をバッククォートに置き換えてください）

このスキルの実行時：

1. 感嘆符とバッククォートを使った各コマンドが直ちに実行されます（Claude が何かを見る前に実行されます）
2. 出力によってスキルコンテンツ内のプレースホルダーが置き換えられます
3. Claude は実際のデータを含む、レンダリング済みのプロンプトを受け取ります

これは前処理であり、Claude が実行するものではありません。Claude が見るのは最終結果のみです。

呼び出しの制御

デフォルトでは、ユーザーと Claude の両方が任意のスキルを呼び出せます。これを制御するフロントマターのフィールドは次の 2 つです。

フロントマター	ユーザーが呼び出せる	Claude が呼び出せる	コンテキスト内での表示
（デフォルト）	はい	はい	説明は常に表示されます
disable-model-invocation: true	はい	いいえ	説明は Claude に表示されません
user-invocable: false	いいえ	はい	説明は常に表示されます

それぞれの使用場面：

• disable-model-invocation: true：副作用を伴うワークフロー（デプロイ、コミット、メッセージ送信など）に使用します。Claude が自動的に実行するのを防ぎます。
• user-invocable: false：意味のあるコマンドではないバックグラウンド知識（例：legacy-system-context）に使用します。関連する場合に Claude が参照できるようにしますが、/legacy-system-context はユーザーにとって役に立ちません。

サブエージェントとの連携

context: fork を追加すると、スキルを分離して実行できます。スキルの内容がサブエージェントのプロンプトになります（会話履歴にはアクセスできません）。

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

エージェントのオプション：

エージェント	説明
Explore	読み取り専用のコードベース探索（Glob、Grep、Read）
Plan	アーキテクチャの計画と設計
general-purpose	すべての機能（デフォルト）
カスタム	.claude/agents/ 内の任意のエージェント

注： context: fork が有効なのは、明示的な指示を含むスキルだけです。ガイドラインのみのスキル（例：「この API 規約を使用する」）には実行可能なプロンプトが含まれないため、意味のある出力を返さずに終了します。

スキルの保存場所

スキルの保存場所によって、使用できるユーザーが決まります。

場所	パス	適用対象	優先度
エンタープライズ	管理対象の設定	組織内のすべてのユーザー	最高
個人	~/.claude/skills/<name>/SKILL.md	あなたのすべてのプロジェクト	高
プロジェクト	.claude/skills/<name>/SKILL.md	このプロジェクトのみ	中
プラグイン	<plugin>/skills/<name>/SKILL.md	プラグインが有効な場所	名前空間付き

同じ名前のスキルが複数ある場合は、優先度の高い場所にあるものが使用されます。プラグインのスキルは plugin-name:skill-name という名前空間を使用するため、名前が競合することはありません。

ネストされたスキルの検出： サブディレクトリ（例：packages/frontend/）内のファイルを編集するとき、Claude Code はネストされた .claude/skills/ ディレクトリ内のスキルも検出します。これにより、パッケージごとに独自のスキルを持つモノレポに対応できます。

レガシーコマンド： .claude/commands/ 内のファイルも、同じフロントマターを使用して引き続き動作します。スキルは、補助ファイルなどの追加機能をサポートするため、推奨されています。

同梱リソース（任意）

スクリプト（scripts/）

コンテンツの種類：コード — 決定論的な信頼性が求められるタスクや、コードが繰り返し書き直されるタスク向けの実行可能コード（Python/Bash など）です。

• 含めるタイミング：同じコードが繰り返し書き直される場合や、決定論的な信頼性が必要な場合
• 例：PDF 回転タスク用の scripts/rotate_pdf.py
• 利点：トークン効率が高く、決定論的です。スクリプトのコードはコンテキストに入らず、出力だけが入ります
• 主な利点：200 行のスクリプトでも、2000 個以上のトークン（コード）ではなく、約 20 個のトークン（出力）しか必要としません
• 注： パッチの適用や環境固有の調整のために、Claude がスクリプトを読み込む必要が生じる場合があります

References (references/)

コンテンツタイプ：指示 - Claude のプロセスと思考に役立てるため、必要に応じてコンテキストに読み込むことを想定したドキュメントや参考資料です。

• 含めるタイミング：作業中に Claude が参照するドキュメントの場合
• 例：財務スキーマの references/finance.md、会社の NDA テンプレートの references/mnda.md、会社のポリシーの references/policies.md、API 仕様の references/api_docs.md
• 用途：データベーススキーマ、API ドキュメント、ドメイン知識、会社のポリシー、詳細なワークフローガイド
• メリット：SKILL.md を簡潔に保ち、Claude が必要と判断した場合にのみ読み込まれます
• ベストプラクティス：ファイルが大きい場合（10k 語を超える場合）は、SKILL.md に grep 検索パターンを含めます
• 重複を避ける：情報は SKILL.md または references ファイルのどちらか一方に記載し、両方には記載しないでください。スキルの中核に関わる情報でない限り、詳細情報は references ファイルに記載してください。これにより、SKILL.md を簡潔に保ちながら、コンテキストウィンドウを圧迫せずに情報を見つけやすくできます。SKILL.md には必須の手順とワークフローのガイダンスのみを残し、詳細な参考資料、スキーマ、例は references ファイルに移してください。

Assets (assets/)

コンテンツタイプ：リソース - Claude が作成する出力内で使用するファイルであり、コンテキストへの読み込みを目的としていません。

• 含めるタイミング：スキルで最終出力に使用するファイルが必要な場合
• 例：ブランド素材の assets/logo.png、PowerPoint テンプレートの assets/slides.pptx、HTML/React のひな形の assets/frontend-template/、タイポグラフィ用の assets/font.ttf
• 用途：テンプレート、画像、アイコン、ひな形コード、フォント、コピーまたは編集されるサンプル文書
• メリット：出力用リソースをドキュメントから分離し、コンテキストに読み込まずに Claude がファイルを使用できるようにします

段階的開示の設計原則

スキルでは、コンテキストを効率的に管理するため、3段階の読み込みシステムを使用します。

レベル	読み込みタイミング	トークンコスト	内容
レベル 1：メタデータ	常時（起動時）	スキルあたり約100トークン	YAML フロントマターの name と description
レベル 2：指示	スキルの起動時	5k トークン未満	指示とガイダンスを含む SKILL.md 本文
レベル 3 以上：リソース	必要に応じて	実質無制限*	コンテキストに読み込まず、bash で実行するバンドルファイル

*スクリプトはコードをコンテキストに読み込まずに実行されます（出力のみがコンテキストに入ります）。参考ファイルとアセットは、Claude が bash コマンドを介して明示的にアクセスした場合にのみ読み込まれます。

重要なポイント：コンテキストへの影響を最小限に抑えながら、数十個のスキルをインストールできます。スキルが起動されるまでは、それぞれのスキルが存在することと、いつ使用するかだけを Claude が認識します。

コンテキスト予算：利用可能な機能を Claude が把握できるよう、スキルの説明はコンテキストに読み込まれます。スキルが多い場合、文字数の予算（デフォルトでは15,000文字）を超えることがあります。除外されたスキルを確認するには、/context を実行してください。上限を増やすには、SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数を設定します。

スキルのファイルシステムアーキテクチャ

スキルはローカルファイルシステム上のディレクトリとして存在し、Claude は bash コマンドとファイル操作を使ってスキルを利用します。

Claude がスキルのコンテンツにアクセスする方法：

1. 指示の読み込み：スキルが起動されると、Claude は bash を使ってファイルシステムから SKILL.md を読み込み、その指示をコンテキストに取り込みます
2. 参照ファイルの読み込み：指示で他のファイル（references/api_docs.md やデータベーススキーマなど）が参照されている場合、Claude は追加の bash コマンドを使ってそれらのファイルを読み込みます
3. スクリプトの実行：指示に実行可能なスクリプトが記載されている場合、Claude は bash を使って実行します。コード自体ではなく、スクリプトの出力だけがコンテキストに取り込まれます

これによって可能になること：

• 必要に応じたファイルアクセス：Claude は各タスクに必要なファイルだけを読み込みます。スキルに数十個の参照ファイルを含められますが、タスクで必要なのが1つのスキーマだけなら、Claude はそのファイルだけを読み込みます。残りのファイルはトークンを一切消費しません
• 効率的なスクリプト実行：Claude が validate_form.py を実行すると、200行のスクリプトではなく、出力だけがトークンを消費します。そのため、スクリプトは Claude が同等のコードをその場で生成するよりもはるかに効率的です
• 同梱コンテンツに実質的な上限がないこと：ファイルはアクセスされるまでコンテキストを消費しないため、スキルにはコンテキスト上の負担をかけずに、包括的なドキュメント、データセット、例、参照資料を含められます

ワークフローの例：

1. User: "Process this PDF and extract tables"
2. Claude: bash: read pdf-skill/SKILL.md
3. SKILL.md mentions scripts/extract_tables.py
4. Claude: bash: python scripts/extract_tables.py input.pdf
5. Script output: "Extracted 3 tables: [table data...]"
6. Claude proceeds using the extracted data (script code never entered context)

スキルの作成プロセス

スキルを作成するには、該当しない明確な理由がある場合に限って手順を省略し、「スキルの作成プロセス」の順に進めてください。

ステップ 1：具体例を通じてスキルを理解する

スキルの使用パターンがすでに明確に理解されている場合に限り、このステップを省略してください。既存のスキルに取り組む場合でも、このステップは有用です。

効果的なスキルを作成するには、そのスキルがどのように使われるかを具体例を通じて明確に理解する必要があります。必須の質問が6つ、追加の掘り下げ質問、回答が曖昧すぎる場合に明確な異議を唱えるためのルールが含まれた、references/interview-protocol.md のプロトコルに従って、体系的な聞き取りを行ってください。

最も重要な質問は、「このスキルがない場合、Claude は現在どのような間違いを犯しますか？」です。Claude がすでにそのタスクを適切に処理できているなら、そのスキルを作成する価値はありません。明らかになった失敗パターンはすべて、スキルに含められるコンテンツの中で最も価値の高い、注意点の項目になります。

ユーザーを圧倒しないよう、最も重要な質問から1つずつ尋ねてください。具体的なユースケース、失敗パターンの一覧、検証可能な成功基準がそろったら、このステップを終了します（終了基準は references/interview-protocol.md を参照）。

ステップ 2：再利用可能なスキルの内容を計画する

具体的な例を効果的なスキルにするには、各例を次の観点から分析します。

1. 例のタスクを最初から実行する方法を検討する
2. これらのワークフローを繰り返し実行する際に役立つスクリプト、リファレンス、アセットを特定する

例：「この PDF を回転させるのを手伝って」のような問い合わせに対応する pdf-editor スキルを作成する場合、分析から次のことが分かります。

1. PDF の回転には、毎回同じコードを書き直す必要があります
2. スキルに保存する scripts/rotate_pdf.py スクリプトが役立ちます

例：「ToDo アプリを作って」や「歩数を記録するダッシュボードを作って」のような問い合わせに対応する frontend-webapp-builder スキルを設計する場合、分析から次のことが分かります。

1. フロントエンドの Web アプリを作成するには、毎回同じ定型的な HTML／React を記述する必要があります
2. 定型的な HTML／React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキルに保存すると役立ちます

例：「今日ログインしたユーザー数は？」のような問い合わせに対応する big-query スキルを作成する場合、分析から次のことが分かります。

1. BigQuery へのクエリでは、毎回テーブルのスキーマと関係を再確認する必要があります
2. テーブルスキーマを記載した references/schema.md ファイルをスキルに保存すると役立ちます

スキルに含める内容を決めるには、具体的な各例を分析し、含める再利用可能なリソース（スクリプト、リファレンス、アセット）の一覧を作成します。

カテゴリの特定

このスキルが該当する 9 つのスキルカテゴリのうち、どれに当てはまるかを特定します（分類の全体像、例、構成に関するガイダンスについては references/skill-categories.md を参照してください）。

1. ライブラリと API のリファレンス
2. 製品の検証
3. データの取得と分析
4. コードのひな形とテンプレート
5. コード品質とレビュー
6. CI/CD とデプロイ
7. ランブック
8. ビジネスプロセスとチームの自動化
9. インフラストラクチャ運用

カテゴリを提示し、ユーザーに確認を求めます。最適なスキルは、1 つのカテゴリに明確に当てはまります。2 つのカテゴリにまたがる場合は、その旨を伝えてください。スキルを分割する必要があるかもしれません。このカテゴリによって、スキルの構成パターンと評価戦略が決まります。

ステップ 3：スキルを初期化する

ここから、実際にスキルを作成します。

開発対象のスキルがすでに存在し、反復やパッケージ化が必要な場合に限り、このステップを省略してください。その場合は、次のステップに進みます。

新しいスキルをゼロから作成する場合は、必ず init_skill.py スクリプトを実行してください。このスクリプトは、新しいスキルディレクトリのテンプレートを生成します。スキルに必要なものがすべて自動的に含まれるため、スキル作成のプロセスをより効率的かつ確実に進められます。

使用方法：

scripts/init_skill.py <skill-name> --path <output-directory>

このスクリプトは次の処理を行います。

• 指定したパスにスキルディレクトリを作成します
• 適切なフロントマターと TODO プレースホルダーを含む SKILL.md テンプレートを生成します
• サンプルのリソースディレクトリ（scripts/、references/、assets/）を作成します
• 各ディレクトリに、カスタマイズまたは削除できるサンプルファイルを追加します

初期化後、必要に応じて、生成された SKILL.md とサンプルファイルをカスタマイズまたは削除してください。

ステップ 4：スキルを編集する

（新しく生成した、または既存の）スキルを編集する際は、別の Claude インスタンスが使用するためにスキルを作成していることを念頭に置いてください。Claude にとって有益で、すぐには分からない情報を含めることに重点を置きます。別の Claude インスタンスがタスクをより効果的に実行するために役立つ、手順に関する知識、分野固有の詳細、再利用可能なアセットを検討してください。

再利用可能なスキルの内容から始める

実装を始めるには、上記で特定した再利用可能なリソースである scripts/、references/、assets/ のファイルから着手します。この手順ではユーザーからの入力が必要になる場合があります。たとえば、brand-guidelines スキルを実装する際、assets/ に保存するブランドアセットやテンプレート、または references/ に保存するドキュメントをユーザーから提供してもらう必要がある場合があります。

また、スキルに不要なサンプルファイルやディレクトリは削除します。初期化スクリプトは構成を示すために scripts/、references/、assets/ にサンプルファイルを作成しますが、ほとんどのスキルですべてが必要になるわけではありません。

ドキュメントからリファレンスを作成する（任意）

既存のフレームワーク、ライブラリ、オンラインドキュメントのあるツールを基にスキルを作成する場合は、Skill_Seekers（v2.0.0 以降）を使用して、ドキュメントを自動的にスクレイピングし、references/ ディレクトリに整理できます。Skill_Seekers は統合型のマルチソーススクレイピングに対応し、ドキュメントサイト、GitHub リポジトリ、PDF ファイルを組み合わせて、包括的なリファレンス資料を作成できるようになりました。

この方法を使用するケース：

• 包括的なオンラインドキュメントを持つフレームワーク（React、Django、FastAPI など）のスキルを作成する場合
• ゲームエンジン（Godot、Unity）のスキルを作成する場合
• Web ベースのドキュメントがある API やライブラリを文書化する場合
• GitHub のソースコードから API リファレンスを直接抽出する場合
• 包括的なスキルのために複数のソース（ドキュメント＋コード＋PDF）を組み合わせる場合
• ドキュメントと実際の実装との相違点を検出する場合

クイックスタート：

# One-time setup
git clone https://github.com/yusufkaraaslan/Skill_Seekers.git ~/Skill_Seekers
cd ~/Skill_Seekers
pip install requests beautifulsoup4

# Option 1: Documentation-only scraping (classic approach)
python3 cli/doc_scraper.py --config configs/react.json
cp -r output/react/references/* /path/to/your-skill/references/

# Option 2: GitHub-only scraping (extract API from source code)
python3 cli/github_scraper.py --repo facebook/react --extract-api
cp -r output/react_github/references/* /path/to/your-skill/references/

# Option 3: Unified multi-source scraping (RECOMMENDED)
# Combines documentation + GitHub code + PDFs into one comprehensive skill
python3 cli/unified_scraper.py --config configs/react_unified.json
cp -r output/react_complete/references/* /path/to/your-skill/references/

# Option 4: Custom unified config
python3 cli/config_validator.py configs/myframework_unified.json
python3 cli/unified_scraper.py --config configs/myframework_unified.json

代替方法： より簡単な方法で十分な場合や、ドキュメントが Web ベースでない場合は、references/ ディレクトリにリファレンスファイルを手動で作成します。

Skill_Seekers の詳細については、references/documentation-scraping.md を参照してください。

SKILL.md を更新する

文体： スキル全体を、二人称ではなく命令形／不定詞形（動詞から始まる指示）で記述します。客観的で指示的な表現を使用します（「X を達成するには、Y を行う」のように記述し、「X を行うべきです」や「X を行う必要がある場合は」のような表現は避けます）。これにより、AI が内容を利用する際の一貫性と明確さが保たれます。強調にすべて大文字を使うことは避け、代わりに Markdown の太字や見出しを使用します。CRITICAL／MANDATORY／MUST といった限定表現は避けます。Claude 4.6 では、直接的な命令形で十分です。

SKILL.md を完成させるため、次の質問に回答します。

1. このスキルの目的は何ですか？ 数文で説明します。
2. このスキルはいつ使用しますか？
3. 実際に、Claude はこのスキルをどのように使用すればよいですか？ Claude が再利用可能なスキルの内容をどのように使うか把握できるよう、上記で作成したすべての内容を参照します。

スキル作成の理念

スキルの指示を書くときは、Anthropic の skill-creator の調査をもとにした次の原則に従ってください。

あらゆる指示の「理由」を説明します。 理由を説明する指示は、単なる指示よりも幅広い状況に応用できる能力を高めます。「スキャンした文書では OCR の誤りがよく起きるため、スクリプトで出力を検証します」は、「検証スクリプトを実行します」より効果的です。Claude は、指示で扱われていない未知の状況にも、その理由を応用します。

プロンプトは簡潔に保ちます。 SKILL.md のトークンはすべて、ユーザーの実際のタスクに使えるコンテキストを減らします。参考資料は references/ に、詳細な例は assets/ に、繰り返し使うロジックは scripts/ に移してください。スキル本文には、Claude が「何をすべきか」を判断するために必要な内容だけを記載し、「どのように実行するか」の詳細を網羅する必要はありません。

繰り返しの作業はスクリプトにまとめます。 同じコードが複数のテスト実行や評価の記録に登場する場合は、スクリプトに切り出してください。スクリプトは出力だけがコンテキストに入るため、トークン効率が高く、決定論的で、キャッシュ可能です。テストケース全体のパターンを見つけ、まとめられる箇所を特定してください。

説明は少し「強め」にします。 スキルは、過剰に起動するよりも起動しないことのほうが多くあります。「このスキルは、次のような場合に使用します」のように、具体的なトリガーフレーズを含めて積極的に対象範囲を示す説明は、受け身の説明より効果的です。ユーザーが自然に使うキーワードも含めてください。

Claude 4.6 のプロンプト作成方針との整合

スキルの指示を書くとき、またはレビューするときは、次のパターンに従ってください。

言葉遣いの調整：

• ALL CAPS で強調せず、直接的な命令形を使います。「Firecrawl をウェブスクレイピングに使用してください」とし、「必ず Firecrawl を使用してください」や「Firecrawl を使用しなければなりません」とはしません。
• CRITICAL／MANDATORY／MUST のマーカーは、通常の見出しに置き換えます。Claude 4.6 は、強制的な表現を使わなくても、構成の整った指示に適切に従います。
• 指示の理由を説明します。「--only-main-content を使用してトークン消費を抑えます」とし、「必ず --only-main-content を使用してください」とはしません。Claude は、理由を説明したほうが幅広い状況に応用できます。

怠惰を防ぐプロンプトを取り除く：

• 「徹底的に行う」「慎重に考える」「怠けない」「意欲を高める表現」は含めないでください。Claude 4.6 はすでに自発的に行動するため、こうした表現は計画の立てすぎや、文章の作成と書き直しを繰り返す傾向を強めます。

サブエージェントのガイダンス（オーケストレーション用スキルの場合）：

• エージェントを起動しない場面を明示してください。Claude 4.6 は、直接対応したほうが速い場合でも、サブエージェントを使う傾向があります。
• 「タスクを並行して進められる場合や、コンテキストを分離する必要がある場合はエージェントを使用します。順次実行するタスク、単一ファイルの編集、または 5 分以内に完了できる作業は、直接対応します。」

過剰な対応を防ぐ：

• 最小限の解決策を選ぶためのガイダンスを含めてください。「既存の規約に従う」といった事実に基づく品質基準は、「無秩序化に立ち向かう」といった意欲を高める表現よりも効果的です。

ステップ 5：スキルのパッケージ化

スキルの準備ができたら、ユーザーと共有できる配布用 ZIP ファイルにパッケージ化します。パッケージ化のプロセスでは、すべての要件を満たしていることを確認するため、まずスキルを自動で検証します。

scripts/package_skill.py <path/to/skill-folder>

出力ディレクトリの指定（任意）：

scripts/package_skill.py <path/to/skill-folder> ./dist

パッケージ化スクリプトでは、次の処理が行われます。

1. 検証： スキルを自動で検証し、次の項目を確認します。

   • YAML フロントマターの形式と必須フィールド
   • スキルの命名規則とディレクトリ構造
   • 説明の完全性と品質
   • ファイルの整理とリソース参照

2. パッケージ化： 検証に合格した場合、スキル名を付けた ZIP ファイル（例：my-skill.zip）を作成します。このファイルにはすべてのファイルが含まれ、配布に適したディレクトリ構造が維持されます。

検証に失敗すると、スクリプトはエラーを報告し、パッケージを作成せずに終了します。検証エラーを修正してから、パッケージ化コマンドを再度実行してください。

ステップ 6：テストと評価

パッケージ化した後、スキルの有効性を測定するため、体系的にテストします。このステップでは、Anthropic の評価フレームワークをスキル品質の測定に応用します。

2 種類のスキル

評価を作成する前に、スキルがどちらのカテゴリに当てはまるかを特定します。これにより評価戦略が決まります。

• 能力の向上：スキルがないと Claude が安定して実行できない作業を支援します（例：PDF フォームへの入力、特定のファイル形式の生成）。評価戦略：スキルありの場合となしの場合の出力を比較します。
• 符号化された好み：Claude がすでに実行できるワークフローの手順を、特定の好みやドメイン知識を反映して組み立てます（例：コーディングスタイルガイド、ブランドの語り口）。評価戦略：出力を人間がレビューしたゴールドスタンダードと比較します。

カテゴリごとの評価戦略（ライブラリ／API スキルをランブックや検証スキルと異なる方法で評価する方法）については、references/skill-categories.md を参照してください。

評価の作成

スキルディレクトリに、現実的なテスト用プロンプトを 2～5 件含む evals/evals.json を作成します。

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's example prompt",
      "expected_output": "Description of expected result",
      "files": ["evals/files/sample1.pdf"],
      "expectations": [
        "The output includes X",
        "The skill used script Y"
      ]
    }
  ]
}

各評価には、以下が必要です。

• 実際にユーザーが使いそうな現実的なプロンプト
• 任意の入力ファイル（evals/files/ に配置）
• 期待される出力の、人が読める説明
• 採点者が出力と照らして確認できる、検証可能な期待事項 3～7 件

期待事項は、具体的で反証可能な記述にします。曖昧な品質評価は避けてください。「出力に 5 列の表が含まれている」は検証可能です。「出力が適切に書式設定されている」は検証できません。

評価の実行

評価ランナースクリプトを使って評価を実行します。

# Run evals with the skill active
python3 scripts/run_eval.py --eval-set evals/evals.json --skill-path <skill-path>

# Run with multiple attempts per query for reliability
python3 scripts/run_eval.py --eval-set evals/evals.json --skill-path <skill-path> --runs-per-query 3

実行ごとに、スキルの出力、トランスクリプト、処理時間とトークンのメトリクスを含む出力ディレクトリが生成されます。

採点

評価を実行した後、期待事項に照らして出力を採点します。採点エージェント（agents/grader.md）は、各期待事項を根拠とともに合格／不合格で評価し、出力から暗黙の主張を抽出し、トランスクリプトから実行側の動作を要約します。

採点結果として、合格率、実行メトリクス、処理時間データを含む grading.json が生成されます。スキーマの全容については、references/schemas.md を参照してください。

ベンチマーク

複数回の実行結果を集計するには、以下を実行します。

python3 scripts/aggregate_benchmark.py <benchmark-dir> --skill-path <skill-path>

これにより、スキルあり／なしの設定ごとに、合格率、処理時間、トークン使用量の統計集計（平均、標準偏差）を含む benchmark.json が生成されます。次に、分析エージェント（agents/analyzer.md）が、集計メトリクスでは見えにくいパターン（識別力のないアサーション、ばらつきの大きい評価、品質と速度のトレードオフ）を明らかにします。

結果のレビュー

定性的および定量的なレビューを行うには、評価ビューアーを起動します。

# Interactive server (auto-refreshes on new outputs)
python3 eval-viewer/generate_review.py <workspace-path>

# Static HTML export
python3 eval-viewer/generate_review.py <workspace-path> --static review.html

# With previous iteration context
python3 eval-viewer/generate_review.py <workspace-path> --previous-workspace <prev-workspace>

# With benchmark data
python3 eval-viewer/generate_review.py <workspace-path> --benchmark <benchmark.json>

ビューアーには 2 つのタブがあります。出力（実行ごとのフィードバックを含む定性的レビュー）と、ベンチマーク（合格率、処理時間、トークンの定量的なグラフ）です。

ブラインド A/B 比較

2 つのスキルバージョンを比較するには、比較エージェント（agents/comparator.md）を使用します。このエージェントは、どちらのスキルが生成したかを知らずに、A と B のラベルが付いた出力を受け取ります。これにより、特定の手法に偏ることを防ぎます。比較エージェントは、内容と構成の観点からなる評価基準を生成し、各出力を 1～5 点で採点して、勝者を判定します。

比較後、分析エージェントが結果のブラインドを解除し、優先度（高／中／低）と種類（指示、ツール、例、エラー処理、構成、参照）別に分類した、実行可能な改善提案を作成します。

バージョンの追跡

改善の反復を history.json に記録します。

{
  "skill_name": "pdf",
  "current_best": "v2",
  "iterations": [
    {"version": "v0", "parent": null, "expectation_pass_rate": 0.65, "grading_result": "baseline"},
    {"version": "v1", "parent": "v0", "expectation_pass_rate": 0.75, "grading_result": "won"},
    {"version": "v2", "parent": "v1", "expectation_pass_rate": 0.85, "grading_result": "won"}
  ]
}

ステップ 7：説明の最適化

スキルの説明によって、Claude がそのスキルをいつ使用するかが決まります。説明が不十分だと、トリガー不足（使うべきときにスキルが呼び出されない）や過剰トリガー（使うべきでないときにスキルが呼び出される）が起こります。このステップでは、説明を体系的に最適化します。

トリガー評価クエリの生成

テスト用クエリを 20 件作成します。スキルをトリガーすべきものを 10 件、トリガーすべきでないものを 10 件用意します。スキルの対象領域に近いものの、トリガーすべきでないクエリなど、現実的なエッジケースを含めます。

pdf-editor スキルの場合の例：

• トリガーすべき：「この PDF を 90 度回転して」「この 3 つの PDF を結合して」「この文書から 5 ページ目を抽出して」
• トリガーすべきでない：「この PDF を読んで要約して」「この Word 文書を PDF に変換して」「この PDF には何が書かれていますか？」

最適化ループを実行する

python3 scripts/run_loop.py \
  --eval-set trigger-queries.json \
  --skill-path <skill-path> \
  --holdout 0.4 \
  --runs-per-query 3 \
  --max-iterations 5 \
  --model sonnet

ループの流れ：

1. クエリをトレーニング用 60％、テスト用 40％に分割します
2. 信頼性を高めるため、各クエリを 3 回実行します（多数決）
3. トレーニングセットの失敗を分析します
4. 拡張思考を使って、改善した説明を生成します
5. 保留しておいたテストセットで評価します
6. 収束するか、最大反復回数に達するまで繰り返します

確認して採用する

ループによって、反復ごとの精度の推移を示す HTML レポートが生成されます。最終的な説明を確認してください。過剰なトリガーを避けるために十分具体的でありながら、正当なユースケースを捉えられるだけの網羅性が必要です。

最適化した説明によってテストセットの精度が向上した場合は、スキルの YAML フロントマターにある description フィールドを更新してください。精度が頭打ちになったり低下したりした場合は、現在の説明を維持し、トリガーとなるクエリ自体を見直す必要があるか調査してください。

ステップ 8：反復する

スキルをテストした後、ユーザーから改善を求められることがあります。多くの場合、スキルを使った直後に、スキルの動作に関する新鮮なコンテキストをもとに依頼されます。

反復ワークフロー：

1. 実際のタスクでスキルを使用します
2. 問題点や非効率な点に気づきます
3. SKILL.md または同梱リソースをどのように更新すべきか特定します
4. 変更を実装し、再度テストします

ユーザーごとの設定、永続メモリ、セッションスコープのフック、使用状況の分析が必要なスキルについては、references/advanced-patterns.md を参照してください。

スキルを共有する

スキルは、さまざまな範囲に配布できます。

• プロジェクトスキル：.claude/skills/ をバージョン管理にコミットします
• プラグイン：プラグインに skills/ ディレクトリを作成します
• 管理対象：管理設定を通じて組織全体にデプロイします

各階層を使い分けるタイミング、スキルの段階的な昇格（個人 -> プロジェクト -> プラグイン -> 管理対象）、ポートフォリオの整理（コンテキスト予算、キュレーション、エージェント数の上限約 40）については、references/distribution-strategy.md を参照してください。

トラブルシューティング

スキルがトリガーされない

期待どおりに Claude がスキルを使わない場合：

1. 説明に、ユーザーが自然に使うキーワードが含まれていることを確認します
2. 「利用可能なスキルは何ですか？」への応答に、そのスキルが表示されることを確認します
3. 説明により近い表現になるよう、リクエストを言い換えてみます
4. スキルをユーザーが呼び出せる場合は、/skill-name で直接呼び出します

スキルが頻繁にトリガーされる

望んでいないときに Claude がスキルを使う場合：

1. 説明をより具体的にします
2. 手動での呼び出しのみを許可する場合は、disable-model-invocation: true を追加します

Claude がすべてのスキルを認識しない

スキルの説明はコンテキストに読み込まれます。スキルの数が多いと、文字数の上限（デフォルトでは 15,000 文字）を超えることがあります。/context を実行し、除外されたスキルに関する警告がないか確認してください。

上限を引き上げるには、SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数を設定します。

関連リソース

• サブエージェント：専門エージェントにタスクを委任します
• プラグイン：他の拡張機能とともにスキルをパッケージ化して配布します
• フック：ツールイベントに関連するワークフローを自動化します
• メモリ：永続的なコンテキスト用の CLAUDE.md ファイルを管理します
• 権限：ツールとスキルへのアクセスを制御します