capability-documentation

スキルの作成

概要

スキルの作成は、プロセス文書に適用されたテスト駆動開発そのものです。

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

テストケース（サブエージェントを使った圧力シナリオ）を書き、失敗するのを確認し（ベースライン動作）、スキル（ドキュメント）を書き、テストが通るのを確認し（エージェントが従う）、リファクタリングします（抜け穴を塞ぐ）。

中心原則: スキルなしでエージェントが失敗する様子を確認していなければ、そのスキルが正しいことを教えているかどうかはわかりません。

必須の前提知識: このスキルを使う前に、superpowers:test-driven-development を理解している必要があります。そのスキルは、RED-GREEN-REFACTOR という基本サイクルを定義しています。本スキルは、そのTDDをドキュメント作成向けに適合させたものです。

公式ガイダンス: Anthropic 公式のスキル作成ベストプラクティスについては、anthropic-best-practices.md を参照してください。本ドキュメントは、TDD に重点を置いた本スキルのアプローチを補完する追加のパターンとガイドラインを提供します。

スキルとは

スキルとは、実証済みの技法、パターン、またはツールについての参照ガイドです。スキルは、将来の Claude インスタンスが効果的なアプローチを見つけて適用する助けになります。

スキルであるもの: 再利用可能な技法、パターン、ツール、参照ガイド

スキルではないもの: 過去にある問題をどう解決したかの体験談

スキル作成のための 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. 詳細な参照資料（100 行以上）- API ドキュメント、包括的な構文
2. 再利用可能なツール - スクリプト、ユーティリティ、テンプレート

インラインに残すもの:

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

SKILL.md の構造

フロントマター（YAML）:

• サポートされているフィールドは name と description の 2 つのみ
• 合計最大 1024 文字
• name: 文字、数字、ハイフンのみを使用（括弧や特殊文字は不可）
• description: 三人称で、使用するタイミングのみを記述（何をするかは記述しない）
  • 発動条件に焦点を当てるため「Use when...」で始める
  • 具体的な症状、状況、コンテキストを含める
  • スキルのプロセスやワークフローを決して要約しない（理由は CSO セクションを参照）
  • 可能であれば 500 文字未満に抑える

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

# 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

Claude 検索最適化（CSO）

発見のために重要: 将来の Claude が、あなたのスキルを見つけられる必要があります

1. 詳細な description フィールド

目的: Claude は description を読んで、特定のタスクでどの skills を読み込むかを判断します。「今このskillを読むべきか？」に答えられる内容にしてください。

形式: トリガー条件に焦点を当てるため、「Use when...」で始めてください。

重要: Description = いつ使うか。skill が何をするかではない

description には、トリガー条件だけを記述してください。description で skill のプロセスやワークフローを要約しないでください。

これが重要な理由: テストの結果、description が skill のワークフローを要約している場合、Claude は完全な skill の内容を読まずに description に従ってしまう可能性があることが分かりました。「タスク間のコードレビュー」という description では、skill のフローチャートには2回のレビュー（まず仕様準拠、次にコード品質）が明確に示されていたにもかかわらず、Claude は1回しかレビューを行いませんでした。

description を「Use when executing implementation plans with independent tasks」（ワークフローの要約なし）だけに変更すると、Claude はフローチャートを正しく読み、2段階のレビュープロセスに従いました。

落とし穴: ワークフローを要約する description は、Claude が近道として使ってしまう原因になります。すると skill 本体は、Claude が読み飛ばすだけのドキュメントになってしまいます。

# ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ❌ BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# ✅ GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

# ✅ GOOD: Triggering conditions only
description: Use when implementing any feature or bugfix, before writing implementation code

内容:

• このskillが適用されることを示す、具体的なトリガー、症状、状況を記述する
• 言語固有の症状（setTimeout、sleep）ではなく、問題（race condition、動作の不一致）を記述する
• skill自体が技術固有でない限り、トリガーは技術に依存しない形に保つ
• skillが技術固有の場合は、そのことをトリガー内で明示する
• 三人称で記述する（system prompt に注入されるため）
• skill のプロセスやワークフローを決して要約しない

# ❌ 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, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# ✅ GOOD: Technology-specific skill with explicit trigger
description: Use when using React Router and handling authentication redirects

2. キーワードの網羅

Claude が検索しそうな語を使ってください:

