creating-effective-skills

効果的なスキルの作成

Claude の公式ベストプラクティスに沿ったエージェントスキルを作成するためのガイドです。

基本原則

簡潔さが重要です：コンテキストウィンドウは共有されています。Claude がすでに知っていることは追加しないでください。Claude は非常に賢いという前提を基本とします。

段階的な開示：スキルは次の 3 段階で読み込まれます。

1. メタデータ（約 100 トークン）— 常に読み込み
2. SKILL.md 本文（5k トークン未満）— 起動時に読み込み
3. バンドルされたリソース — 必要に応じて読み込み

SKILL.md は小さく保ちます：目標は約 200 行、最大 500 行です。詳細な内容は積極的に参照ファイルへ移動してください。

単一責任：各スキルは 1 つのことを適切に行います。

ワークフロー

ステップ 1：スキルのニーズを把握する

ユーザーに確認します（状況に合わせて質問を調整してください）。

依頼が明確な場合（例：「Markdown の表を整形する」）：

• 「どの入力形式に対応する必要がありますか？」
• 「出力に関する希望はありますか？」
• 「どのようなエッジケースに対応する必要がありますか？」

依頼が曖昧な場合（例：「データを扱う」「ファイルを手伝う」）：

• 「どのような種類のデータ／ファイルですか？」（形式、ソース、構造）
• 「どのような操作を行いますか？」（変換、検証、移行、分析）
• 「解決すべき具体的な問題は何ですか？」
• 先に進む前に、少なくとも 3 つの具体的な質問をしてください

追加の確認が必要な危険信号：

• 曖昧な動詞：「扱う」「処理する」「管理する」「手伝う」
• 具体性のない広範な名詞：「データ」「ファイル」「ドキュメント」

目的、使用例、起動条件、そして対象範囲の境界を明確に把握してください。

ステップ 2：対象範囲を検証する

先に進む前に、スキルが単一責任に従っていることを確認します。

命名を確認する：

• ❌ handling-data — 範囲が広すぎます。どのデータをどう扱うのでしょうか？
• ❌ data-helper — 汎用的で、目的が不明確です
• ✅ transforming-csv-data — 具体的な操作とデータ形式
• ✅ validating-json-schemas — 単一の目的が明確です

境界を確認する：

• 対象範囲に含まれることと、含まれないことを明確に説明できますか？
• 境界が明確でなければ、対象範囲が広すぎます → ユーザーに絞り込むよう依頼します

対象範囲が広すぎる場合：

1. 焦点を絞った代案を提案します（例：「データを扱う」→「transforming-csv-data」）
2. 何が対象外となるのか、その理由とともに説明します
3. 必要に応じて、複数のスキルに分割することを提案します

対象範囲が検証されるまでは、ファイルの作成に進まないでください。

ステップ 3：自由度を決定する

自由度によって、スキルに従う際に Claude がどの程度柔軟に対応できるかが決まります。

• 高：複数の有効なアプローチがあり、状況に応じた判断が必要です
• 中：推奨されるパターンがあり、ある程度の違いは許容されます
• 低：壊れやすい操作で、一貫性が重要です

自由度が明らかに低い場合を除き、references/degrees-of-freedom.md を読み、判断フレームワークを適用してください。正当化する際は、脆弱性、状況依存性、一貫性、エラーの影響という要因を示してください。

参照資料を読んでも判断できない場合は、ユーザーに確認してください。

ステップ 4：再利用可能な内容を計画する

含める内容を特定します。

スクリプト（scripts/）：決定的な操作を行う実行可能コード 参照資料（references/）：必要に応じて読み込むドキュメント アセット（assets/）：出力に使用するファイル（テンプレート、画像、フォント）

ステップ 5：構成を作成する

skill-name/
├── SKILL.md (required - AI agent instructions)
├── README.md (optional - human-facing installation and usage guide)
├── references/ (optional)
├── tests/
│   └── scenarios.md (optional - self-evaluation scenarios)
├── scripts/ (optional)
└── assets/ (optional)

README.md と SKILL.md の違い：

• SKILL.md：Claude 向けの指示（ワークフロー、パターン、技術的な詳細）
• README.md：人間向けの説明（インストール、権限、概要）

README.md がある場合は、次の内容を含めます：

• スキルの機能の概要
• ファイル構成の説明（特に tests/scenarios.md の目的）
• インストール手順と必要な権限

