skill-optimization

name	skill-optimization
description	スキルファイルの品質を9つのコンテンツパターンと10の編集原則で評価・最適化。スキル作成、内容改善、品質監査時に使用。

スキルコンテンツ最適化

基本方針

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

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

P1: 重大（修正必須）

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

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

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

例外の境界例:

• 許容: 「不要になった記録は復元可能なarchiveへ移す。ユーザーが恒久削除を明示的に許可した場合を除き、完全には削除しない」
• 肯定形に書き換え: 「問題を捏造しない」→「全ての指摘をBPパターンまたは10原則に基づいて行う」、「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-009の網羅結果、再レビューでも維持する指摘ID、重大度、場所、引用した根拠、根拠付きで却下した指摘、保持すべき要件、未解決の入力、最終評価を含める。スキル作成の出力は、完成したSKILL.mdの内容と、必要な同一ディレクトリ内のreferenceまたはscriptとする。

スキルでの例:

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

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

BP-009: 作業の無制限な生成 → 成果に比例した作業

検出条件	変換方法
指摘、可能性、または技術的に有効な改善が、成果、必要な境界、実際の利用側、必要な証明を変えないまま必須作業になる	候補として扱い、必要な作業だけを残し、変更なし、再利用、根拠に基づく却下を許容する
調査範囲が実装または成果物の範囲を決める	必要な成果を観測できた時点で完了し、発見だけを理由に作業を増やさない

スキルで重大な理由: 能力の高いモデルは暗黙の義務も実行するため、根拠のない可能性が成果を改善せずに作業を生み出す。

P2: 高影響（修正推奨）

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

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

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

標準セクション順序:

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

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

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

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

スキルでの例:

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

BP-006: 手続き制御の不足・過剰 → 根拠に基づくゲート

検出条件	変換方法
前提となる根拠がなければ後続の操作が無効になる	必要な根拠と遷移条件を示すゲートを追加する
権限、不可逆な操作、機械が読み取る契約、完了証明が暗黙的	その境界を明示する
可逆な選択に一つの経路を必須としている	目的、根拠、選択基準を示し、経路はモデルに選択させる
機械による厳密な形式要求がないのに、特定のラベルや成果物だけをゲートが要求する	意味的に同等な根拠を受け入れる

要点: 予測した経路ではなく、境界と必要な根拠を制御する。

スキル作成では、以下の3つのゲートを順に使用する：

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

レビュー指摘に基づく修復では、現状レビューを分析の根拠とし、合意済みの修復範囲に最適化ゲートとバランスゲートを適用する。

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

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

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

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

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

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

スキルでの例:

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

10の編集原則

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

#	原則	合格基準	不合格例
1	コンテキスト効率	各文がベースライン外の知識、判断規則、必要な境界、または実行根拠を提供する	観測された失敗、レビュー指摘、プロジェクト要件との関係がないベースライン知識の説明
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から欠けている
10	作業量の妥当性	必須の成果物、テスト、ゲート、判断が、成果、境界、利用側の結果、または必要な証明を変える	全ての指摘や技術的に有効な改善を実装必須にする

References

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