Skill optimization

スキルコンテンツ最適化

基本方針

1. 指摘ベース: すべての変更は、記録済みの指摘を解消するか、明記されたプロジェクト固有の情報源に従う
2. 具体的: 各パターンに検出条件と変換方法を提供
3. 構造特化: 表現と構成を最適化し、ドメイン知識は変更しない
4. 意図を保持: 構造、表現、制約、コンテキスト、例を変える前に、元の要件を記録する
5. 追跡可能: 適用するすべての変更を、指摘または明記されたプロジェクト情報源へ結び付ける
6. 自己完結: 各pure skillを単独で読み込んでも実行できる状態に保つ。単独での実行に同じ内容が必要な場合は、独立して読み込まれるpure skill間の重複を許容する

コンテンツ最適化パターン

P1: 重大（修正必須）

スキル読み込み時のLLM実行精度に直接影響する問題。

BP-001: 否定形の指示 → 肯定形への変換

検出条件	変換方法
「〜しない」「〜を避ける」「禁止」等の否定形指示	望ましい操作または許可された状態を先に示す。違反が不可逆な運用操作であり、呼び出し元が通常は回復できず、肯定形だけでは境界が曖昧になる場合に限り、明示的な禁止を残す。その場合も、安全な代替手段と境界を越えるための条件を併記する。レビュー可能な品質方針は肯定形に書き換える。

例外の境界例:

• 許容: 「不要になった記録は復元可能なarchiveへ移す。ユーザーが恒久削除を明示的に許可した場合を除き、完全には削除しない」
• 肯定形に書き換え: 「問題を捏造しない」→「全ての指摘をBPパターンまたは9原則に基づいて行う」、「P1問題を省略しない」→「全レビューモードで全P1問題を評価する」、「P1がある時にグレードAを付与しない」→「P1問題が0件の場合のみグレードAを判定する」

品質ポリシー、ロール境界、採点基準、一般的な作業ルールは常に肯定形を使用する。呼び出し元が検証・上書き・破棄する出力は不可逆ではない。

スキルでの例:

• 変更前: 「汎用的な変数名を使わないこと」
• 変更後: 「目的を表す具体的な変数名を使用する（例: xではなくuserId）」

スキルで重大な理由: 禁止だけでは、実行すべき目標状態が示されない。

BP-002: 曖昧な指示 → 具体的な判断基準

検出条件	変換方法
成果に必要な判断を残す曖昧語（「適切に」「良い」「正しく」「ベスト」「明確に」等）で、解釈の違いが実行や検証を実質的に変えるもの	必要な精度を満たす、最も制約の少ない基準で解決する（手順は下記）
形式・長さ・スコープ・トーン・成功基準が未定義でも、想定されるどの解釈でも成果を同等に満たすもの	許容される自由度として扱い、解釈を一つに絞る必要がある場合のみ制約を追加する（下流の利用側が要求する形式はBP-003を参照）

解決手順（1行目の該当箇所向け）:

1. 必要な精度を満たす、最も制約の少ない基準を選ぶ（除外する有効な挙動が最も少ない、測定可能なif-then基準または閾値）。
2. その精度への寄与を記録する: その明確化によって、意図した成果に関するどの観測可能な出力差が改善されるか。
3. その制約コストを記録する: 元の意図が許容していたのに除外してしまう有効な解。
4. 精度への寄与を特定でき、かつ制約コストが元の意図を保つ場合にのみ適用する。
5. 入力やプロジェクトのコンテキストから判断できない場合は、推測せず判断に必要な情報源を記録する。

スキル例外: 入力コンテキストから一意に解決できる表現（例: ユーザーのプロンプトと照合できる状況での「ユーザーが省略した箇所」）は曖昧ではない — 主観的判断ではなく決定論的な処理を記述している。

スキルでの例:

