writing-skills

スキルの作成

概要

スキルの作成は、プロセス文書に適用するテスト駆動開発（TDD）です。

個人用スキルは、エージェント固有のディレクトリ（Claude Code の場合は ~/.claude/skills、Codex の場合は ~/.agents/skills/）に保存します。

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

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

必須の事前知識： このスキルを使う前に、superpowers-ruby: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	はい	最大64文字。小文字、数字、ハイフンのみ使用できます。先頭または末尾にハイフンを使用できず、ハイフンを連続させることもできません。親ディレクトリ名と一致させる必要があります。
description	はい	最大1024文字。効果的な説明の書き方については、CSOのセクションを参照してください。
license	いいえ	ライセンス名、または同梱のライセンスファイルへの参照。
compatibility	いいえ	最大500文字。環境要件（対象製品、システムパッケージ、ネットワークアクセス）を指定します。
metadata	いいえ	任意のキーと値のマッピング（文字列キーと文字列値）。
allowed-tools	いいえ	事前承認されたツールのスペース区切りリスト。実験的機能のため、サポート状況は異なる場合があります。

description のガイドライン：

• 三人称で、使用するタイミングのみを説明します（何をするかではありません）。
• 使用条件に焦点を当てるため、「Use when...」で始めます。
• 具体的な症状、状況、文脈を含めます。
• スキルのプロセスやワークフローを要約しないでください（理由についてはCSOのセクションを参照してください）。
• 可能であれば500文字未満にします。

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions and symptoms]
# Optional:
# license: MIT
# compatibility: Requires network access
# metadata:
#   author: your-name
# allowed-tools: Bash(git:*) Read
---

# 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が近道を選ぶ原因になります。その結果、スキル本文が読み飛ばされるドキュメントになってしまいます。

# ❌ 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などの）言語固有の症状は説明しません。
• スキル自体が特定の技術に依存しない限り、トリガーは技術に依存しないものにします。
• スキルが特定の技術に依存する場合は、トリガーでそれを明示します。
• （システムプロンプトに挿入されるため）三人称で書きます。
• スキルのプロセスやワークフローを要約しないでください。

# ❌ 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

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

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

コード例

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

最も関連性の高い言語を選びます：

• テスト手法 → 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

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

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

例外はありません：

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

REQUIRED BACKGROUND: なぜこれが重要なのかは、superpowers-ruby:test-driven-development スキルで説明されています。同じ原則がドキュメントにも当てはまります。

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

スキルの種類ごとに、適したテスト方法は異なります：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

合理化に屈しないスキルを作る

規律を徹底させるスキル（TDD など）は、合理化に屈しないようにする必要があります。エージェントは賢く、プレッシャーがかかると抜け道を見つけます。

心理学に関する注記： 説得技法がなぜ有効なのかを理解すると、体系的に適用しやすくなります。権威、一貫性、希少性、社会的証明、一体性の原則に関する研究の基礎については、persuasion-principles.md（Cialdini、2021；Meincke ほか、2025）を参照してください。

あらゆる抜け道を明示的に塞ぐ

ルールを述べるだけでなく、具体的な回避策を禁止します。

```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 に追加する

説明に、ルールに違反しそうなときの兆候を追加します。

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 良くない理由： ラベルには意味が伝わる名前を付ける必要があります

STOP：次のスキルに進む前に

スキルを作成したら、必ず作業を止めてデプロイプロセスを完了してください。

次のことはしないでください：

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

以下のデプロイチェックリストは、スキルごとに必ず実施してください。

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

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

重要：以下の各チェック項目について、TodoWrite を使って todo を作成してください。

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

• プレッシャーシナリオを作成する（規律に関するスキルでは、複合的なプレッシャーを 3 つ以上含める）
• スキルなしでシナリオを実行し、ベースラインの挙動をそのまま記録する
• 正当化や失敗のパターンを特定する

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

• 名前には英字、数字、ハイフンのみを使用する（括弧や特殊文字は不可）
• YAML フロントマターに必須の name（最大 64 文字、小文字とハイフンのみ）と description（最大 1024 文字）を含める
• 該当する場合は、任意のフロントマターフィールド license、compatibility、metadata、allowed-tools を追加する
• 説明は「Use when...」で始め、具体的なトリガーや症状を含める
• 説明は三人称で書く
• 検索しやすいよう、エラー、症状、ツールに関するキーワードを全体に含める
• 中核となる原則を示す、明確な概要を用意する
• RED で特定した具体的なベースラインの失敗に対処する
• コードを本文に記載するか、別ファイルへのリンクを追加する
• 優れた例を 1 つ用意する（複数言語にはしない）
• スキル適用後にシナリオを実行し、エージェントが従うことを確認する

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

• テストで新たに見つかった正当化を特定する
• 明示的な反論を追加する（規律に関するスキルの場合）
• すべてのテスト反復から、正当化の一覧表を作成する
• 危険信号のリストを作成する
• 確実に機能するまで再テストする

品質チェック：

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

デプロイ：

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

発見ワークフロー

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

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

この流れに最適化してください - 検索されやすい用語を、早い段階から頻繁に含めてください。

要点

スキルの作成は、プロセスを記録するための TDD です。

同じ鉄則：失敗するテストなしにスキルを作らない。 同じサイクル：RED（ベースライン）→ GREEN（スキルを書く）→ REFACTOR（抜け穴をふさぐ）。 同じ効果：品質の向上、予期せぬ事態の減少、確実な成果。

コードに TDD を適用しているなら、スキルにも適用してください。ドキュメントに同じ規律を適用するだけです。