writing-skills

スキルの作成

概要

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

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

基本原則： スキルなしでエージェントが失敗するのを見ていなければ、そのスキルが適切な内容を教えているかどうかはわかりません。

個人用スキルはエージェント固有のディレクトリに置きます： Claude Code の場合は ~/.claude/skills、Codex の場合は ~/.codex/skills

必須の事前知識： このスキルでは、スキル作成にテストファーストの規律を適用します。スキルを信頼する前に、そのスキルが失敗する様子を確認してください。テストの仕組みは testing-skills-with-subagents にあります（以下を参照）。

使用するタイミング

次の場合にスキルを作成します：

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

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

• 一度きりの解決策
• 他の場所で十分に文書化されている標準的な慣行
• プロジェクト固有の規約（CLAUDE.md に記載してください）

スキルの種類

• 技法：手順を伴う具体的な方法（condition-based-waiting、root-cause-tracing）
• パターン：問題への取り組み方（flatten-with-flags、test-invariants）
• リファレンス：API ドキュメント、構文ガイド、ツールのドキュメント（office docs）

クイックリファレンス

タスク	参照先
スキルへの TDD の適用方法を理解する	skills/writing-skills/references/tdd-mapping.md
スキルの構造と整理方法を学ぶ	skills/writing-skills/references/skill-structure.md
検索と発見に向けて最適化する	skills/writing-skills/references/search-optimization.md
サブエージェントでスキルをテストする	skills/writing-skills/references/testing-skills.md
コード例とフローチャート	skills/writing-skills/references/code-and-flowcharts.md
作成チェックリストの全項目	skills/writing-skills/references/checklist.md

RED-GREEN-REFACTOR ワークフロー

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

1. プレッシャーシナリオを作成する（規律を扱うスキルでは、3 つ以上のプレッシャーを組み合わせる）
2. スキルなしでシナリオを実行し、ベースラインの動作をそのまま記録する
3. 言い訳や失敗のパターンを特定する

これは重要です： スキルを書く前に、エージェントが自然にどう行動するかを確認してください。

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

1. ベースラインで具体的に見つかった失敗に対処するスキルを書く
2. 構成のガイドラインに従う（skill-structure.md を参照）
3. 検索しやすいように最適化する（search-optimization.md を参照）
4. 同じシナリオをスキルありで実行し、エージェントが従うようになったことを確認する

REFACTOR：抜け穴を塞ぐ

1. テストで新たに見つかった言い訳を特定する
2. 規律を扱うスキルには、明示的な反論を追加する
3. すべての反復で見つかった言い訳を一覧表にまとめる
4. 抜け穴がなくなるまで再テストする

必須のサブスキル： 完全なテスト手法には testing-skills-with-subagents を使用してください。

絶対のルール

NO SKILL WITHOUT A FAILING TEST FIRST

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

テストの前にスキルを書いた場合は、それを削除してください。最初からやり直してください。

例外はありません：

• 「簡単な追加」の場合でも
• 「セクションを追加するだけ」の場合でも
• 「ドキュメントを更新するだけ」の場合でも
• 削除とは、実際に削除することです

よくある間違い

間違い	修正方法
テストの前にスキルを書く	スキルを削除し、先にベースラインテストを実行する
ベースライン（RED フェーズ）を省略する	失敗を見るまでは、何を教えるべきかわかりません
スキルを入れたままテストする	スキルを削除し、真のベースラインの動作を確認する
複数のスキルを「まとめて」作成する	次に進む前に、スキルごとに RED-GREEN-REFACTOR を完了する
説明が曖昧	「次の場合に使用する」で始め、具体的な条件を含める
スキルの参照に @ リンクを使う	スキル名だけを使い、強制的な読み込みを避ける
出来のよくないコード例を複数載せる	最も適した言語で、優れた例を 1 つ載せる
物語風に説明する	一度きりの話ではなく、再利用可能なパターンに焦点を当てる

次のスキルに進む前に必ず停止してください

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

テストせずに複数のスキルをまとめて作成しないでください。テストしていないスキルのデプロイは、テストしていないコードのデプロイと同じです。

デプロイの全チェックリストについては、checklist.md を参照してください。

リソース

• 公式ガイダンス：Anthropic 公式のスキル作成に関するベストプラクティスについては、anthropic-best-practices.md を参照してください
• Graphviz の規約：フローチャートのスタイルルールについては、@graphviz-conventions.dot を参照してください
• テスト方法：testing-skills-with-subagents を使用してください