create-skills

Claude スキルの作成

スキルは、特定のタスクを一貫して適切に実行する方法を Claude に教える、再利用可能な指示セットです。スキルは SKILL.md ファイルと、任意の補助リソースを含むフォルダーです。スキルが起動すると、Claude は SKILL.md を読み、その指示に従います。

スキルとは、正確な自然言語を使って Claude の振る舞いをプログラミングするものだと考えてください。LLM がインタープリターで、スキルがソースコードです。

スキルを作成するタイミング

次のような場合は、スキルを作成してください。

• 多くの会話で、タスクを一貫して繰り返し実行する必要がある
• タスクに、Claude がデフォルトでは知らない特定のツール、手順、出力形式が関わる
• ワークフローを手作業で改良してきたため、うまくいく方法を記録したい
• 指示が毎回繰り返すには詳細すぎる一方、運任せにするには重要すぎる

次のような場合は、スキルを作成しないでください。

• シンプルなプロンプトで目的を達成できる
• タスクが一度限りである
• その振る舞いがすでに Claude に組み込まれている

ワークフロー

1. Capture Intent → 2. Research & Interview → 3. Draft SKILL.md →
4. Test with real prompts → 5. Refine → 6. Package & deliver

---

ステップ 1：意図を把握する

まず、ユーザーが何を求めているのかを理解します。次の 4 つの質問に答えてください。

1. スキルによって Claude に何をできるようにするべきですか？ 具体的にしましょう。「企業のレターヘッドを使った、ピクセル単位で正確な Word 文書を作成する」は、「文書を作る」より適切です。

2. どのようなときに起動するべきですか？ どのようなフレーズ、ファイル形式、コンテキストがこのスキルを起動するべきですか？具体的にしましょう。起動条件が厳しすぎることが、最もよくある失敗パターンです。

3. 期待される出力は何ですか？ ファイルですか？コードスニペットですか？構造化された応答ですか？成果物を明確に定義してください。

4. 出力は客観的に検証できますか？ ファイル変換、データ抽出、コード生成はテストできます。文体やクリエイティブな作業は、通常テストできません。これによって、テストケースを用意するかどうかが決まります。

現在の会話に、ユーザーが記録したいワークフロー（例：「これをスキルにして」）がすでに含まれている場合は、会話履歴から答えを抽出します。使用したツール、手順の順序、行った修正、確認できた入出力形式などを確認してください。不足部分は、的を絞った質問で補います。

---

ステップ 2：スキルの構造

すべてのスキルは、次の構造に従います。

skill-name/
├── SKILL.md              ← Required. The instruction file.
│   ├── YAML frontmatter   (name + description — always in context)
│   └── Markdown body      (instructions — loaded when skill triggers)
│
└── Optional resources/
    ├── scripts/           Executable code for deterministic tasks
    ├── references/        Docs loaded into context as needed
    └── assets/            Templates, icons, fonts used in output

含めてはいけないもの：README.md、INSTALLATION_GUIDE.md、CHANGELOG.md、人間向けのドキュメント。スキルを読むのは人ではなく、AI エージェントです。

プログレッシブ・ディスクロージャー（3 段階の読み込み）

スキルは、コンテキストを効率的に管理するため、情報を段階的に読み込みます。

レベル	内容	読み込みのタイミング	サイズの目安
1. メタデータ	YAML フロントマター内の name + description	常にコンテキスト内	約100語
2. SKILL.md 本文	Markdown 形式の指示全文	スキルの起動時	理想は500行未満
3. 同梱リソース	スクリプト、参照資料、アセット	明示的な読み込みに応じて	制限なし

説明は最も重要な部分です。これが起動の仕組みとなります。本文はプレイブックです。リソースは詳細な参照資料です。

---

ステップ 3：YAML フロントマターを書く

name フィールド

短い識別子です。小文字を使い、単語をハイフンでつなぎます。例：docx、pdf、frontend-design、deploy-aws。

description フィールド（重要）

description は主なトリガーの仕組みです。Claude は、ユーザーのリクエストと description が一致するかどうかに基づいて、ほぼ全面的にスキルを使用するかどうかを判断します。description が不適切だと、スキルは一度も起動しません。

よくある失敗：トリガー不足。 Claude はスキルの起動に慎重になりがちです。description をやや「積極的」にし、明らかに思えるケースも含めて、スキルが適用される状況を明示してください。

テンプレート：

description: >
  [What the skill does — 1 sentence].
  Use this skill when [primary triggers].
  Also use when [secondary triggers that might be missed].
  Covers [key capabilities].
  Do NOT use for [explicit exclusions to prevent false triggers].

良い例：

