writing-skills

スキルの作成

概要

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

スキルは文章ではなく、動作を形作るコードです。失敗するテスト（スキルがないとエージェントが誤るプレッシャーシナリオ）を書き、失敗することを確認してから、それを修正する最小限のスキルを書き、成功することを確認し、その後、抜け穴をふさぎます。

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

鉄則：

NO SKILL WITHOUT A FAILING BASELINE FIRST

これは、新しいスキルにも既存スキルの編集にも当てはまります。「簡単な追加」「セクションを1つ追加するだけ」「ドキュメントの更新」も、すべて同じ違反です。テストする前にスキルを書いてしまった場合は、削除して最初からやり直してください。

使用する場面

• このリポジトリ用の新しいスキルを作成するとき（CONTRIBUTING.md も読んでください。新しいスキルは事前に issue で合意し、評価カバレッジを含めて公開する必要があります）
• skills/**/SKILL.md の内容を編集するとき
• スキルの内容を変更する PR をレビューするとき

使用しない場面： プロジェクト固有の規約（それらは team-ai-directives リポジトリの CDR に記載します）や、スクリプトまたはテストで強制できる機械的な制約には使用しないでください。そうした制約は自動化し、ドキュメントは判断が必要な事柄のために使ってください。

基本プロセス

RED — 失敗のベースラインを取る

スキルを読み込まずにシナリオを実行します。次の内容を逐語的に記録してください。

• エージェントが実際に行ったこと
• 正しい動作を省くために使った、具体的な言い訳
• 失敗を引き起こしたプレッシャー（時間、サンクコスト、権威、「どちらでも動く」など）

スキルなしですでにエージェントが正しく動作する場合は、そこで止めてください。修正するものはありません。 自然にできる動作を強制するスキルは、コンテキストのノイズです（このリポジトリはコンテキストのノイズを増やすのではなく、減らすために存在します）。

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

このディレクトリにあるテンプレート（templates/SKILL-template.md）から始めます。RED で確認した失敗だけに対処し、仮定上の失敗には対処しません。

同じシナリオをスキルを読み込んだ状態で実行します。エージェントは今度は指示に従うはずです。

REFACTOR — 抜け穴をふさぐ

新たな言い訳が見つかりましたか？ 明示的な反論を追加し、再テストしてください。プレッシャーの下でも確実に動作するまで繰り返します。

全シナリオの前に文言をマイクロテストする

プレッシャーをかけた全シナリオの実行には時間がかかります。まずは低コストで文言を検証してください。サンプルごとに新しい API 呼び出しまたはサブエージェント呼び出しを1回行い、各バリアントを5回以上試し、必ずガイダンスなしの対照条件を含めてください。対照条件で失敗が見られないなら、修正するものはありません。検出された一致はすべて手動で確認してください。自動集計では、失敗も成功も過大に見積もられます。

構成ルール（このリポジトリ）

ルール	理由
深さは正確に2階層：skills/<domain>/<skill>/SKILL.md	test_skill_directory_depth で強制され、skills CLI の深さ制限にも対応します
Frontmatter：name と description が必須（合計1024文字以下）	test_skill_description_presence_and_length で強制されます
scripts:（sh:／ps:）と disable-model-invocation: true は任意	モデルから呼び出してはならないスキルを示します
Description はトリガーのみを記載	以下を参照してください。スキルが気づかれないまま機能しなくなる原因として、最もよくあるものです
見出し：Overview → When to Use → Core Process → Red Flags → Verification	標準的な構成です。スキルに調整項目がある場合に限り、Configuration を追加します
トークン予算：SKILL.md 本文は500行未満を目標にします（500行超で警告、800行超で失敗するよう強制されます。test_skill_token_budget を参照）	大量のリファレンス資料は references/ に、スクリプトは scripts/{bash,powershell}/ に配置します
新しいスキルには評価カバレッジを含めます	Goldset の基準と二値評価器（{"pass": bool, "score": 1.0|0.0}）を用います。evals/promptfoo/ を参照してください

スキルの検出最適化（SDO）

description はトリガーとなる部分です。factory-mission は各スキルの名前と説明をすべてサブエージェントに渡し、モデルはその一覧から何を読み込むかを判断します。

