customaize-agent:create-skill

スキル作成コマンド

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

概要

スキルの作成とは、プロセス文書に適用するテスト駆動開発です。

個人用スキルは、エージェント固有のディレクトリ（Claude Code の場合は ~/.claude/skills、Codex の場合は ~/.codex/skills）に保存します。

サブエージェントを使ってテストケース（プレッシャーシナリオ）を作成し、その失敗（ベースラインの振る舞い）を確認してから、スキル（ドキュメント）を書き、テストの成功（エージェントが指示に従うこと）を確認し、最後に抜け穴を塞ぐようリファクタリングします。

基本原則： スキルなしでエージェントが失敗するのを見ていなければ、そのスキルが適切なことを教えているかどうかは分かりません。

必須の前提知識： このスキルを使う前に、テスト駆動開発を必ず理解してください。テスト駆動開発では、基本となる RED-GREEN-REFACTOR サイクルを定義します。このスキルでは、TDD をドキュメントに適用します。

公式ガイダンス： /customaize-agent:apply-anthropic-skill-best-practices コマンドで提供される Anthropic 公式のスキル作成ベストプラクティスは、customize-agent:prompt-engineering スキルを補強します。スキルとドキュメントを併用してください。これらは互いを複製するのではなく、補完し合います。このドキュメントでは、このスキルの TDD 重視のアプローチを補完する追加のパターンとガイドラインを提供します。

スキルについて

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

スキルとは？

スキルとは、実証済みの手法、パターン、ツールをまとめたリファレンスガイドです。スキルを使うことで、将来の Claude インスタンスが効果的なアプローチを見つけて適用できます。

スキルに含まれるもの： 再利用可能な手法、パターン、ツール、リファレンスガイド

スキルに含まれないもの： ある問題を一度解決した際の経緯

スキルが提供するもの

1. 専門的なワークフロー - 特定の領域における複数ステップの手順
2. ツール連携 - 特定のファイル形式や API を使うための指示
3. 領域の専門知識 - 会社固有の知識、スキーマ、ビジネスロジック
4. 同梱リソース - 複雑で反復的なタスクに役立つスクリプト、リファレンス、アセット

スキルにおける TDD の対応関係

TDD の概念	スキルの作成
テストケース	サブエージェントを使ったプレッシャーシナリオ
本番コード	スキルのドキュメント（SKILL.md）
テスト失敗（RED）	スキルなしでエージェントがルールに違反する（ベースライン）
テスト成功（GREEN）	スキルがある状態でエージェントが指示に従う
リファクタリング	指示への準拠を維持しながら抜け穴を塞ぐ
最初にテストを書く	スキルを書く前にベースラインシナリオを実行する
失敗を確認する	エージェントが使う正確な正当化の仕方を記録する
最小限のコード	特定された違反に対処するスキルを書く
成功を確認する	エージェントが指示に従うようになったか検証する
リファクタリングサイクル	新たな正当化の仕方を見つけて対策し、再検証する

スキル作成の全工程は、RED-GREEN-REFACTOR に従います。

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

作成するケース：

• 自分にとって直感的に明らかではなかった手法
• 複数のプロジェクトで再び参照する手法
• 幅広く応用できるパターン（プロジェクト固有ではないもの）
• 他の人にも役立つもの

作成しないケース：

• 一度きりの解決策
• 他の場所で十分に文書化されている標準的な手法
• プロジェクト固有の規約（CLAUDE.md に記載してください）

スキルの種類

手法

従うべき具体的な手順（condition-based-waiting、root-cause-tracing）

パターン

問題に対する考え方（flatten-with-flags、test-invariants）

リファレンス

API ドキュメント、構文ガイド、ツールのドキュメント（office docs）

ディレクトリ構造

skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed

フラットな名前空間 - すべてのスキルを検索可能な1つの名前空間にまとめます

ファイルを分けるもの：

1. 大規模なリファレンス（100行以上） - API ドキュメント、包括的な構文資料
2. 再利用可能なツール - スクリプト、ユーティリティ、テンプレート

インラインに含めるもの：

• 原則と概念
• コードパターン（50行未満）
• その他すべて

スキルの構成

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

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

SKILL.md（必須）

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

