スキルの作成

概要

スキルの作成は、プロセスドキュメンテーションに適用されたテスト駆動開発です。

個人のスキルはエージェント固有のディレクトリに保存されます (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              # メインリファレンス (必須)
    supporting-file.*     # 必要な場合のみ

フラットな名前空間 - すべてのスキルが1つの検索可能な名前空間内

別ファイルとする対象：

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

インラインのままとする：

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

SKILL.mdの構造

フロントマター (YAML):

• サポートされるフィールドは2つのみ: name と description
• 合計で最大1024文字
• name: 文字、数字、ハイフンのみを使用（括弧や特殊文字なし）
• description: 三人称、使用する場合のみを記述（何をするかではない）
  • 「Use when...」で始めてトリガー条件に焦点を当てる
  • 特定の症状、状況、文脈を含める
  • スキルのプロセスやワークフローを要約しない（理由についてはCSOセクションを参照）
  • 可能な限り500文字以下に保つ

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

# スキル名

## 概要
これは何か。核となる原則を1〜2文で。

## 使用時期
[意思決定が明らかでない場合は小さなインラインフローチャート]

症状とユースケースを含むリスト
使用しない場合

## 核となるパターン (テクニック/パターンの場合)
変更前/変更後のコード比較

## クイックリファレンス
スキャン用のテーブルまたは箇条書き

## 実装
シンプルなパターン用のインラインコード
大量のリファレンスまたは再利用可能なツール用のファイルへのリンク

## よくある間違い
何が間違っているか + 修正

## 実際の影響 (オプション)
具体的な結果

Claude検索最適化 (CSO)

発見にとって重要： 将来のClaudeがあなたのスキルを見つける必要があります

1. リッチな説明フィールド

目的： Claudeは説明を読んでタスク用にどのスキルをロードするか決定します。「このスキルを今すぐ読むべきか？」という質問に答えます。

形式： 「Use when...」で始めてトリガー条件に焦点を当てる

重要: 説明 = 使用時期、スキルの内容ではない

説明はトリガー条件のみを記述する必要があります。スキルのプロセスやワークフローを要約しないでください。

これが重要な理由： テストで、説明がスキルのワークフローを要約する場合、Claudeはスキルの完全な内容を読む代わりに説明に従う可能性があることが明らかになりました。「タスク間でコードレビューを行う」という説明は、スキルのフローチャートが2つのレビュー（仕様準拠と分析品質）を明確に示していたのに、Claudeに1つのレビューを行わせました。

説明が「独立したタスクを使用した実装計画を実行する場合に使用」（ワークフロー要約なし）に変更されたとき、Claudeは正しくフローチャートを読んで2段階のレビュープロセスに従いました。

罠： ワークフローを要約する説明は、Claudeが取る近道を作成します。スキルの本体はClaudeがスキップするドキュメンテーションになります。

# ❌ 悪い: ワークフローを要約 - Claudeはスキル全体を読む代わりにこれに従う可能性
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ❌ 悪い: プロセスの詳細が多すぎる
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# ✅ 良い: トリガー条件のみ、ワークフロー要約なし
description: Use when executing implementation plans with independent tasks in the current session

# ✅ 良い: トリガー条件のみ
description: Use when implementing any feature or bugfix, before writing implementation code

内容：

• 具体的なトリガー、症状、このスキルが適用されることを示す状況を使用
• 言語固有の症状（setTimeout、sleep）ではなく、問題（レースコンディション、動作の一貫性がない）を記述
• スキル自体が技術固有でない限り、トリガーを技術中立的に保つ
• スキルが技術固有の場合、トリガーでそれを明示的にする
• 三人称で書く（システムプロンプトに注入される）
• スキルのプロセスやワークフローを要約しない

# ❌ 悪い: 抽象的すぎて、曖昧で、使用時期を含まない
description: For async testing

# ❌ 悪い: 一人称
description: I can help you with async tests when they're flaky

# ❌ 悪い: テクノロジーについて言及しているが、スキルはそれに固有ではない
description: Use when tests use setTimeout/sleep and are flaky

# ✅ 良い: 「Use when」で始まり、問題を記述し、ワークフローなし
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# ✅ 良い: 技術固有のスキルで明示的なトリガー
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と頻繁に参照されるスキルがすべての会話にロードされます。すべてのトークンが重要です。

目標単語数：

• getting-startedワークフロー: 各150語以下
• 頻繁にロードされるスキル: 合計200語以下
• その他のスキル: 500語以下（簡潔であること）

テクニック：

詳細をツールヘルプに移動：

# ❌ 悪い: SKILL.mdですべてのフラグを文書化
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ 良い: --helpを参照
search-conversations supports multiple modes and filters. Run --help for details.

相互参照を使用：

# ❌ 悪い: ワークフロー詳細を繰り返す
When searching, dispatch subagent with template...
[20行の繰り返された指示]

# ✅ 良い: 別のスキルを参照
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

例を圧縮：

# ❌ 悪い: 冗長な例 (42語)
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"]

# ✅ 良い: 最小例 (20語)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]

冗長性を排除：

• 相互参照スキルに既に記載されているものを繰り返さない
• コマンドから明白なものを説明しない
• 同じパターンの複数の例を含めない

検証：

wc -w skills/path/SKILL.md
# getting-startedワークフロー: 各150語以下を目指す
# その他の頻繁にロードされる: 合計200語以下を目指す

何をするか、または核となる洞察で命名：

• ✅ 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 {
    "情報を表示する必要があるか?" [shape=diamond];
    "間違える可能性のある決定か?" [shape=diamond];
    "Markdownを使用" [shape=box];
    "小さなインラインフローチャート" [shape=box];

    "情報を表示する必要があるか?" -> "間違える可能性のある決定か?" [label="yes"];
    "間違える可能性のある決定か?" -> "小さなインラインフローチャート" [label="yes"];
    "間違える可能性のある決定か?" -> "Markdownを使用" [label="no"];
}

フローチャートを使用する場合：

• 明らかではない意思決定ポイント
• 途中で止まる可能性があるプロセスループ
• 「AとBのどちらを使用するか」の決定

フローチャートを使用しない場合：

• リファレンス資料 → テーブル、リスト
• コード例 → Markdownブロック
• 線形の指示 → 番号付きリスト
• セマンティック意味のないラベル (step1、helper2)

スタイルルールについては @graphviz-conventions.dot を参照してください。

人間のパートナー向けに可視化： このディレクトリの render-graphs.js を使用してスキルのフローチャートをSVGにレンダリング：

./render-graphs.js ../some-skill           # 各ダイアグラムを個別に
./render-graphs.js ../some-skill --combine # 1つのSVGにすべてのダイアグラム

コード例

複数の平凡な例より1つの優れた例

最も関連性の高い言語を選択：

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

良い例：

• 完全で実行可能
• なぜかを説明する良いコメント
• 実際のシナリオから
• パターンを明確に示す
• 適応する準備ができている（汎用テンプレートではない）

しないこと：

• 5言語以上で実装する
• 穴埋めテンプレートを作成する
• でっち上げた例を書く

ポーティングが得意です。1つの優れた例で十分です。

ファイル編成

自己完結型スキル

defense-in-depth/
  SKILL.md    # すべてインライン

対象： すべてのコンテンツが適応し、大量のリファレンスが不要

再利用可能なツール付きスキル

condition-based-waiting/
  SKILL.md    # 概要 + パターン
  example.ts  # 適応するワーキングヘルパー

対象： ツールは再利用可能なコード、ナラティブだけではない

大量のリファレンス付きスキル

pptx/
  SKILL.md       # 概要 + ワークフロー
  pptxgenjs.md   # 600行のAPIリファレンス
  ooxml.md       # 500行のXML構造
  scripts/       # 実行可能なツール

対象： リファレンス資料がインラインには大きすぎる

アイアンロー (TDDと同じ)

失敗するテストなしのスキルはない

これは新しいスキルとも既存スキルの編集にも適用されます。

テストなしでスキルを書く? 削除してください。もう一度開始します。 テストなしでスキルを編集する? 同じ違反です。

例外なし：

• 「簡単な追加」のためではない
• 「セクションを追加するだけ」のためではない
• 「ドキュメンテーション更新」のためではない
• テストされていない変更を「参照」として保持しない
• テストを実行しながら「適応」しない
• 削除は削除を意味します

必須背景知識： 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ドキュメント、コマンドリファレンス、ライブラリガイド

テスト対象：

• 取得シナリオ: 正しい情報を見つけられるか?
• 適用シナリオ: 見つけた情報を正しく使用できるか?
• ギャップテスト: 一般的なユースケースがカバーされているか?

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

テスト省略の一般的な正当化

言い訳	現実
「スキルは明らかに明確」	あなたには明確 ≠ 他のエージェントには明確。テストしてください。
「これはただのリファレンス」	リファレンスにはギャップがある可能性があります。取得をテストしてください。
「テストはやり過ぎ」	テストされていないスキルには常に問題があります。15分のテストで何時間も節約。
「問題が出てきたらテストする」	問題 = エージェントはスキルを使用できない。デプロイ前にテストしてください。
「テストするのが面倒」	テストするのは本番環境の悪いスキルのデバッグよりも面倒ではありません。
「それが良いか確信している」	過信は問題を保証します。とにかくテストしてください。
「アカデミックレビューで十分」	読む ≠ 使用。適用シナリオをテストしてください。
「テストする時間がない」	テストされていないスキルをデプロイすることはその後の修正に多くの時間を無駄にします。

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

正当化に対するスキルの防弾

規律を強制するスキル（TDDなど）はプレッシャー下でエージェントが正当化を見つけるときにループホールに抵抗する必要があります。

心理学的注釈： 説得テクニックなぜ機能するかを理解することは、それらを体系的に適用するのに役立ちます。persuasion-principles.md を参照（Cialdini、2021; Meincke等、2025）権威、約束、希少性、社会的証拠、統一原則について。

すべてのループホールを明示的に塞ぐ

ルールを述べるだけではなく、特定の回避策を禁止してください：

<Bad> ```markdown テスト前にコードを書く? 削除します。 ``` </Bad> <Good> ```markdown テスト前にコードを書く? 削除してください。最初からやり直してください。

例外なし：

• 「参照」として保持しない
• テストを書く間に「適応」しない
• それを見ない
• 削除は削除を意味します

</Good>

### 「スピリット対文字」の議論に対処

原則を早期に追加してください：

```markdown
**ルールの文字に違反することはルールのスピリットに違反することです。**

これは「スピリットに従っている」という正当化のクラス全体を遮断します。

正当化テーブルを構築

ベースラインテストから正当化をキャプチャしてください（下記のテストセクション参照）。エージェントが行うすべての言い訳はテーブルに入ります：

| 言い訳 | 現実 |
|--------|---------|
| 「テストするには単純すぎる」 | シンプルなコードは壊れます。テストは30秒かかります。 |
| 「その後テストする」 | テストが直後に成功することは何も証明しません。 |
| 「テスト後は同じ目標を達成」 | テスト後 = 「これは何をするか?」 テスト先 = 「これは何をすべきか?」 |

赤旗リストを作成

エージェントが正当化しているときに自己チェックするのを簡単にしてください：

## 赤旗 - 停止して最初からやり直す

- テスト前のコード
- 「すでに手動でテストしました」
- 「テスト後は同じ目的を達成」
- 「スピリットについてであり儀式ではない」
- 「これは異なる理由で...」

**これらはすべて意味します：** コードを削除します。TDDで最初からやり直してください。

CSO を違反症状向けに更新

説明に追加：ルールを違反しようとしているときの症状：

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 なぜ悪いのか： ラベルはセマンティック意味を持つべき

停止：次のスキルに移動する前に

スキルを書いた後、デプロイメントプロセスを完了する必要があります。

しないこと：

• テストなしで複数のスキルをバッチで作成する
• 現在のスキルが検証される前に次のスキルに移動
• 「バッチ処理の方が効率的」だからテストをスキップ

下記のデプロイメントチェックリストは各スキルについて必須です。

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

スキル作成チェックリスト (TDD適用)

重要：以下の各チェックリスト項目についてTodoWriteを使用してTodoを作成してください。

RED段階 - 失敗するテストを書く：

• 圧力シナリオを作成（規律スキルの場合は3種類以上の組み合わせ圧力）
• スキルなしでシナリオを実行 - ベースライン動作を逐語的に文書化
• 正当化/失敗のパターンを特定

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

• 名前は文字、数字、ハイフンのみを使用（括弧/特殊文字なし）
• 名前と説明のみを含むYAMLフロントマター（最大1024文字）
• 説明は「Use when...」で始まり、特定のトリガー/症状を含む
• 説明は三人称で書かれている
• 検索用のキーワードが全体を通じて
• 核となる原則を含む明確な概要
• RED で特定された特定のベースライン失敗に対処
• コードはインラインまたは別ファイルへのリンク
• 1つの優れた例（多言語ではない）
• スキル付きでシナリオを実行 - エージェントが確実に従うことを確認

REFACTOR段階 - ループホールを塞ぐ：

• テストから新しい正当化を特定
• 明示的なカウンターを追加（規律スキルの場合）
• すべてのテスト反復から正当化テーブルを構築
• 赤旗リストを作成
• 完璧になるまで再テスト

品質チェック：

• 小さなフローチャート（意思決定が明らかでない場合のみ）
• クイックリファレンステーブル
• よくある間違いセクション
• ナラティブストーリーテリングなし
• サポートファイルはツールまたは大量のリファレンスのみ

デプロイメント：

• gitにスキルをコミットしてフォークにプッシュ（設定されている場合）
• 広く有用な場合はPRを通じた貢献を検討

発見ワークフロー

将来のClaudeがスキルをどのように見つけるか：

1. 問題に遭遇 (「テストがflaky」)
2. スキルを見つける (説明が一致)
3. 概要をスキャン (これは関連しているか?)
4. パターンを読む (クイックリファレンステーブル)
5. 例をロード (実装時のみ)

このフローを最適化する - 検索可能な用語を早期かつ頻繁に配置。

要点

スキルの作成はプロセスドキュメンテーション用のTDDです。

同じアイアンロー: テストなしのスキルはない。 同じサイクル: RED (ベースライン) → GREEN (スキルを書く) → REFACTOR (ループホールを塞ぐ)。 同じメリット: より良い品質、驚きが少ない、防弾の結果。

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