writing-skills

スキルの作成

概要

スキルの作成は、プロセスのドキュメント化に TDD を適用したものです。

個人用スキルは、エージェント固有のディレクトリ（Claude Code の場合は ~/.claude/skills、Codex の場合は ~/.agents/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 つの名前空間に配置します

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

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

次のものはインラインにします：

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

SKILL.md の構成

フロントマター（YAML）：

• 必須フィールドは name と description の 2 つです（サポートされているフィールドの一覧は agentskills.io/specification を参照してください）
• 合計 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 フェーズ - 最小限のスキルを書く：

• 名前には英字、数字、ハイフンのみを使用する（括弧や特殊文字は使用しない）
• 必須の name フィールドと description フィールドを含む YAML フロントマターを用意する（最大1024文字。詳細は仕様を参照）
• 説明は「Use when...」で始め、具体的なトリガーや症状を含める
• 説明は三人称で書く
• 検索しやすいように、全体を通してキーワード（エラー、症状、ツール）を含める
• 核となる原則を含む、明確な概要を用意する
• RED フェーズで特定した具体的なベースラインの失敗に対処する
• コードをインラインで記述するか、別ファイルへのリンクを記載する
• 優れた例を1つ用意する（複数の言語を使わない）
• スキルを適用してシナリオを実行し、エージェントが適切に従うようになったことを確認する

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

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

品質チェック：

• 判断が自明でない場合に限り、小さなフローチャートを用意する
• クイックリファレンス表を用意する
• よくある間違いのセクションを設ける
• 物語形式の説明は含めない
• 補助ファイルはツールや大部の参考資料に限る

デプロイ：

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

発見のワークフロー

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

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

この流れに合わせて最適化しましょう。検索されやすい用語を、冒頭付近に繰り返し含めてください。

要点

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

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

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