description: >
  Use this skill whenever the user wants to create, read, edit, or
  manipulate Word documents (.docx files). Triggers include: any mention
  of "Word doc", "word document", ".docx", or requests to produce
  professional documents with formatting like tables of contents,
  headings, page numbers, or letterheads. Also use when extracting or
  reorganizing content from .docx files, inserting or replacing images
  in documents, performing find-and-replace in Word files, working with
  tracked changes or comments, or converting content into a polished
  Word document. If the user asks for a "report", "memo", "letter",
  "template", or similar deliverable as a Word or .docx file, use this
  skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general
  coding tasks unrelated to document generation.

効果がある理由：

• 主なトリガーフレーズを明示的に列挙している
• 見落とされる可能性のある二次的なトリガーも含めている
• 誤検出を防ぐための除外条件がある
• 技術用語だけでなく、ユーザーが使いそうな語彙にも言及している

悪い例：

description: Creates Word documents.

うまくいかない理由： 曖昧すぎて、トリガーフレーズも除外条件もありません。Claude はいつ起動すればよいかわかりません。

description 作成チェックリスト：

• 最初の文でスキルの機能を説明している
• ユーザーが使いそうなトリガーフレーズを明示的に列挙している
• 二次的、または自明ではないトリガーシナリオも含めている
• 関連するファイル形式や拡張子に言及している
• 誤ったトリガーを防ぐ除外条件がある
• トリガー不足を補うため、やや「積極的」な表現になっている

---

ステップ 4：SKILL.md 本文の作成

構成パターン

スキルの目的に合った構成を選びます。多くのスキルでは複数のパターンを組み合わせます。

パターン	最適な用途	構成例
ワークフローベース	順を追って進めるプロセス	概要 → 決定ツリー → ステップ 1 → ステップ 2...
タスクベース	個別の操作をまとめたツール集	概要 → クイックスタート → タスク A → タスク B...
リファレンス／ガイドライン	標準、仕様、ブランドガイドライン	概要 → ガイドライン → 仕様 → 使用方法
機能ベース	関連機能が統合されたシステム	概要 → 主要機能 → 機能 1 → 機能 2...

執筆の原則

命令形を使います。 説明ではなく、指示として記述します。

# Good
Read the input file. Extract the header row. Validate each column type.

# Bad
The skill should read the input file and then it would extract the header row...

何をするかだけでなく、なぜそうするのかも説明します。 現在の LLM は優れた能力を備えています。指示の背景にある理由を理解すると、より適切に一般化し、指示で明示されていないエッジケースにも対応できます。

# Good
Use pandoc for text extraction because it preserves tracked changes
and handles nested formatting that raw XML parsing misses.

# Bad
ALWAYS use pandoc for text extraction. NEVER use raw XML parsing.

強引な「必ず」や「絶対に」は避けます。 ALWAYS や NEVER を大文字で書いていることに気づいたら、注意が必要です。モデルが重要性を理解できるよう、理由を説明する形に言い換えてください。強引な制約はスキルを脆弱で限定的なものにします。

少数例を含めます。 適切な入力→出力の例をモデルに示します。例は、振る舞いを形作るうえで最も強力な手段のひとつです。

## Commit message format

**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

**Example 2:**
Input: Fixed crash when uploading files over 10MB
Output: fix(upload): handle large file uploads without crash

出力構造が重要な場合は、出力形式を明確に定義します。

## Report structure
Use this exact template:

# [Title]
## Executive summary
[2-3 sentence overview]
## Key findings
[Bulleted list of findings with evidence]
## Recommendations
[Numbered actionable recommendations]

大規模なスキルの整理

SKILL.md が 500 行に近づいている場合は、内容をリファレンスファイルに分割します。

my-skill/
├── SKILL.md                  (core workflow + pointers to references)
└── references/
    ├── aws-deployment.md      (read when deploying to AWS)
    ├── gcp-deployment.md      (read when deploying to GCP)
    └── troubleshooting.md     (read when errors occur)

SKILL.md では、各リファレンスをいつ読むべきか Claude に伝えます。

## Deployment
Read the appropriate reference file based on the target platform:
- AWS: `references/aws-deployment.md`
- GCP: `references/gcp-deployment.md`

If you encounter errors during deployment, consult `references/troubleshooting.md`.

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

スクリプト

決定論的で反復的な操作にはスクリプトを使います。スクリプトはコンテキストに読み込まずに実行できるため（トークンを節約できます）、Claude はロジックを理解または変更する必要があるときに読み取れます。

スクリプトの適した用途：

• ファイル形式の変換
• 検証とリンティング
• テンプレートのひな形作成
• データの抽出または変換

#!/usr/bin/env python3
"""
Extract form fields from a PDF.
Usage: python scripts/extract_fields.py input.pdf
"""

アセット