• エラーメッセージ: "Hook timed out", "ENOTEMPTY", "race condition"
• 症状: "flaky", "hanging", "zombie", "pollution"
• 類義語: "timeout/hang/freeze", "cleanup/teardown/afterEach"
• ツール: 実際のコマンド、ライブラリ名、ファイルタイプ

3. 分かりやすい命名

能動態で、動詞から始めてください:

• ✅ creating-skills （skill-creation ではなく）
• ✅ condition-based-waiting （async-test-helpers ではなく）

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

問題: getting-started や頻繁に参照される skills は、すべての会話に読み込まれます。すべてのトークンが重要です。

目標の語数:

• getting-started のワークフロー: 各 150 語未満
• 頻繁に読み込まれる skills: 合計 200 語未満
• その他の skills: 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]

冗長さを排除する:

• 相互参照先の skills に既に書かれていることは繰り返さない
• コマンドから明らかなことは説明しない
• 同じパターンの例を複数入れない

検証:

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. 他の skills への相互参照

他の skills を参照するドキュメントを書く場合:

skill 名だけを使い、明示的な必須マーカーを付けてください:

• ✅ 良い例: **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 を参照してください。

人間のパートナーに向けた可視化: このディレクトリにある render-graphs.js を使うと、スキルのフローチャートを SVG にレンダリングできます:

./render-graphs.js ../some-skill           # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVG

コード例

優れた例を1つ示す方が、平凡な例を多数示すより効果的です

最も関連性の高い言語を選んでください:

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

良い例の条件:

• 完全で、そのまま実行できる
• なぜそうするのかを説明する、わかりやすいコメントがある
• 実際のシナリオから得られたものである
• パターンを明確に示している
• そのまま応用できる（汎用的なテンプレートではない）

避けるべきこと:

• 5つ以上の言語で実装する
• 穴埋め式のテンプレートを作る
• 作為的な例を書く

移植作業には長けているので、優れた例を1つ示せば十分です。

ファイルの構成

自己完結型のスキル

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 と同じ）

NO SKILL WITHOUT A FAILING TEST FIRST

これは、新規のスキルと既存スキルへの編集の両方に適用されます。

テストする前にスキルを書いてしまったら、削除してください。最初からやり直してください。 テストせずにスキルを編集するのも、同じ違反です。

例外は一切ありません:

• 「単純な追加」だからといって例外にはしない
• 「セクションを1つ足すだけ」だからといって例外にはしない
• 「ドキュメントの更新」だからといって例外にはしない
• 未テストの変更を「参考として」残しておかない
• テストを実行しながら「適応させる」ことをしない
• 削除とは、本当に削除することを意味する

必読の背景: superpowers:test-driven-development スキルで、これが重要な理由を説明しています。同じ原則はドキュメントにも当てはまります。

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

スキルの種類によって、必要なテストのアプローチは異なります。

規律を強制するスキル（ルール・要件）

例: TDD、verification-before-completion、designing-before-coding

テスト方法:

• 学術的な質問: ルールを理解しているか？
• プレッシャーのシナリオ: ストレス下でもルールに従うか？
• 複数のプレッシャーの組み合わせ: 時間 + サンクコスト + 疲労
• 合理化の仕方を特定し、明示的な反論を追加する

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

技法スキル（ハウツーガイド）

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

テスト方法:

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

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

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

例: reducing-complexity、information-hiding の概念

テスト方法:

• 認識のシナリオ: パターンが適用される場面を認識できるか？
• 適用のシナリオ: メンタルモデルを使えるか？
• 反例: 適用すべきでない場面を理解しているか？

成功基準: エージェントがパターンを適用すべき時と方法を正しく特定する

リファレンススキル（ドキュメント・API）

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

テスト方法:

• 検索のシナリオ: 適切な情報を見つけられるか？
• 適用のシナリオ: 見つけた情報を正しく使えるか？
• ギャップのテスト: よくあるユースケースがカバーされているか？

成功基準: エージェントがリファレンス情報を見つけ、正しく適用する

スキップを正当化する一般的な言い訳

言い訳	実際
"Skill is obviously clear"	あなたにとって明確でも、他のエージェントにとって明確とは限りません。テストしてください。
"It's just a reference"	リファレンスにも抜けや不明瞭なセクションがあり得ます。検索結果をテストしてください。
"Testing is overkill"	テストされていないスキルには、例外なく問題があります。15分のテストが数時間の手戻りを防ぎます。
"I'll test if problems emerge"	問題とは、エージェントがスキルを使えないことです。デプロイの前にテストしてください。
"Too tedious to test"	テストの手間は、本番環境で不良なスキルをデバッグする手間よりも小さいものです。
"I'm confident it's good"	過信は必ず問題を生みます。それでもテストしてください。
"Academic review is enough"	読むことと使うことは別物です。適用シナリオをテストしてください。
"No time to test"	テストされていないスキルをデプロイすると、後から修正するためにさらに多くの時間が無駄になります。

