writing-skills

スキルの執筆

概要

スキルの執筆は、プロセス文書に適用するテスト駆動開発です。

個人用スキルは、実行環境のスキルディレクトリ（Claude Code では ~/.claude/skills/）に保存します。各実行環境でのパスについては、codex-tools.md または gemini-tools.md を参照してください。Codex、Copilot CLI、Gemini CLI は、実行環境をまたいで利用できる別名として ~/.agents/skills/ も認識します。

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

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

必須の事前知識： このスキルを使う前に、superpowers:test-driven-development を必ず理解してください。このスキルでは、基本となる RED-GREEN-REFACTOR サイクルを定義しています。このスキルは、TDD をドキュメントに適用するものです。

公式ガイダンス： Anthropic の公式スキル作成のベストプラクティスについては、references/anthropic-best-practices.md を参照してください。このドキュメントでは、このスキルの TDD 重視のアプローチを補完する追加のパターンとガイドラインを紹介しています。

スキルとは

スキルとは、実証済みの手法、パターン、ツールをまとめたリファレンスガイドです。スキルは、後続のエージェントが効果的なアプローチを見つけ、適用するのに役立ちます。

スキルに含まれるもの： 再利用可能な手法、パターン、ツール、リファレンスガイド

スキルに含まれないもの： 一度だけ問題を解決した方法を記した物語

スキルにおける TDD の対応関係

TDD の概念	スキル作成
テストケース	サブエージェントを使ったプレッシャーシナリオ
本番コード	スキルドキュメント（SKILL.md）
テスト失敗（RED）	スキルがない状態でエージェントがルールに違反する（ベースライン）
テスト成功（GREEN）	スキルがある状態でエージェントが従う
リファクタリング	順守を維持しながら抜け穴をふさぐ
先にテストを書く	スキルを書く前にベースラインシナリオを実行する
失敗を確認する	エージェントが使う正確な合理化を記録する
最小限のコード	具体的な違反に対処するスキルを書く
成功を確認する	エージェントが従うようになったことを検証する
リファクタリングサイクル	新たな合理化を見つける → 対処する → 再検証する

スキル作成のプロセス全体で、RED-GREEN-REFACTOR に従います。

スキルを作成するタイミング

次の場合に作成します：

• その手法が直感的には明らかでなかった
• 複数のプロジェクトで再び参照することになる
• パターンを幅広く応用できる（特定のプロジェクトに限定されない）
• 他の人にも役立つ

次の場合は作成しないでください：

• 一度限りの解決策
• ほかの場所で十分に文書化されている標準的な慣行
• プロジェクト固有の規約（指示ファイルに記載してください）
• 機械的な制約（正規表現や検証で強制できる場合は自動化し、文書化は判断が必要な事項に使ってください）

スキルの種類

手法

手順に沿って実行する具体的な方法（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. 大規模なリファレンス（100 行以上） - API ドキュメント、包括的な構文説明
2. 再利用可能なツール - スクリプト、ユーティリティ、テンプレート

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

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

SKILL.md の執筆

スキルの description には、使用するタイミングだけを記載します。つまり、発動条件と症状を「Use when...」で始めます。スキルのワークフローを要約してはいけません。ワークフローの要約を読んだエージェントが、スキル本体を読まずにその要約に従ってしまうためです。

スキルの frontmatter、名前、説明を作成または変更するときや、サイズを削減する必要があるときは、references/discovery.md を読んでください。SKILL.md のテンプレート、説明とキーワードのガイダンス、命名、トークン予算、ほかのスキルとの相互参照について説明しています。

フローチャート

スキルにフローチャートを追加または変更する場合は、まず references/flowcharts.mdを読んでください。フローチャートを使う価値がある場合、graphviz の規約、およびレンダリング方法について説明しています。

コード例

優れた例を1つ示すほうが、平凡な例をたくさん示すより効果的です

最も関連性の高い言語を選んでください。

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

良い例：