アセットは、テンプレート、フォント、アイコン、画像、CSS ファイルなど、出力に使われる静的ファイルに使用します。アセットはコピーまたは参照され、解釈されることはありません。

ステップ 5：テスト

スキルの草案を作成したら、現実的なテストプロンプトを 2～3 個作成します。実際のユーザーが口にしそうなものであり、入念に作り込まれたテスト入力ではありません。

適切なテストプロンプト：

• 「このデータを要約した Word 文書を作ってくれますか？」（カジュアルで曖昧）
• 「目次とページ番号を付けて、プロフェッショナルなレポートを作成してください」（具体的）
• 「この .docx ファイルの書式を修正してください」（編集タスク）

確認すること：

1. テストプロンプトからスキルが正しく起動するか？
2. Claude が SKILL.md の指示に従うか？
3. 出力品質に問題がないか？
4. エッジケース（入力の欠落、曖昧な依頼）に対応できるか？

ユーザーが正式な評価を希望する場合は、evals/evals.json を作成します。

{
  "skill_name": "my-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "The user's actual request",
      "expected_output": "What success looks like",
      "files": [],
      "assertions": [
        "Output includes a table of contents",
        "All headings use Heading 1 style",
        "Page numbers appear in the footer"
      ]
    }
  ]
}

フィードバックループ

ユーザーが例や入力を提示するたびに、完全な仕様を待たず、すぐに実行してください。出力を見せて、ユーザーの反応を確かめます。Claude が実際にどう動くかを見ることが、要件を洗練する最も速い方法です。

---

ステップ 6：よくある落とし穴

落とし穴	対策
スキルがまったく起動しない	説明をより明確で「積極的」なものにし、トリガーとなる語句を追加します
関係のない依頼でスキルが起動する	説明に除外事項を追加します（「次の場合は使用しないでください……」）
Claude が指示を無視する	望ましい動作を示す例を追加します。ルールよりも少数の例を使った学習のほうが効果的です
出力形式に一貫性がない	正確な構成を示した明示的なテンプレートを用意します
SKILL.md が長すぎる	詳細な内容を、参照先を明記した references/ ファイルに移します
スキルの融通が利かない	MUST／NEVER のルールを、その理由を説明する内容に置き換えます
テスト例でしかスキルが機能しない	個別のフィードバックから一般化し、修正内容だけでなく原則を説明します
Claude が効果のない手順に時間を浪費する	実行トランスクリプトを読み、無駄な作業を引き起こす指示を削除します

---

ステップ 7：パッケージ化と提供

スキルが完成したら、次の手順に従います。

1. 構成を確認する — SKILL.md が存在し、有効な YAML フロントマターが含まれていることを確認します
2. すべてのファイル参照を確認する — スクリプト、参照ファイル、アセットが存在し、パスが正しいことを確認します
3. 出力ディレクトリにコピーする — ユーザーがアクセスできるようにします
4. ファイルを提示する — スキルの機能とインストール方法を簡潔に説明します

package_skill.py スクリプトが利用できる場合は、これを使って .skill アーカイブを作成します。

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

---

クイックリファレンス：SKILL.md テンプレート

すぐに使えるテンプレートについては、このスキルのディレクトリにある templates/skill-template.md を読みます。

---

スキル作成者への補足アドバイス

これらの原則は、本番用スキルを繰り返し改善する中で得られたものです。

1. 説明がすべてです。 必要だと思う以上に時間をかけて説明を作成してください。優れたスキルでも、説明が不適切だと見つけてもらえません。

2. ルールだけでなく、理由も説明してください。 「追跡された変更を扱えるため pandoc を使用する」は、「必ず pandoc を使用してください」よりも効果的です。理由を理解すると、モデルはより適切に一般化できます。

3. 草案を書いたら、新鮮な目で見直してください。 最初の草案は、詳しすぎる（例に過剰適合する）か、曖昧すぎる（避けたい解釈の余地を残す）かのどちらかです。時間を置いて見直しましょう。

4. 個別のフィードバックから一般化してください。 ユーザーが「この出力は間違っています」と言ったときは、その事例だけを修正するのではなく、どの原則に違反したのかを理解し、その原則を反映してください。

5. 無駄を省いてください。 効果のない指示を削除します。スキル内の何かがモデルに無益な作業をさせているなら、それを取り除きましょう。

6. スキルは何百万回も使われます。 実用上、いくつかの例を使って改善を繰り返しますが、スキルは多様なプロンプトに対応できなければなりません。テストケースへの過剰適合は避けてください。

7. 遠慮しないでください。 Claude は驚くほど優れた成果を出せます。高い基準を設け、その重要性を説明するスキルは、安全策にとどまるスキルよりも、はるかに優れた結果を生み出します。