作成を避けるもの：INSTALLATION_GUIDE.md、CHANGELOG.md、その他の重複するドキュメント。人間向けのドキュメントには README.md を使用してください。

ステップ 6：SKILL.md を作成する

Frontmatter

---
name: skill-name
description: What the skill does and when to use it
---

命名（動名詞形を使用）：

• 推奨：processing-pdfs、analyzing-spreadsheets、managing-databases
• 避ける：helper、utils、tools、anthropic-*、claude-*

説明（三人称で、WHAT と WHEN を含めます）：

• 推奨：「PDF ファイルからテキストや表を抽出し、フォームに入力し、ドキュメントを結合します。PDF ファイルを扱う場合や、ユーザーが PDF、フォーム、ドキュメントの抽出について言及した場合に使用します。」
• 避ける：「ドキュメントを支援します」、「データを処理します」

具体的にし、重要なキーワードを含めてください。説明は、主な起動条件となります。

本文

命令形を使用してください。短く保ちます（目標は約 200 行、最大 500 行）。以下のみを含めてください：

• クイックスタート／基本的な使い方
• 中核となるワークフロー
• 追加ファイルへの参照

複雑な複数ステップのプロセスについては、references/workflows-and-validation.md を参照してください。

パターンの例：

## Quick start
[Basic usage]

## Advanced features
**Feature A**: See [references/feature-a.md](references/feature-a.md)
**Feature B**: See [references/feature-b.md](references/feature-b.md)

参照は 1 階層までにしてください。パターンについては、references/progressive-disclosure.md を参照してください。

ステップ 7：参照ファイルを作成する

100 行を超えるファイルには、先頭に目次を含めてください。

適切な場合は、ドメイン別に整理してください：

skill/
├── SKILL.md
└── references/
    ├── domain_a.md
    └── domain_b.md

避けること：深くネストした参照、重複する情報、汎用的なファイル名。

ステップ 8：テストシナリオを作成する（任意）

ユーザーに尋ねてください：「このスキルのテストシナリオを作成しますか？テストシナリオを使うと、/evaluating-skills-with-models による自動評価で、異なるモデル（sonnet、opus、haiku）間のスキル品質を測定できます。」

ユーザーが同意した場合は、自己評価用に tests/scenarios.md を作成します：

## Scenario: [Name]

**Difficulty:** Easy | Medium | Hard | Edge-case

**Query:** User request that triggers this skill

**Expected behaviors:**

1. [Action description]
   - **Minimum:** What counts as "did it"
   - **Quality criteria:** What "did it well" looks like
   - **Haiku pitfall:** Common failure mode for smaller models
   - **Weight:** 1-5 (importance)

**Output validation:** (optional)
- Pattern: `regex`
- Line count: `< N`

この形式を使用する理由：二択の合否判定では、モデル間の違いを識別できません。品質ベースのスコアリングによって、能力の違いが明らかになります。

ステップ 9：allowed-tools を定義する

SKILL.md と参照ファイルを完成させた後、スキルが使用するツールを特定します：

1. SKILL.md と参照ファイルを確認し、ツールの使用箇所を調べます
2. 事前承認が必要なツールを列挙します（例：Bash(git status:*)、WebSearch、Skill(other-skill)）
3. 必要に応じて、frontmatter に allowed-tools フィールドを追加します

---
name: skill-name
description: ...
allowed-tools: "Bash(git status:*) Bash(git diff:*) WebSearch"
---

このフィールドは実験的なものですが、エージェントによるツールアクセスの事前承認に役立ちます。

重要な考慮事項：

• Read、Glob はすでにデフォルトで許可されています。含めないでください
• Edit、Write は破壊的な操作です。事前承認しないでください
• Bash のサブコマンドは、できるだけ具体的に指定してください
  • 推奨：Bash(git status:*) Bash(git diff:*) Bash(git log:*)
  • 避ける：Bash(git:*)（範囲が広すぎ、git push --force のような破壊的な操作も含まれます）

アンチパターン

❌ Windows 形式のパス（scripts\file.py） ❌ デフォルトを定めずに選択肢を増やしすぎる ❌ 時間の経過によって古くなる情報 ❌ 用語の不統一 ❌ 深くネストした参照 ❌ あいまいな指示

参照資料

段階的な情報開示：references/progressive-disclosure.md - 詳細なパターンと例

自由度：references/degrees-of-freedom.md - 適切な自由度に関するガイダンス

ワークフローと検証：references/workflows-and-validation.md - 検証とフィードバックループを備えたワークフローの作成