• 完全で、そのまま実行できる
• WHY（なぜそうするのか）を説明するコメントがある
• 実際のシナリオに基づいている
• パターンが明確に示されている
• 応用しやすい（汎用テンプレートではない）

避けること：

• 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

用途：リファレンス資料が大きすぎてインラインに収まらない場合

同梱スクリプトは、本文中でインタープリターを通して呼び出してください（bash scripts/tool.sh、node scripts/tool.js）。パスだけを指定して呼び出してはいけません。一部のハーネスプラグインパッケージャーでは実行ビットが削除されるため、scripts/tool.shだけを指定するとPermission deniedで失敗します。

鉄の掟（TDDと同じ）

NO SKILL WITHOUT A FAILING TEST FIRST

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

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

例外はありません：

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

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

あらゆる種類のスキルのテスト

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

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

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

テスト方法：

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

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

技術スキル（ハウツーガイド）

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

テスト方法：

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

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

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

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

テスト方法：

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

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

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

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

テスト方法：

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

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

テストを省略する際によくある正当化

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

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

失敗に合わせて形式を選ぶ

ガイダンスを書く前に、ベースラインでの失敗を分類してください。ある種類の失敗を確実に防ぐ形式が、別の種類の失敗を明らかに悪化させることがあります。

ベースラインでの失敗	適切な形式	不適切な形式
プレッシャーの下でルールを無視する／破る（分かっているのに、そのとおりにしない）	禁止事項＋正当化の表＋危険信号（references/bulletproofing.md を参照）	ソフトなガイダンス（「〜を推奨します」「〜を検討してください」）
指示には従うが、出力の形式が間違っている（肥大化したプロンプト、埋もれた判定、仕様の言い換え）	肯定的な手順または契約：出力に含めるもの、つまりその構成要素と順序を示す	禁止事項のリスト（「言い換えない」「説明を加えない」）
すでに作成しているものから、必須要素が抜ける	構造的に指定する：記入するテンプレートに必須フィールドまたは必須枠を設ける	テンプレートの近くに置く文章での注意喚起
振る舞いが条件によって変わるべきである	観察可能な述語に基づく条件（「ブリーフがある場合は、それを参照する」）	無条件のルール＋適用除外条項

禁止事項が形式の問題を悪化させる理由：「プロンプトを自己完結させる」という競合する動機があると、エージェントは「Xしないで」という指示に対して折り合いをつけようとします。ディスパッチプロンプトのガイダンスに関する文言の直接比較テストでは、禁止事項を用いたグループは、手順を用いたグループよりも、望ましくない内容を明らかに多く生成しました（分布は完全に分離していました）。さらに、ガイダンスなしの対照群より悪化する傾向もありました。決めつけずに、自分のケースで小規模なテストを行ってください。ただし、安易に禁止事項を使わないでください。手順に交渉の余地はありません。出力が指定された形式に合っているか、いないかのどちらかです。

選んだ形式にかかわらず、守るべきルール：

• ニュアンスを加える条項は設けないでください。「重要な場合を除き、Xしないでください」とすると、交渉の余地が再び生まれます。同じ文言テストでは、勝っていた手順にニュアンスを加える条項を一つ付けただけで、安定した結果がばらつく結果に変わりました。実際の例外は、観察可能な述語に基づく独立した条件として表現してください。
• 適用除外条項では範囲を限定できません。「この制限はコードブロックには適用されません」としても、コードブロックの出力は抑制されます。出力の一部を適用除外にする必要がある場合は、ルールがそこに及ばないよう構成を変えてください。

正当化を封じる

ベースラインでの失敗が規律上の問題である場合は、ガイダンスを書く前に references/bulletproofing.md を読んでください。抜け穴を塞ぐ方法、文言どおりに従うことと意図を守ることの境界、正当化の表、危険信号のリストについて説明しています。

スキルの RED-GREEN-REFACTOR

TDD サイクルに従ってください。

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

スキルを使わずに、サブエージェントでプレッシャーシナリオを実行します。実際の振る舞いを正確に記録してください。

