writing-skills

スキルの作成

概要

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

個人用スキルは、ランタイムにインストールされたスキルディレクトリに保存されます。Codex、Copilot CLI、Gemini CLI は、すべて ~/.agents/skills/ をランタイム間で共通のエイリアスとして認識します。

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

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

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

公式ガイダンス： Anthropic の公式なスキル作成のベストプラクティスについては、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つの名前空間にまとめます

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

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

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

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

SKILL.md の構成

フロントマター（YAML）：

• 必須フィールドは name と description の2つです（サポートされるすべてのフィールドについては、agentskills.io/specification を参照してください）
• 合計1024文字以内
• name：英字、数字、ハイフンのみを使用します（括弧や特殊文字は不可）
• description：三人称で、使用する条件のみを説明します（何をするかは説明しません）
  • トリガーとなる条件に焦点を当てるため、「Use when...」で始めます
  • 具体的な兆候、状況、コンテキストを含めます
  • スキルのプロセスやワークフローを要約してはいけません（理由については SDO の節を参照）
  • 可能であれば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

スキル発見の最適化（SDO）

発見しやすさが重要です： 後続のエージェントが、あなたのスキルを見つけられる必要があります

1. 詳細な説明フィールド

目的： エージェントは説明を読んで、特定のタスクでどのスキルを読み込むかを判断します。「今、このスキルを読むべきか？」に答えられるようにします。

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

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

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

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

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

落とし穴： ワークフローを要約した説明は、エージェントが使う近道を生み出します。その結果、スキル本文はエージェントが読み飛ばすドキュメントになってしまいます。

# ❌ BAD: Summarizes workflow - agents 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. キーワードの網羅

エージェントが検索に使いそうな語句を使います。

• エラーメッセージ：「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
• 能動的で、実行するアクションを表します

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

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

明示的な必須マーカーとともに、スキル名だけを使います。

• ✅ 推奨：**REQUIRED SUB-SKILL:** Use test-driven-development`
• ✅ 推奨：**REQUIRED BACKGROUND:** You MUST understand systematic-debugging`
• ❌ 非推奨：See skills/testing/test-driven-development（必須かどうかが不明確です）
• ❌ 非推奨：@skills/testing/test-driven-development/SKILL.md（強制的に読み込まれ、コンテキストを消費します）

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

フローチャートの使い方

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

良い例：

• 完成していて、実行可能
• 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

該当する場合：参考資料が大きすぎて本文に含められない場合

鉄則（TDD と同じ）

NO SKILL WITHOUT A FAILING TEST FIRST

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

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

例外はありません。

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

必須の予備知識： なぜこれが重要なのかは、test-driven-development スキルで説明されています。同じ原則がドキュメントにも適用されます。

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

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

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

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

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

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

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

技法スキル（実践ガイド）

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

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

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

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

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

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

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

• 認識シナリオ：パターンが当てはまる状況を認識できるか
• 適用シナリオ：メンタルモデルを活用できるか
• 反例：適用してはいけない状況を理解しているか

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

参考スキル（ドキュメント／API）

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

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

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

成功基準： エージェントが参考情報を見つけ、正しく適用できる

テストを省略する際によくある言い訳

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

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

失敗に合った形式を選ぶ

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

ベースラインの失敗	適切な形式	不適切な形式
プレッシャーの下でルールを無視・違反する（分かっているのに、そのとおりにしない）	禁止事項＋言い訳の表＋危険信号（下記の「合理化への耐性を高める」を参照）	柔らかなガイダンス（「～を優先してください」「～を検討してください」）
指示には従うが、出力の形が間違っている（肥大化したプロンプト、埋もれた結論、仕様の言い直し）	肯定形のレシピまたは契約：出力が「何であるか」を、構成要素と順序を含めて示す	禁止事項のリスト（「言い直さない」「説明を加えない」）
すでに作成しているものから必須要素が抜ける	構造化する：記入するテンプレートに必須フィールドまたはスロットを設ける	テンプレートの近くに文章で注意書きを置く
条件によって動作を変える必要がある	観察可能な述語を条件にした条件文（「概要が存在する場合は、それを参照する」）	無条件のルール＋免除条項

禁止事項が出力の形を整える問題に逆効果になる理由：「プロンプトを自己完結させる」といった競合する動機があると、エージェントは「Xするな」という指示に抜け道を見つけます。ディスパッチプロンプトのガイダンスを直接比較する文言テストでは、禁止事項のグループはレシピのグループより明らかに多く、望ましくない内容を出力しました（分布は完全に分離）。さらに、ガイダンスなしの対照群よりも悪い傾向が見られました。決めつけずに自身のケースを小規模にテストしてください。ただし、既定で禁止事項に頼ってはいけません。レシピには交渉の余地がありません。出力は、示された形に一致するか、しないかのどちらかです。

どの形式を選ぶ場合にも適用するルール：

• 曖昧にする但し書きを付けないでください。「重要な場合を除き、Xしないでください」とすると、再び交渉の余地が生まれます。同じ文言テストでは、勝っていたレシピに曖昧にする但し書きを1つ加えただけで、一貫性が損なわれ、結果にばらつきが生じました。実際の例外は、観察可能な述語を条件とする独立した条件文として表現してください。
• 免除条項を設けても、適用範囲は限定されません。「この制限はコードブロックには適用されません」と書いても、コードブロックの出力は抑制されます。出力の一部を適用対象外にする必要がある場合は、ルールがその部分に及ばないよう構成し直してください。

合理化に対するスキルの耐性を高める

TDDのように規律を徹底させるスキルは、合理化に対抗できる必要があります。エージェントは賢いため、プレッシャーの下では抜け道を見つけます。

適用範囲： このツールキットは、規律に関する失敗を対象としています。つまり、ルールを知っているエージェントがプレッシャーの下でそれを省略する場合です。出力の形が間違っている場合や要素が抜けている場合、禁止事項に基づいて合理化への耐性を高めようとすると逆効果になります。代わりに「失敗に合った形式を選ぶ」に示した形式を使用してください。

心理学に関する注記： 説得の手法がなぜ有効なのかを理解することで、体系的に適用しやすくなります。権威、一貫性、希少性、社会的証明、一体性の原則に関する研究基盤については、persuasion-principles.md（Cialdini, 2021; Meincke et al., 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.**

違反の兆候をSDOに追加する

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

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

スキルのRED-GREEN-REFACTOR

TDDサイクルに従います。

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

スキルを使わずにサブエージェントでプレッシャーシナリオを実行します。実際の挙動を正確に記録します。

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

これは「テストが失敗するのを確認する」段階です。スキルを書く前に、エージェントが自然にどのように振る舞うかを確認する必要があります。

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

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

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

REFACTOR：抜け穴を塞ぐ

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

本格的なシナリオの前に文言をマイクロテストする

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

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

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

テスト方法： 完全なテスト方法については、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. 例を読み込む（実装時のみ）

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