説明には使用する場面を書きます。スキルの内容は決して書きません。

測定された失敗パターン（このスキルが応用している superpowers の writing-skills を参照）：説明にワークフローを要約すると、エージェントはスキル本文を読む代わりに説明に従います。「タスク間でコードレビューを行う」と説明した結果、スキルのフローチャートでは明らかに2回必要とされていたレビューが1回だけ行われました。

# BAD: workflow summary — agents will follow this shortcut
description: Bootstraps the session by injecting the team context index and pulls rules on demand

# GOOD: trigger only
description: Use when a session starts and the team AI directives context is not yet loaded

• 「Use when…」で始め、具体的な症状や状況を挙げます
• 三人称で書きます（プロンプトに挿入されるため）
• エージェントが検索に使いそうなキーワードを含めます：エラーメッセージ、症状、ツール名
• disable-model-invocation: true を設定したスキルは（モデルによって振り分けられないため）対象外ですが、誤解を招く説明にしてはいけません

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

ガイダンスを書く前に、まずベースラインで起きた失敗を分類します。ある失敗の種類に対して有効な形式が、別の種類では逆効果になることがあります。

ベースラインでの失敗	適切な形式	不適切な形式
プレッシャー下でルールを無視する（正しいことは分かっているのに、そのとおりにしない）	禁止事項＋正当化の一覧表＋危険信号	やわらかなガイダンス（「～を優先する」「～を検討する」）
出力の形式が違う（冗長、結論が埋もれている）	肯定的な手順：出力の内容と、その構成要素を順番に示す	禁止事項の一覧（「言い直さない」「決して説明しない」）
必須要素が抜ける	構造で指定：テンプレートに必須の項目を設ける	テンプレートの近くに注意書きを置く
条件によって動作が変わる	観察可能な述語に基づく条件付きルール	例外条項付きの無条件ルール

どちらの場合も、ニュアンスを加える条項は設けません。「重要な場合を除いて X しない」とすると、再び交渉の余地が生まれます。効果のある手順にニュアンスを加えるだけでも、その効果が損なわれます。

ルールを徹底するスキルの抜け穴対策

ルールを徹底するスキルでは、すべての抜け穴を明示的に塞ぎます。具体的な抜け道を禁止し（「参考資料として残さない。削除するとは、削除することです」）、根本原則を早い段階で示し（「ルールの文言に違反することは、その精神に違反することです」）、RED のトランスクリプトから正当化の一覧表を作り、エージェントが自分で確認できる危険信号を列挙します。

危険信号

• ベースラインの実行前にスキルを書いた — 削除して最初からやり直す
• 説明が使用する場面ではなく、スキルの内容を要約している
• 「エージェントは当然、正しいことをするはず」— RED はその確認のためにあります
• スキルが約500行を超えて膨らみ、すべてが references/ ではなくインラインになっている
• 評価基準と採点器を用意せずに新しいスキルを公開した
• 仮定上の失敗には対処しているが、実際に観察された失敗には対処していない

これらに当てはまる場合は、作業を止め、ベースラインを再実行してスキルを修正してください。

検証

以下の項目がすべて満たされたら、スキルの変更は完了です。

• スキルを使わずにベースラインのシナリオを実行し、失敗をそのまま記録した
• 同じシナリオがスキルを使うと成功する
• pytest tests/unit/test_playbook_integrity.py -q が成功する（深さ、フロントマター、説明のルール）
• 評価基準と二値判定の採点器を追加し、採点器のユニットテストも用意した（evals/promptfoo/tests/）
• 再生成したインストール成果物が同期している： pytest tests/unit/test_generated_artifacts_sync.py -q
• 実際のエージェントで手動の受け入れ確認を行った（CONTRIBUTING の「Manual testing」）— スキルは必要なときに作動し、不要なときは作動しない

参考資料

• templates/SKILL-template.md — 新しいスキルの出発点
• references/skill-testing.md — プレッシャーシナリオ、プレッシャーの種類、マイクロテストの方法論
• CONTRIBUTING.md — PR プロセス、評価カバレッジの要件、手動テストの手順