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 の公式なスキル作成のベストプラクティスについては、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）：

• 必須フィールドは 2 つです：name と description（サポートされているすべてのフィールドについては、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 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 にレンダリングします：

node ./render-graphs.js ../some-skill           # Each diagram separately
node ./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

使用する場面：参照資料が大きすぎて本文に含められない場合

同梱スクリプトは、本文中でインタープリターを使って実行します（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 分のテストで数時間が節約できます。
「問題が発生したらテストする」	問題 = エージェントがスキルを使えないこと。デプロイ前にテストしましょう。
「テストは面倒すぎる」	テストは、本番環境で不良スキルをデバッグするよりも面倒ではありません。
「良いと確信している」	過信は問題を必ず招きます。それでもテストしましょう。
「学術的なレビューで十分だ」	読むこと ≠ 使うこと。適用シナリオをテストしましょう。
「テストする時間がない」	テストされていないスキルをデプロイすると、後で修正するのにより多くの時間が無駄になります。

これらはすべて次のことを意味します: デプロイ前にテストしましょう。例外はありません。

失敗に応じて形式を合わせる

ガイダンスを書く前に、ベースラインの失敗を分類しましょう。ある失敗タイプを完全に防ぐ形式が、別のタイプでは測定可能なほど逆効果になることがあります。

ベースラインの失敗	正しい形式	間違った形式
プレッシャー下でルールを飛ばす/違反する（分かっていながら、それでもやってしまう）	禁止 + 合理化テーブル + レッドフラグ（下記の「完全防御」を参照）	ソフトなガイダンス（「〜を好む」「〜を検討する」）
従っているが、出力の形が間違っている（肥大化したプロンプト、埋もれた判定、繰り返された仕様）	ポジティブなレシピまたは契約: 出力が何であるか — その構成要素を順番に — を明示する	禁止リスト（「繰り返すな」「ナレーションするな」）
すでに生成しているものから必須要素を省略している	構造的: 記入するテンプレートに REQUIRED フィールドまたはスロットを設ける	テンプレート付近の散文によるリマインダー
動作が条件に依存すべきである	観測可能な述語に紐づけた条件（「ブリーフが存在するなら、それを参照する」）	無条件のルール + 免除条項

なぜ禁止が形成の問題で逆効果になるのか: 競合するインセンティブ（「プロンプトを自己完結型にせよ」）の下では、エージェントは「X するな」と交渉します。ディスパッチプロンプトのガイダンスにおける直接比較の文言テストでは、禁止群はレシピ群よりも明らかに多くの不要なコンテンツを生成し（分布が完全に分離）、ガイダンスなしの対照群よりもさらに悪い傾向がありました — 想定せずに自分のケースをマイクロテストしてください。ただし、デフォルトで禁止に手を伸ばしてはいけません。レシピには交渉の余地がありません: 出力が記載された形に一致するか、しないかです。

どの形式を選んでも共通するルール:

• ニュアンス条項を入れない。 「重要な場合を除いて X するな」は交渉を再開させます — 勝利したレシピに単一のニュアンス条項を追加すると、同じ文言テストで一貫した状態からノイズの多い状態に劣化しました。本当の例外は、観測可能な述語に基づく独自の条件として表現しましょう。
• 免除条項はスコープを限定しない。 「この制限はコードブロックには適用されない」としても、依然としてコードブロックが抑制されます。出力の一部を免除する必要がある場合は、ルールがそこに届かないように再構成しましょう。

合理化を許さないスキルの作成

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 文字。 spec を参照）
• 説明は「Use when...」で始め、具体的なトリガーや症状を含める
• 説明は三人称で記述する
• 検索に使えるキーワードを全体に含める（エラー、症状、ツール）
• 中核となる原則を明確にした概要を記述する
• RED フェーズで特定した具体的なベースラインの失敗に対処する
• ガイダンスの形式を失敗の種類に合わせる（「失敗に合わせた形式の選択」を参照）
• 行動を形作るガイダンスの場合、ガイダンスなしの対照条件と比較して表現をマイクロテストする（5 回以上実施し、フラグが立った一致をすべて手動で確認する）。純粋なリファレンススキルでは該当しない
• コードをインラインで記述するか、別ファイルへのリンクを追加する
• 優れた例を 1 つ用意する（複数言語を使わない）
• スキルを使ってシナリオを実行し、エージェントが指示に従うようになったことを確認する

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

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

品質チェック：

• 判断が明白でない場合に限り、小さなフローチャートを作成する
• クイックリファレンステーブルを作成する
• よくある間違いのセクションを設ける
• 物語形式の説明を含めない
• 補助ファイルは、ツールや大規模なリファレンスに限って用意する

デプロイ：

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

発見ワークフロー

将来のエージェントがスキルを見つける流れ：

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

この流れに合わせて最適化してください。検索可能な用語を、早い段階から頻繁に含めてください。