SKILL.md の構成

フロントマター（YAML）：

• サポートされるフィールドは name と description の 2 つのみです
• 合計で最大 1024 文字です
• name：英字、数字、ハイフンのみを使用してください（括弧や特殊文字は使用しないでください）
• description：三人称で記述し、機能と使用する場面の両方を含めてください
  • トリガー条件に焦点を当てるため、「Use when...」で始めてください
  • 具体的な症状、状況、コンテキストを含めてください
  • 可能であれば 500 文字未満にしてください

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms] - [what the skill does and how it helps, written in third person]
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
[Small inline flowchart IF decision non-obvious]

Bullet list with SYMPTOMS and use cases
When NOT to use

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
Link to file for heavy reference or reusable tools

## Common Mistakes
What goes wrong + fixes

## Real-World Impact (optional)
Concrete results

バンドルリソース（任意）

スクリプト（scripts/）

決定論的な信頼性が必要なタスクや、繰り返し書き直されるタスクに使用する実行可能コード（Python／Bash など）です。

• 含める場合： 同じコードを繰り返し書き直している場合、または決定論的な信頼性が必要な場合
• 例： PDF 回転タスク用の scripts/rotate_pdf.py
• メリット： トークン効率が高く、決定論的で、コンテキストに読み込まずに実行できる場合があります
• 注： パッチ適用や環境固有の調整のため、Claude がスクリプトを読み込む必要がある場合があります

参照資料（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 または参照ファイルのいずれかに記載し、両方には記載しないでください。スキルの中核にあたる情報でない限り、詳細情報は参照ファイルに記載してください。これにより、SKILL.md を簡潔に保ちつつ、コンテキストウィンドウを圧迫せずに情報を見つけやすくできます。SKILL.md には不可欠な手順とワークフローのガイダンスのみを残し、詳細な参照情報、スキーマ、例は参照ファイルに移してください。

アセット（assets/）

コンテキストに読み込むのではなく、Claude が生成する出力で使用するファイルです。

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

段階的開示の設計原則

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

1. メタデータ（name + description） - 常にコンテキスト内にあります（約 100 語）
2. SKILL.md 本文 - スキルが起動した場合に読み込まれます（5k 語未満）
3. バンドルリソース - Claude が必要に応じて読み込みます（無制限*）

*スクリプトはコンテキストウィンドウに読み込まずに実行できるため、無制限です。

Claude 検索最適化（CSO）

発見されるために重要： 将来の Claude がスキルを見つけられるようにします

1. 充実した説明フィールド

目的： Claude は説明を読んで、タスクに応じてどのスキルを読み込むか判断します。「今、このスキルを読むべきか？」に答えられるようにします。

形式： 「Use when...」で始めて適用条件に焦点を当て、その後にスキルの機能を説明します

内容：

• このスキルが適用されることを示す、具体的なトリガー、症状、状況を挙げます
• 言語固有の症状（setTimeout、sleep）ではなく、問題（競合状態、一貫性のない動作）を説明します
• スキル自体が特定の技術に依存する場合を除き、トリガーは技術に依存しないものにします
• スキルが特定の技術に依存する場合は、そのことをトリガーに明示します
• 三人称で記述します（システムプロンプトに挿入されます）

# ❌ BAD: Too abstract, vague, doesn't include when to use
description: For async testing

# ❌ BAD: First person
description: I can help you with async tests when they're flaky

# ❌ BAD: Mentions technology but skill isn't specific to it
description: Use when tests use setTimeout/sleep and are flaky

# ✅ GOOD: Starts with "Use when", describes problem, then what it does
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests

# ✅ GOOD: Technology-specific skill with explicit trigger
description: Use when using React Router and handling authentication redirects - provides patterns for protected routes and auth state management

2. キーワードの網羅

Claude が検索しそうな語句を使います。

• エラーメッセージ：「Hook timed out」、「ENOTEMPTY」、「race condition」
• 症状：「flaky」、「hanging」、「zombie」、「pollution」
• 同義語：「timeout/hang/freeze」、「cleanup/teardown/afterEach」
• ツール：実際のコマンド、ライブラリ名、ファイル形式

3. 説明的な命名

能動態を使い、動詞から始めます：

