writing-skills

スキルの作成

概要

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

個人用スキルは ~/.claude/skills/ に保存します。

サブエージェントを使ってテストケース（プレッシャーシナリオ）を作成し、それらが失敗する様子を確認し（ベースラインの動作）、スキル（ドキュメント）を書き、テストが通る様子を確認し（エージェントが指示に従う）、抜け穴を塞ぐためにリファクタリングします。

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

必須の前提知識： このスキルを使う前に、superpowers-extended-cc: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）：

• 必須フィールドは2つ：nameとdescription（サポートされているすべてのフィールドについては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. 詳細な説明フィールド

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

形式： トリガーとなる条件に焦点を当てるため、「Use when...」で始めます。

重要：説明は「いつ使うか」であり、「スキルが何をするか」ではありません

説明には、トリガーとなる条件のみを記述してください。説明の中でスキルの手順やワークフローを要約してはいけません。

重要な理由： テストの結果、説明にスキルのワークフローが要約されていると、Claude はスキルの内容全体を読まずに、説明に従ってしまうことがあります。「タスク間のコードレビュー」という説明が原因で、スキルのフローチャートには（仕様への準拠、その後にコード品質という）2 回のレビューが明確に示されていたにもかかわらず、Claude は 1 回だけレビューしました。

説明を「独立したタスクを含む実装計画を実行するときに使用する」に変更したところ（ワークフローの要約なし）、Claude はフローチャートを正しく読み、2 段階のレビュー手順に従いました。

落とし穴： ワークフローを要約した説明を作ると、Claude が近道を選んでしまいます。その結果、スキルの本文は 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

内容：

• このスキルが適用されることを示す、具体的なトリガー、症状、状況を使います
• 言語固有の症状（setTimeout、sleep）ではなく、問題（競合状態、一貫性のない動作）を説明します
• スキル自体が特定の技術に特化していない限り、トリガーは技術に依存しないものにします
• スキルが特定の技術に特化している場合は、そのことをトリガーで明示します
• 3 人称で記述します（システムプロンプトに挿入されます）
• スキルの手順やワークフローを絶対に要約しないでください

# ❌ 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. わかりやすい命名

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

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

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

問題： はじめに使うスキルや頻繁に参照されるスキルは、すべての会話で読み込まれます。トークンは一つひとつが重要です。

目標の単語数：

• はじめに使うワークフロー：各 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

実行すること、または中心となる知見に基づいて名前を付けます。

• ✅ async-test-helpers より condition-based-waiting
• ✅ skill-usage ではなく using-skills
• ✅ data-structure-refactoring より flatten-with-flags
• ✅ debugging-techniques より root-cause-tracing

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

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

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

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

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

• ✅ 良い例：**REQUIRED SUB-SKILL:** Use superpowers-extended-cc:test-driven-development
• ✅ 良い例：**REQUIRED BACKGROUND:** You MUST understand superpowers-extended-cc: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

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

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

例外はありません：

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

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

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

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

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

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

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

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

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

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

例： 条件ベースの待機、根本原因の追跡、防御的プログラミング

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

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

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

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

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

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

• 認識シナリオ：パターンが当てはまる状況を認識できるか？
• 適用シナリオ：メンタルモデルを使えるか？
• 反例：適用すべきでない状況を把握しているか？

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

参照スキル（ドキュメント／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 に適応）

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

RED フェーズ — 失敗するテストを書く：

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

GREEN フェーズ — 最小限のスキルを書く：

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

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

• テストで新たに見つかった合理化を特定する
• 明示的な対処法を追加する（規律を求めるスキルの場合）
• すべてのテスト反復から合理化の一覧表を作成する
• 危険信号のリストを作成する
• 抜け穴がなくなるまで再テストする

品質チェック：

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

デプロイ：

• スキルを git にコミットし、フォークにプッシュする（設定済みの場合）
• 広く役立つ場合は、PR でのコントリビューションを検討する

検出ワークフロー

Claude が今後スキルを見つける流れ：

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

この流れに合わせて最適化してください — 検索されやすい用語を、早い段階から繰り返し含めてください。