• どのような選択をしましたか？
• どのような正当化をしましたか（実際の言葉をそのまま記録）？
• どのプレッシャーが違反を引き起こしましたか？

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

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

特定できた正当化に対処するスキルを書きます。仮定上のケースに備えて、余分な内容を追加しないでください。

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

REFACTOR：抜け穴を塞ぐ

エージェントが新たな正当化を見つけましたか？明示的な反論を追加してください。抜け穴がなくなるまで再テストします。

フルシナリオの前に行うマイクロテスト

本格的なプレッシャーシナリオの実行は最終チェックですが、反復ごとに時間とコストがかかります。まず、マイクロテストで文言そのものを検証します。

1. 各呼び出しで新しいコンテキストを使ったサンプルを1つ実行 — 生の API 呼び出しを使うか、API にアクセスできない場合は単発のサブエージェントを使います。システムプロンプトにはガイダンスが適用される現実的なコンテキスト（ガイダンス単体ではなく、スキル全体またはプロンプトテンプレート全体）を設定し、ユーザーメッセージには失敗を誘発するタスクを設定します。
2. ガイダンスなしの対照群を必ず含めます。 対照群で失敗が起きなければ、修正すべきことはありません。作業を止め、ガイダンスを作成しないでください。
3. 各バリアントで5回以上繰り返します。 1回だけのサンプルでは誤った結論になり得ます。
4. フラグが付いた一致箇所はすべて手動で読みます。 プログラムによる採点を行っても構いませんが、テンプレートの反復や引用された反例が一致として誤認されることがあります。自動集計だけでは、失敗も成功も過大評価されます。
5. ばらつきも指標です。 ガイダンスが機能すれば、反復の結果は同じパターンに収束します。5回の反復で5通りの解釈になるなら、文言に十分な拘束力がありません。言葉を追加する前に、形式を明確にしてください。

マイクロテストは文言を検証するものであり、規律を要するスキルのプレッシャーシナリオに代わるものではありません。

テスト方法： 完全なテスト方法については、references/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 に合わせたもの）

重要：以下のチェック項目ごとに TODO を作成してください。

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

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

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

• 名前には英字、数字、ハイフンのみを使用する（括弧や特殊文字は使用しない）
• 必須の name フィールドと description フィールドを含む YAML フロントマターを用意する（最大 1024 文字。仕様を参照）
• 説明は「Use when...」で始め、具体的なトリガーや症状を含める
• 説明は三人称で書く
• 検索に使えるキーワード（エラー、症状、ツール）を全体に盛り込む
• 中核となる原則を含む明確な概要を用意する
• RED で特定したベースラインの失敗に対処する
• 失敗の種類に合った形式でガイダンスを記述する（「失敗の種類に形式を合わせる」を参照）
• 行動を形成するガイダンスの場合：ガイダンスなしの対照条件と比較して文言を小規模にテストする（5 回以上実施し、該当と判定された結果をすべて手動で確認する）。純粋なリファレンススキルの場合は該当なし
• コードをインラインで記載するか、別ファイルへのリンクを追加する
• 優れた例を 1 つ用意する（複数の言語を使わない）
• スキルを使ってシナリオを実行し、エージェントが遵守するようになったことを確認する

REFACTOR フェーズ — 抜け道をなくす：

• テストで新たに見つかった正当化を特定する
• 明示的な対策を追加する（規律スキルの場合）
• すべてのテスト反復から正当化の表を作成する
• 危険信号のリストを作成する
• 万全になるまで再テストする

品質チェック：

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

デプロイ：

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

発見のワークフロー

今後、エージェントがスキルを見つける方法：

1. 問題に遭遇する（「テストが不安定」）
2. スキルを検索する（説明を grep で検索し、カテゴリを閲覧する）
3. SKILL を見つける（説明が一致する）
4. 概要をざっと確認する（関連性があるか）
5. パターンを読む（クイックリファレンス表）
6. 例を読み込む（実装時のみ）

この流れに合わせて最適化してください — 検索可能な用語を早い段階から、頻繁に盛り込みましょう。