• ✅ creating-skills。skill-creation ではありません
• ✅ testing-skills-with-subagents。subagent-skill-testing ではありません

4. トークン効率（重要）

問題： getting-started と頻繁に参照されるスキルは、すべての会話で読み込まれます。トークンは一つ残らず重要です。

目標の語数：

• getting-started のワークフロー：それぞれ <150 語
• 頻繁に読み込まれるスキル：合計 <200 語
• その他のスキル：<500 語（簡潔さは保ちます）

テクニック：

詳細はツールのヘルプに移動します：

# ❌ BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.

相互参照を使います：

# ❌ BAD: Repeat workflow details
When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# ✅ GOOD: Reference other skill
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

例を簡潔にします：

# ❌ BAD: Verbose example (42 words)
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# ✅ GOOD: Minimal example (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]

重複をなくします：

• 相互参照先のスキルに書かれている内容を繰り返さないでください
• コマンドを見れば明らかなことを説明しないでください
• 同じパターンの例を複数含めないでください

検証：

wc -w skills/path/SKILL.md
# getting-started workflows: aim for <150 each
# Other frequently-loaded: aim for <200 total

実行することや中心となる洞察に基づいて命名します：

• ✅ condition-based-waiting > async-test-helpers
• ✅ using-skills。skill-usage ではありません
• ✅ flatten-with-flags > data-structure-refactoring
• ✅ root-cause-tracing > debugging-techniques

プロセスには動名詞（-ing 形）が適しています：

• creating-skills、testing-skills、debugging-with-logs
• 能動的で、実行するアクションを表します

4. 他のスキルへの相互参照

他のスキルを参照するドキュメントを書く場合：

明示的な必須マーカーを付け、スキル名だけを使います。

• ✅ 良い例：**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development
• ✅ 良い例：**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging
• ❌ 悪い例：See skills/testing/test-driven-development（必須かどうかが不明確です）
• ❌ 悪い例：@skills/testing/test-driven-development/SKILL.md（強制的に読み込み、コンテキストを消費します）

@ リンクを使わない理由： @ 構文はファイルをすぐに強制読み込みするため、必要になる前に 200k+ のコンテキストを消費します。

フローチャートの使用

digraph when_flowchart {
    "Need to show information?" [shape=diamond];
    "Decision where I might go wrong?" [shape=diamond];
    "Use markdown" [shape=box];
    "Small inline flowchart" [shape=box];

    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
}

フローチャートを使うのは、次の場合に限ります：

• 自明ではない判断点
• 早く止めすぎる可能性があるプロセスのループ
• 「A と B のどちらを使うか」という判断

フローチャートを使わないでください：

• 参照資料 → 表、リスト
• コード例 → Markdown ブロック
• 直線的な手順 → 番号付きリスト
• 意味上の役割がないラベル（step1、helper2）

graphviz のスタイル規則については、graphviz-conventions.dot を参照してください。

コード例

優れた例一つは、平凡な例をいくつも並べるより効果的です

最も関連性の高い言語を選びます：

• テスト手法 → TypeScript/JavaScript
• システムのデバッグ → Shell/Python
• データ処理 → Python

良い例：

• 完結していて実行可能
• WHY を説明するコメントが十分にある
• 実際のシナリオに基づいている
• パターンを明確に示している
• 応用しやすい（汎用テンプレートではない）

避けること：

• 5 つ以上の言語で実装する
• 空欄を埋めるだけのテンプレートを作る
• 不自然な例を書く

移植は得意です。優れた例が一つあれば十分です。

ファイル構成

自己完結型のスキル

defense-in-depth/
  SKILL.md    # Everything inline

適用する場合：すべての内容が収まり、重い参照資料が不要なとき

再利用可能なツールを含むスキル

condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt

対象：ツールが単なる説明ではなく、再利用可能なコードである場合

参照情報が大量にあるスキル

pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools

対象：参照資料が大きすぎてインラインで記載できない場合

鉄則（TDDと同じ）

すべてのスキルタイプをテストする

スキルのタイプごとに、異なるテスト方法が必要です。

規律を徹底させるスキル（ルール／要件）

例： TDD、完了前の検証、コーディング前の設計

次の方法でテストします：

