---
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](references/creation-guide.md) - 生成フローとdescription指針
- **スキルレビュー時**: [references/review-criteria.md](references/review-criteria.md) - 評価フローとグレード判定基準