• 変更前: 「エラーは適切に処理する」
• 変更後（基準を情報源から導出した場合）: 「プロジェクトのエラーハンドリング方針（docs/error-handling.md）に従う。外部API呼び出し・ファイルI/O・JSON.parseをtry-catchで囲み、error.name・error.stack・タイムスタンプをログ出力し、呼び出し元での処理が必要な場合はコンテキスト付きで再throwする。」
• 変更後（情報源がない場合）: 「try-catch対象・ログ項目・閾値を根拠なく設定する代わりに、判断に必要な情報源として『エラーハンドリング方針』を記録する。」

スキルで重大な理由: 曖昧な指示は、成果に影響する振る舞いを、基準なしにモデルへ選ばせる。

BP-003: 出力形式の欠落 → 構造化出力の明示

検出条件	変換方法
何をすべきかは書いてあるが成果物の形式が未定義	出力の利用側が要求する構造・フィールド・順序を定義した出力セクションを追加する（パース、振り分け、比較、検証のため）。慣習で形式を選ばない

スキルレビューの出力契約には、BP-001〜BP-008の網羅結果、一意な指摘ID、重大度、場所、引用した根拠、指摘ごとの解決方法、保持すべき要件、未解決の入力、最終評価を含める。スキル作成の出力は、完成したSKILL.mdの内容と、必要な同一ディレクトリ内のreferenceまたはscriptとする。

スキルでの例:

• 変更前: 「コードの問題を分析する」
• 変更後（レビューレポートの利用側が要求する形式）: 「## 検出した問題 を、レポート描画側がパースできるテーブルで出力する: | 重大度 | 箇所 | 説明 | 修正案 |」

スキルで重大な理由: 構造化出力の制約はハルシネーションを抑制し、スキル適用結果の一貫性を確保する。

P2: 高影響（修正推奨）

対処により実効性が向上する問題。

BP-004: 未構造化コンテンツ → 整理されたフォーマット

検出条件	変換方法
見出しのない文章の塊	標準セクション順序を適用（下記参照）
複数トピックが1セクションに混在	見出し付きの個別セクションに分割
参照データがリスト形式のまま	テーブル形式に変換

標準セクション順序:

1. コンテキスト/前提条件
2. 中核概念（定義、パターン）
3. プロセス/手順（ステップ形式）
4. 出力形式/具体例
5. 品質チェックリスト
6. 参照

適用条件: 30行未満かつ単一トピックのスキルには構造化を省略。

BP-005: コンテキストの不足・過剰 → 必要十分なコンテキスト

検出条件	変換方法
記述されていない前提知識に依存	必要な前提を列挙したPrerequisitesセクションを追加
定義なしにドメイン用語を使用	インラインまたは用語テーブルで定義を追加。スキル例外: LLMのベースライン知識に含まれる用語（広く使われる技術用語、標準的なドメイン語彙）は定義不要。プロジェクト固有の用語、内部命名規則、LLMの一般知識に含まれないドメイン用語のみ明示的な定義が必要。
使用場面の指針がない	具体的なシナリオ付きのトリガー条件を追加
重複している、注意をそらす、または下流の判断・実行・検証に影響しないコンテキスト	繰り返される事実を一つの実効的な記述に集約する。抽出した事実だけが必要な場合は、元の背景情報はパスや参照の形で残す。プロジェクト固有の事実には情報源を明記する。

スキルでの例:

• 変更前: 「移行にはStrangler Patternを適用する」
• 変更後: 「前提: モジュール境界が識別可能な既存モノリス。使用場面: 本番トラフィックを維持しながらレガシーモジュールを置換する場合。」

BP-006: 複雑な内容 → ステップ分解

検出条件	変換方法
1つの指示に3つ以上の目的	番号付きステップに分解し、各ステップに完了を示す観測可能な出力と、次へ進むための遷移条件を明記する
順序依存が暗黙的	各ステップの遷移条件を、直前のステップの観測可能な出力に依存させる
依存関係のある複数の動作が1ステップにまとまっている	各動作が完了を示す観測可能な出力を生成してから次へ進むよう分割する

適用条件: 単純な参照テーブルや単一基準のルールには分解を省略。

要点: 目的は「分解すること」ではなく、外部から観測可能な状態遷移にすること — 各ステップが、次のステップへ進めるかを判定するための観測可能な出力を生成する。

