Writing Skills

スキルの作成

概要

スキルの作成は、プロセスのドキュメント化に適用するテスト駆動開発です。

スキルは ${SUPERPOWERS_SKILLS_ROOT}（~/.config/superpowers/skills/ にクローンされます）に書き込みます。 このリポジトリのローカルブランチでスキルを編集します。

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

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

基本となる RED-GREEN-REFACTOR サイクルについては、skills/testing/test-driven-development を参照してください。このスキルでは、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）

ディレクトリ構造

すべてのスキルは ${SUPERPOWERS_SKILLS_ROOT} のスキルリポジトリにあります：

${SUPERPOWERS_SKILLS_ROOT}
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed

フラットな名前空間 - すべてのスキルを、検索しやすい1か所にまとめます

次のものは別ファイルに分けます：

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

以下はインラインにします：

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

SKILL.md の構成

---
name: Human-Readable Name
description: One-line summary of what this does
when_to_use: when [trigger/situation]
version: 5.1.0
languages: all | [typescript, python] | etc
dependencies: (optional) Required tools/libraries
---

# 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. 充実した when_to_use

目的： Claude は when_to_use を読んで、特定のタスクでどのスキルを読み込むかを判断します。「今このスキルを読むべきか？」に答えられるようにしてください。

形式： 「when」で始め、「Use [skill-path] when [your text]」を完成させます。

内容：

• このスキルが役立つことを示す、具体的なきっかけ、症状、状況を使います
• 言語固有の症状（setTimeout、sleep）ではなく、問題（競合状態、一貫性のない動作）を説明します
• スキル自体が特定の技術に限定されない限り、きっかけは技術に依存しないものにします
• スキルが特定の技術に限定される場合は、きっかけの中で明示します

# ❌ BAD: Too abstract, doesn't start with "when"
when_to_use: For async testing

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

# ✅ GOOD: Starts with "when", describes problem not language symptom
when_to_use: when tests have race conditions, timing dependencies, or pass/fail inconsistently

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

find-skills の出力例：

Use skills/testing/condition-based-waiting/SKILL.md when tests have race conditions, timing dependencies, or pass/fail inconsistently

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). See skills/using-skills 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. 内容の繰り返し

重要な概念を複数回記載します：

• 説明
• when_to_use
• 概要
• セクション見出し

複数の場所で grep にヒットすると、見つけやすくなります。

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

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

@ プレフィックスと /SKILL.md 接尾辞を付けずにパス形式を使います：

• ✅ 推奨：skills/testing/test-driven-development
• ✅ 推奨：skills/debugging/systematic-debugging
• ❌ 非推奨：@skills/testing/test-driven-development/SKILL.md（強制読み込みにより、コンテキストを消費します）

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

スキルの参照先を読むには： ${SUPERPOWERS_SKILLS_ROOT}/category/skill-name/SKILL.md に対して Read ツールを使います。

フローチャートの使用

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

良い例：

• 完全で、実行できる
• 理由を説明するコメントが十分にある
• 実際のシナリオに基づいている
• パターンが明確に示されている
• 汎用的なテンプレートではなく、すぐに応用できる

避けること：

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

NO SKILL WITHOUT A FAILING TEST FIRST

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

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

例外はありません：

• 「簡単な追加」でも例外ではありません
• 「セクションを追加するだけ」でも例外ではありません
• 「ドキュメントの更新」でも例外ではありません
• テストしていない変更を「参考用」として残さない
• テストの実行中に「調整」しない
• 削除とは、削除することです

これが重要な理由については、skills/testing/test-driven-development を参照してください。同じ原則がドキュメントにも適用されます。

すべての種類のスキルをテストする

スキルの種類によって、適切なテスト方法は異なります。

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

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

次の点をテストします：

• 学術的な質問：ルールを理解しているか？
• プレッシャーのかかる状況：ストレス下でもルールに従うか？
• 複数のプレッシャーが重なる状況：時間＋サンクコスト＋疲労
• 合理化を特定し、明確な反論を追加する

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

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

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