• 理論的な質問：ルールを理解しているか？
• プレッシャーのかかるシナリオ：ストレス下でもルールを守るか？
• 複数のプレッシャーを組み合わせる：時間＋埋没コスト＋疲労
• 合理化を特定し、明示的な反論を追加する

成功基準： 最大のプレッシャー下でも、エージェントがルールに従う

技法スキル（手順ガイド）

例： condition-based-waiting、root-cause-tracing、defensive-programming

次の方法でテストします：

• 適用シナリオ：技法を正しく適用できるか？
• バリエーションシナリオ：エッジケースに対応できるか？
• 情報不足テスト：指示に抜けがないか？

成功基準： エージェントが新しいシナリオに技法を正しく適用できる

パターンスキル（メンタルモデル）

例： reducing-complexity、information-hiding concepts

次の方法でテストします：

• 認識シナリオ：パターンを適用する場面を認識できるか？
• 適用シナリオ：メンタルモデルを活用できるか？
• 反例：適用すべきでない場面を理解しているか？

成功基準： エージェントがパターンを適用する場面と方法を正しく特定する

参照スキル（ドキュメント／API）

例： API ドキュメント、コマンドリファレンス、ライブラリガイド

次の方法でテストします：

• 検索シナリオ：適切な情報を見つけられるか？
• 適用シナリオ：見つけた情報を正しく使えるか？
• 網羅性テスト：一般的なユースケースがカバーされているか？

成功基準： エージェントが参照情報を見つけ、正しく適用する

合理化に対するスキルの耐性を高める

TDDのように規律を徹底させるスキルは、合理化に屈しないようにする必要があります。エージェントは賢く、プレッシャーがかかると抜け道を見つけます。

心理学に関する注記： 説得の手法がなぜ効果を発揮するのかを理解すると、体系的に応用しやすくなります。権威、一貫性、希少性、社会的証明、一体性の原則に関する研究の基礎（Cialdini, 2021；Meincke et al., 2025）については、persuasion-principles.mdを参照してください。

すべての抜け道を明示的に塞ぐ

ルールを述べるだけでなく、具体的な回避策を禁止します：

```markdown Write code before test? Delete it. ``` ```markdown Write code before test? Delete it. Start over.

No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

</Good>

### 「精神と文言」の議論に対処する

基本原則を早い段階で追加します：

```markdown
**Violating the letter of the rules is violating the spirit of the rules.**

これにより、「精神には従っている」という合理化を一掃できます。

合理化の表を作成する

ベースラインテストで見つかった合理化を記録します（下記のテストセクションを参照）。エージェントが口にする言い訳はすべて表に追加します：

| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |

危険信号のリストを作成する

合理化しているときに、エージェントが簡単に自己確認できるようにします：

## Red Flags - STOP and Start Over

- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

違反の兆候をCSOに追加する

ルールに違反しようとしているときの兆候を、説明に追加します：

description: use when implementing any feature or bugfix, before writing implementation code

スキルのRED-GREEN-REFACTOR

TDDのサイクルに従います：

RED：失敗するテストを書く（ベースライン）

スキルを使わずに、サブエージェントでプレッシャーシナリオを実行します。具体的な振る舞いを記録します：

• どのような選択をしたか？
• どのような合理化を使ったか（逐語的に）？
• どのプレッシャーが違反を引き起こしたか？

これは「テストが失敗するのを確認する」段階です。スキルを書く前に、エージェントが自然にどう振る舞うかを必ず確認してください。

GREEN：最小限のスキルを書く

見つかった具体的な合理化に対処するスキルを書きます。仮定上のケースに備えて余計な内容を追加しないでください。

同じシナリオをスキルを使って実行します。エージェントはルールに従うはずです。

REFACTOR：抜け道を塞ぐ

エージェントが新たな合理化を見つけましたか？明示的な反論を追加し、完全に対処できるまで再テストします。

必須のサブスキル： 完全なテスト方法については、superpowers:testing-skills-with-subagentsを使用します。

• プレッシャーシナリオの書き方
• プレッシャーの種類（時間、埋没コスト、権威、疲労）
• 抜け穴を体系的に塞ぐ方法
• メタテストの手法

アンチパターン

