writing-skills

概要

このスキルは、ドキュメントやスキルの作成において、テスト駆動開発（TDD）のアプローチを徹底します。内容を書く前にスキルが達成すべきことを定義することで、機能を明確にし、「幻覚による有用性」や、根拠のない一般論を防ぎます。

鉄則

NO SKILL WITHOUT A FAILING TEST FIRST 事前にテストケースを用意せずに作成されたスキルは、特定のユーザーの問題を解決しない、一般論の寄せ集めになりがちです。テストケースによって、スキルを現実に根差したものにします。

ステートマシン

digraph writing_skills_flow {
    "Start" [shape=doublecircle];
    "Step 1: Define User Problem" [shape=box];
    "Step 2: Write Failing Test Case" [shape=box];
    "Step 3: Define Acceptance Criteria" [shape=box];
    "Step 4: Author Skill Content" [shape=box];
    "Step 5: Run Test Case" [shape=box];
    "Gate: Pass Test?" [shape=diamond];
    "Done" [shape=doublecircle];

    "Start" -> "Step 1: Define User Problem";
    "Step 1: Define User Problem" -> "Step 2: Write Failing Test Case";
    "Step 2: Write Failing Test Case" -> "Step 3: Define Acceptance Criteria";
    "Step 3: Define Acceptance Criteria" -> "Step 4: Author Skill Content";
    "Step 4: Author Skill Content" -> "Step 5: Run Test Case";
    "Step 5: Run Test Case" -> "Gate: Pass Test?";
    "Gate: Pass Test?" -> "Done" [label="pass"];
    "Gate: Pass Test?" -> "Step 4: Author Skill Content" [label="fail"];
}

このスキルを使う場面

• エージェントスキルを一から作成するとき。
• 既存のスキルをリファクタリングして、新しい機能を追加するとき。
• 粗削りな草稿を、本番環境で使えるスキルに仕上げるとき。
• 品質の低い出力を生成するスキルをデバッグするとき。

このスキルを使わない場面

• 永続的なスキルの指示を必要としない、単純なタスクを実行するとき。
• 一般的な会話の応答。

基本的なプロセス

ステップ 1：ユーザーの問題を定義する

ユーザーが直面している具体的な失敗のパターンや知識の不足を特定します。このスキルがなかった場合、どのようなことが起きるでしょうか？（情報源：システム設計）

ステップ 2：失敗するテストケースを書く

一般的な LLM（または現在のスキル）が失敗するような、プロンプトやシナリオの例を作成します。これが TDD の「Red」フェーズです。（情報源：システム設計）

ステップ 3：受け入れ基準を定義する

スキルが成功したとみなされるために満たすべき、具体的でテスト可能な振る舞いを 3〜5 個挙げます。（情報源：システム設計）

ステップ 4：スキルの内容を作成する

適切な厳密さのテンプレート（完全な厳密さ、または標準的な厳密さ）に従ってスキルを作成します。すべての原則が、ステップ 1 で特定した失敗のパターンに直接対応するようにします。（情報源：システム設計）

ステップ 5：テストケースを実行する

ステップ 2 で作成した失敗するテストケースを、新たに作成したスキルに対して実行します。出力が受け入れ基準を満たしていれば、スキルは合格です。（情報源：システム設計）

スキル間の呼び出し

必須のサブスキル：なし 推奨されるサブスキル：prompt-optimizer — テストケースとスキルの指示を改善するために使用します。

合理化の一覧

考え	実態
「言いたいことは分かっているので、テストケースは必要ありません。」	テストがなければ、そのスキルが実際に LLM の振る舞いを変えるかどうか分かりません。
「テストを書くには時間がかかりすぎます。」	デプロイ後に壊れたスキルを修正するには、10 倍の時間がかかります。
「このスキルは TDD を使うほど複雑ではありません。」	単純なスキルほど、一般論の寄せ集めが紛れ込みやすいものです。
「スキルを書き終えてからテストを書きます。」	それでは目的が失われます。スキルがすでに合格できるテストを、無意識に書いてしまうでしょう。

注意すべき兆候

次のように考えたら、立ち止まってください。近道をしようとしています。

• 「とりあえず書き始めて、どうなるか見てみよう」→ ステップ 1 とステップ 2 を飛ばしています。
• 「スキルがなくてもテストケースに合格した」→ テストケースが弱すぎます。実際の失敗のパターンを表していません。
• 「包括的に見えるから、うまくいくと考えておこう」→ ステップ 5 を飛ばしています。

診断チェックリスト

• 失敗するテストケース（プロンプト／シナリオ）が文書化されていますか？
• 受け入れ基準は、失敗するテストケースを明示的に参照していますか？
• スキルの各原則は、必須の振る舞いに対応していますか？
• スキルをシナリオに対してテストし、合格していますか？
• スキルに、一般論だけで実行可能な指針のない助言が含まれていませんか？

出典

• システム設計 — Pattern Lineage と writing-skills の定義。
• システム設計 — Full Rigor 形式の要件。