作成と網羅的レビューでは、以下の3つのゲートを順に使用する：

1. 分析ゲート: 元の要件を記録し、BP-001〜BP-008をすべて確認し、各指摘に根拠があり、忠実な作業を妨げる未解決の入力がない
2. 最適化ゲート: 各指摘に適用または見送りの解決方法が1つあり、すべての変更を追跡でき、保持すべき要件が残っている
3. バランスゲート: 意図の保持、判断に必要な情報、情報密度、制約の必要性、追跡可能性を確認してから最終結果とする

P3: 改善（対応可能なら）

特定の状況で効果がある段階的な改善。

BP-007: 不要または偏った例示 → 必要最小限の例

検出条件	変換方法
LLMが既に知っている挙動を例が繰り返しているだけ	簡潔なルールまたは利用側が要求する出力形式に置き換え、例を削除する
ドメイン・製品・組織固有のマッピング、非自明な例外、ルールで表現できない境界を例が担っている	解消対象の曖昧さを覆う最小限の例集合だけ残し、各例を「解消する曖昧さ」に対応づける
複数の例が同じ曖昧さを解消している、または全例が同じ表層パターン	解消対象の曖昧さを覆う最小限の例集合まで削減し、別の曖昧さを解消する場合のみ異なるケースを追加する

BP-008: 不確実性の許容なし → 明示的なエスカレーション

検出条件	変換方法
常に確定的な回答を要求	主張を観測事実・推論・不明に分類し、曖昧な場合のエスカレーション基準を追加
「いつ止めるか」の指針がない	「不明」が次のステップを塞ぐ場合、そのゲートで停止し、続行に必要なエビデンスまたはユーザー判断を明示する

スキルでの例:

• 変更前: 「根本原因を特定する」
• 変更後: 「根本原因を観測済み、推測、不明のいずれかに分類する。不足している根拠によって次のステップへ進めない場合は、現在のゲートで止まり、継続に必要な根拠またはユーザー判断を具体的に示す。」

9つの編集原則

スキルコンテンツの測定可能な品質基準。各原則に合否判定基準を設定。

#	原則	合格基準	不合格例
1	コンテキスト効率	全文がLLMの判断に寄与する。冗長な記述なし	「これは〜に役立つ重要なスキルで...」
2	重複排除	1つのスキル内で同じ抽象度の概念を二重に説明しない。独立して読み込まれるpure skill間の重複は、各スキルの単独実行に必要な場合は有効とする。その場合はsibling skillへの参照に置き換えず、意味の整合性を確認する	1つのスキル内で、異なる実行上の役割を加えずに同じルールを再記述
3	関連内容の集約	関連する基準を1セクションに集約（読み込み回数最小化）	エラーハンドリング規則が4セクションに散在
4	測定可能性	各基準が観測可能なエビデンス、決定論的な判断ルール、または根拠のある閾値を示す	「きれいなコードを書く」に観測可能な条件がない
5	肯定形	指示は「何をするか」を記述（BP-001適用済み）	「一切使わないこと」→「Xのみ使用する」
6	表記の一貫性	見出しレベル、リスト記法、テーブル形式が統一	同一文脈で-、*、1.が混在
7	前提条件の明示	プロジェクト固有・非ベースラインの前提を記述またはリンクする。ベースラインの技術知識は簡潔にとどめる	「DI」を定義もリンクもせずに使用
8	重要度順の記述	最重要項目が先頭、例外は末尾	エッジケースが共通パターンより先に記述
9	スコープ境界	スキルが扱う範囲と、条件付き内容を有効にする条件を明示する。pure skillは単独実行に必要なコンテキストを自身に含める。スキル間参照は、orchestrationまたはskill selectionを担うスキルに限定する	他のpure skillにも同じ内容があることを理由に、実行に必要なルールがpure skillから欠けている

References

• スキル生成時: references/creation-guide.md - 生成フローとdescription指針
• スキルレビュー時: references/review-criteria.md - 評価フローとグレード判定基準