❌ 物語形式の例

「2025-10-03 のセッションで、空の projectDir が原因で…」 なぜ悪いか: 具体的すぎて再利用できない

❌ 多言語による希薄化

example-js.js、example-py.py、example-go.go なぜ悪いか: 品質が平凡で、メンテナンスの負担になる

❌ フローチャート内のコード

step1 [label="import fs"];
step2 [label="read file"];

なぜ悪いか: コピー＆ペーストできず、読みにくい

❌ 汎用的なラベル

helper1、helper2、step3、pattern4 なぜ悪いか: ラベルには意味のある名前を付けるべき

停止: 次のスキルに進む前に

スキルを書いた後は、必ず停止してデプロイプロセスを完了してください。

やってはいけないこと:

• 各スキルをテストせずに複数のスキルを一括作成すること
• 現在のスキルが検証される前に次のスキルに進むこと
• 「バッチ処理の方が効率的だから」という理由でテストを省略すること

以下のデプロイチェックリストは、各スキルごとに必須です。

テストされていないスキルをデプロイすること = テストされていないコードをデプロイすること。これは品質基準への違反です。

スキル作成チェックリスト (TDD に準拠)

重要: 以下の各チェックリスト項目に対して、TodoWrite を使って todo を作成してください。

RED フェーズ - 失敗するテストを書く:

• プレッシャーシナリオを作成する (規律スキルの場合は 3 つ以上の複合的なプレッシャー)
• スキルなしでシナリオを実行する - ベースラインの動作をそのまま記録する
• 正当化や失敗のパターンを特定する

GREEN フェーズ - 最小限のスキルを書く:

• 名前には英字、数字、ハイフンのみを使用する (かっこや特殊文字は使わない)
• YAML フロントマターには name と description のみを含める (最大 1024 文字)
• description は「Use when...」で始め、具体的なトリガーや症状を含める
• description は三人称で書く
• 検索用のキーワードを随所に含める (エラー、症状、ツール)
• 核心となる原則を明確にした概要を書く
• RED で特定した具体的なベースラインの失敗に対処する
• コードをインラインで書くか、別ファイルへのリンクを付ける
• 優れた例を 1 つ示す (多言語ではない)
• スキルありでシナリオを実行する - エージェントが準拠するようになったことを検証する

REFACTOR フェーズ - 抜け穴をふさぐ:

• テストから新たな正当化を特定する
• 明示的な反論を追加する (規律スキルの場合)
• すべてのテスト反復から正当化の表を作成する
• レッドフラグのリストを作成する
• 完全になるまで再テストする

品質チェック:

• 判断が自明でない場合に限り、小さなフローチャートを作成する
• クイックリファレンス表を用意する
• よくある間違いのセクションを設ける
• 物語形式の説明は書かない
• 補助ファイルはツールや分量の多いリファレンスに限る

デプロイ:

• スキルを git にコミットし、自分のフォークにプッシュする (設定されている場合)
• PR を通じてコントリビュートすることを検討する (広く役立つ場合)

発見のワークフロー

将来の Claude があなたのスキルを見つける流れ:

1. 問題に遭遇する (「テストが不安定」)
2. SKILL を見つける (description が一致する)
3. 概要をざっと読む (これは関連しているか？)
4. パターンを読む (クイックリファレンス表)
5. 例を読み込む (実装するときのみ)

この流れに最適化する - 検索可能な用語を早い段階で、頻繁に配置してください。

結論

スキルの作成は、プロセスドキュメントのための TDD です。

同じ鉄の掟: 失敗するテストなしにスキルは作らない。 同じサイクル: RED (ベースライン) → GREEN (スキルを書く) → REFACTOR (抜け穴をふさぐ)。 同じ利点: より高い品質、より少ない驚き、完全な結果。

コードで TDD を実践しているなら、スキルでも実践してください。ドキュメントに適用する同じ規律です。

スキル作成プロセス

スキルを作成するには、「スキル作成プロセス」に従って順番に進めてください。適用できない明確な理由がある場合にのみ、ステップを省略してください。

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

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

効果的なスキルを作成するには、そのスキルがどのように使われるか、具体例を通じて明確に理解してください。この理解は、ユーザーから直接提供された例、またはユーザーのフィードバックで検証された生成例から得られます。