これらはすべて次の意味です: デプロイ前に必ずテストしてください。例外はありません。

合理化に対してスキルを強化する

規律を強制するスキル（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.**

これにより、「精神に従っている」という類の合理化のほぼすべてを封じられます。

合理化テーブルを作成する

ベースラインテスト（後述の Testing セクションを参照）で得られた合理化を記録してください。エージェントが口にするすべての言い訳をテーブルに入れます:

| 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 に、ルールを破ろうとしている時の兆候を追加してください:

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

スキルのための RED-GREEN-REFACTOR

TDD のサイクルに従ってください:

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

スキルなしのサブエージェントでプレッシャーシナリオを実行し、正確な振る舞いを記録してください:

• どのような選択をしたか？
• どのような合理化を（一字一句そのまま）使ったか？
• どのプレッシャーが違反を引き起こしたか？

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

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

それら特定の合理化に対処するスキルを書いてください。仮定上のケースのために余計な内容を追加しないでください。

同じシナリオをスキルありで実行します。エージェントが今度は従うはずです。

REFACTOR: 抜け道を塞ぐ

エージェントが新しい合理化を見つけたら、明示的な反論を追加してください。完璧になるまで再テストしてください。

テスト方法論: 完全なテスト方法論については @testing-skills-with-subagents.md を参照してください:

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

アンチパターン

❌ 物語的な例

「セッション 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 問題点: ラベルには意味的な内容があるべきです

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

スキルを 1 つでも書いたら、必ず立ち止まり、デプロイの手順を完了させなければなりません。

次のことをしないでください:

• 各スキルをテストせずに、まとめて複数のスキルを作成する
• 現在のスキルの検証が終わる前に、次のスキルに進む
• 「まとめて作業する方が効率的」という理由でテストを省く

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

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

スキル作成チェックリスト（TDD 版）

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

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

• プレッシャーシナリオを作成する（規律系スキルの場合は 3 つ以上のプレッシャーを組み合わせる）
• スキルなしでシナリオを実行し、ベースラインの動作を一字一句そのまま記録する
• 合理化や失敗のパターンを特定する

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

• 名前には文字、数字、ハイフンのみを使用する（括弧や特殊文字は不可）
• YAML フロントマターには name と description のみを記載する（description は最大 1024 文字）
• description は「Use when...」で始まり、具体的なトリガーや症状を含める
• description は三人称で書く
• 検索用に、エラー、症状、ツールなどのキーワードを全体に散りばめる
• 中核となる原則を含む、明確な概要を書く
• RED フェーズで特定したベースラインの失敗に対処する
• コードはインラインで書くか、別ファイルへのリンクにする
• 優れた例を 1 つだけ載せる（複数言語にはしない）
• スキルありでシナリオを実行し、エージェントが now 従うことを確認する

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

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

品質チェック:

• 判断が自明でない場合にのみ小さなフローチャートを使う
• クイックリファレンス表を用意する
• よくある間違いのセクションを設ける
• 物語的な記述は含めない
• 補助ファイルはツールや大量のリファレンスがある場合にのみ用意する

デプロイ:

• スキルを git にコミットし、（設定されている場合は）自分のフォークにプッシュする
• 広く役立つ場合は、PR で還元することを検討する

発見のワークフロー

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

1. 問題に遭遇する（「テストが不安定だ」など）
2. SKILL を見つける（description が一致する）
3. 概要を確認する（関連性があるか？）
4. パターンを読む（クイックリファレンス表）
5. 例を読み込む（実装するときだけ）

この流れに最適化する - 検索可能な用語を早い段階で、かつ繰り返し配置しましょう。

結論

スキルを作成することは、プロセス文書化における TDD である。

同じ鉄則: テストが失敗するまでスキルは作らない。 同じサイクル: RED（ベースライン）→ GREEN（スキルを書く）→ REFACTOR（抜け穴を塞ぐ）。 同じ利点: 品質の向上、驚きの減少、堅牢な結果。

コードに TDD を適用するなら、スキルにも適用しましょう。同じ規律を文書作成に適用するものです。