次の点をテストします：

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

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

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

例： 複雑さの軽減、情報隠蔽の概念

次の点をテストします：

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

成功基準： エージェントがパターンを適用するタイミングと方法を正しく判断する

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

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

次の点をテストします：

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

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

テストを省略する際によくある合理化

言い訳	実際
"スキルは明らかに分かりやすい"	あなたに分かりやすくても、他のエージェントにも分かりやすいとは限りません。テストしてください。
"単なるリファレンスです"	リファレンスにも抜けや分かりにくい箇所があることがあります。検索をテストしてください。
"テストはやりすぎです"	テストしていないスキルには必ず問題があります。必ずテストしてください。15 分のテストで何時間もの作業を節約できます。
"問題が出たらテストします"	問題とは、エージェントがスキルを使えないことです。デプロイする前にテストしてください。
"テストは面倒すぎます"	本番環境で質の悪いスキルをデバッグするより、テストのほうが面倒ではありません。
"良いものだと確信しています"	過信すれば問題は必ず起きます。それでもテストしてください。
"学術的なレビューで十分です"	読むことと使うことは違います。適用シナリオをテストしてください。
"テストする時間がありません"	テストせずにデプロイすると、後で修正するためにさらに時間がかかります。

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

合理化に負けないスキルを作る

規律を徹底させるスキル（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 を更新する

ルールに違反しようとしている兆候を when_to_use に追加します：

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

スキルの RED-GREEN-REFACTOR

TDD サイクルに従います：

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

スキルを与えずにサブエージェントでプレッシャーシナリオを実施します。実際の動作を正確に記録してください：

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

これは「テストが失敗するのを見届ける」段階です。スキルを書く前に、エージェントが自然にどう行動するかを確認しなければなりません。

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

そうした特定の合理化に対処するスキルを書きます。仮定上のケースに向けた余分な内容は追加しないでください。

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

REFACTOR：抜け穴を塞ぐ

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

以下を参照してください：skills/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 frontmatter を用意する（症状も含める）
• 検索に使われるキーワードを全体に盛り込む（エラー、症状、ツール）
• 核となる原則を明示した、分かりやすい概要を用意する
• RED フェーズで特定した具体的なベースラインの失敗に対処する
• コードをインラインで記載するか、別ファイルへの @link を使う
• 優れた例を 1 つ用意する（多言語にはしない）
• スキルありでシナリオを実行し、エージェントが従うことを確認する

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

• テストで新たに見つかった合理化を特定する
• 明示的な対処を追加する（規律に関するスキルの場合）
• すべてのテスト反復をもとに、合理化の一覧表を作成する
• 危険信号のリストを作成する
• 完全に防げるまで再テストする

品質チェック：

• 判断に迷う場合に限り、小さなフローチャートを用意する
• クイックリファレンス表を用意する
• よくある間違いのセクションを設ける
• 物語形式にしない
• 補助ファイルはツールまたは大量の参考資料に限る

デプロイ：

• スキルを git にコミットし、フォークにプッシュする（設定されている場合）
• 広く役立つ内容なら、PR での貢献を検討する

発見ワークフロー

今後、Claude がスキルを見つける方法：

1. 問題に遭遇する（「テストが不安定」）
2. find-skills ツールを使ってスキルを検索する（スキルリポジトリを検索）
3. SKILL.md を見つける（用途の詳細が一致）
4. 概要をざっと読む（関連する内容か？）
5. パターンを読む（クイックリファレンス表）
6. 例を読み込む（実装時のみ）

この流れに合わせて最適化してください。検索に使える用語を早い段階から繰り返し盛り込みます。

要点

スキルの作成は、プロセス文書に対する TDD です。

同じ鉄則：失敗するテストなしにスキルを作らない。 同じサイクル：RED（ベースライン）→ GREEN（スキルを書く）→ REFACTOR（抜け穴を塞ぐ）。 同じ利点：品質の向上、予想外の事態の減少、万全の成果。

コードに TDD を適用するなら、スキルにも適用してください。文書作成に同じ規律を適用するだけです。