たとえば、画像エディター用のスキルを作成する場合、次のような質問が役立ちます。

• 「画像エディター用のスキルでは、どのような機能をサポートすべきですか？編集や回転のほかに、何かありますか？」
• 「このスキルの使用例をいくつか教えてもらえますか？」
• 「『この画像の赤目を補正して』や『この画像を回転して』のような依頼があると思います。このほかに、どのような使い方が考えられますか？」
• 「どのような依頼をきっかけに、このスキルを起動すべきですか？」

ユーザーに負担をかけないよう、1つのメッセージで質問しすぎないでください。まず重要な質問から始め、必要に応じて効果を高めるための質問を続けてください。

スキルがサポートすべき機能を明確に理解できたら、このステップを終了します。

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

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

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

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

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

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

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

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

1. BigQuery にクエリを実行するには、毎回テーブルのスキーマや関連性を調べ直す必要がある
2. テーブルのスキーマを記載した references/schema.md ファイルをスキルに保存すると役立つ

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

ステップ 3：スキルディレクトリを作成する

スキルがすでに存在し、反復的な改善だけが必要な場合は、このステップを省略してください。

スキルディレクトリと必要なファイルを作成します。

1. スキルフォルダーを作成します：mkdir -p skills/<skill-name>
2. YAML フロントマターを含む SKILL.md を作成します。

---
name: skill-name
description: Use when [triggering conditions] - [what the skill does]
---

# Skill Name

## Critical Guidlines
[Core principle in 1-2 sentences. Each start wit "You MUST ..."]

## How to Use
[Think in steps, use problem decomposition, etc.]

## Guide
[Procedures, patterns]

## Examples
[Examples of how to use the skill, include agent input and output]

## Troubleshooting
[Common mistakes and how to avoid them]

## Resources
[Scripts, references, assets]

3. 必要な場合にのみ、リソース用のサブディレクトリを追加します。
   • scripts/ — 再利用可能な実行コード
   • references/ — 必要に応じて読み込むドキュメント
   • assets/ — 出力に使用するファイル（テンプレート、画像）

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

新規作成したスキルでも既存のスキルでも、編集時には、そのスキルが別の Claude インスタンスによって使われることを念頭に置いてください。Claude にとって有益で、自明ではない情報を含めることに重点を置きます。別の Claude インスタンスがタスクをより効果的に実行するうえで役立つ手順に関する知識、ドメイン固有の詳細、再利用可能なアセットを検討してください。

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

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

スキルに不要なリソース用サブディレクトリは削除してください。ほとんどのスキルで必要なのは SKILL.md のみです。

SKILL.md を更新する

文体: スキル全体を 命令形/不定形 (動詞から始まる指示) で記述し、二人称は使用しないでください。客観的で指示的な言葉遣いを用います (例: 「X を実行するには、Y を行います」とし、「X を行うべきです」や「X を行う必要がある場合は」とはしません)。これにより、AI が利用する際の一貫性と明確さが保たれます。

SKILL.md を完成させるには、次の質問に答えてください:

1. このスキルの目的は何ですか? 数文で説明してください。
2. このスキルはどのようなときに使用すべきですか?
3. 実際に、Claude はこのスキルをどのように使用すべきですか? 上記で作成した再利用可能なスキルの内容をすべて参照し、Claude がそれらを使用する方法を理解できるようにしてください。

ステップ 5: スキルを検証する

デプロイする前に、スキルが要件を満たしていることを確認します:

1. Frontmatter — YAML には name と description のみが含まれている (合計最大 1024 文字)
2. Name — 文字、数字、ハイフンのみを使用している
3. Description — 「Use when...」で始まり、三人称で記述され、具体的なトリガーが含まれている
4. Structure — SKILL.md が skills/<skill-name>/SKILL.md に存在する
5. Resources — 参照されているスクリプト、リファレンス、アセットが、宣言されたパスに存在する

ステップ 6: 反復する

スキルをテストした後、ユーザーは改善を求めることがあります。多くの場合、これはスキルを使用した直後に、スキルがどのように機能したかについての新しいコンテキストとともに発生します。

反復ワークフロー:

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