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

# スキルコンテンツ最適化

## 基本方針

1. **根拠に基づく**: プロンプト工学の研究成果をスキル執筆に応用
2. **具体的**: 各パターンに検出条件と変換方法を提供
3. **構造特化**: 表現と構成を最適化し、ドメイン知識は変更しない

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

### P1: 重大（修正必須）

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

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

| 検出条件 | 変換方法 |
|----------|----------|
| 「〜しない」「〜を避ける」「禁止」等の否定形指示 | 同等の制約を持つ肯定形の指示に変換。**例外**: 以下の4条件を**全て**満たす場合のみ否定形を保持: (1) 違反が1ステップで状態を破壊する、(2) 呼び出し元や後続ステップで通常回復できない、(3) 品質ポリシーやロール境界ではなく操作/手続き上の制約である、(4) 肯定形に書き換えると対象範囲が拡大・曖昧化する。いずれか1つでも満たさない場合は肯定形に書き換える。 |

**例外の境界例**:
- 許容: 「コマンドを変更しない」「フラグを追加しない」「破壊的操作を実行しない」
- 肯定形に書き換え: 「問題を捏造しない」→「全ての指摘をBPパターンまたは9原則に基づいて行う」、「P1問題を省略しない」→「全レビューモードで全P1問題を評価する」、「P1がある時にグレードAを付与しない」→「P1問題が0件の場合のみグレードAを判定する」

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

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

**スキルで重大な理由**: LLMの注意機構は否定された内容に集中する。「〜するな」という指示は禁止行為の出現確率をむしろ高める。

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

| 検出条件 | 変換方法 |
|----------|----------|
| 「適切に」「良い」「正しく」「ベスト」「明確に」等 | 測定可能なif-then基準または具体的な閾値に置換。**スキル例外**: 入力コンテキストから一意に解決できる表現（例: ユーザーのプロンプトが参照可能な状況での「ユーザーが省略した箇所」）は曖昧ではない。主観的判断ではなく機械的に特定できる処理を記述している。 |
| 出力形式・スコープ・成功基準が未定義 | 明示的な制約を追加 |

**スキルでの例:**
- 変更前: 「エラーは適切に処理する」
- 変更後: 「エラーハンドリング基準: 1. try-catch必須: 外部API呼び出し、ファイルI/O、JSON.parse 2. ログ必須項目: error.name、error.stack、タイムスタンプ 3. 呼び出し元での処理が必要な場合はコンテキスト付きで再throw」

**スキルで重大な理由**: 実行精度の差異の約40%は曖昧な指示に起因する。曖昧な記述はLLMに推測を強いる。

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

| 検出条件 | 変換方法 |
|----------|----------|
| 何をすべきかは書いてあるが成果物の形式が未定義 | 構造・フィールド・例を含む出力セクションを追加 |

**スキルでの例:**
- 変更前: 「コードの問題を分析する」
- 変更後: 「出力形式: `## 検出した問題` テーブル形式: | 重大度 | 箇所 | 説明 | 修正案 |」

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

### P2: 高影響（修正推奨）

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

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

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

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

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

#### BP-005: コンテキスト不足 → 前提条件の明示

| 検出条件 | 変換方法 |
|----------|----------|
| 記述されていない前提知識に依存 | 必要な前提を列挙したPrerequisitesセクションを追加 |
| 定義なしにドメイン用語を使用 | インラインまたは用語テーブルで定義を追加。**スキル例外**: LLMのベースライン知識に含まれる用語（広く使われる技術用語、標準的なドメイン語彙）は定義不要。プロジェクト固有の用語、内部命名規則、LLMの一般知識に含まれないドメイン用語のみ明示的な定義が必要。 |
| 使用場面の指針がない | 具体的なシナリオ付きのトリガー条件を追加 |

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

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

| 検出条件 | 変換方法 |
|----------|----------|
| 1つの指示に3つ以上の目的 | チェックポイント付きの番号付きステップに分解 |
| 順序依存が暗黙的 | ステップ間の依存関係を明示 |
| 中間検証がない | 各ステップ後にチェックポイントを挿入 |

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

**要点**: 目的は「分解すること」ではなく、品質チェックポイント付きの**評価可能な粒度**にすること。

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

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

#### BP-007: 偏った例示 → 多様なカバレッジ

| 検出条件 | 変換方法 |
|----------|----------|
| 全例が同じパターン/構造 | エッジケースと例外を追加 |
| 正常系の例のみ | エラーケース、境界条件を追加 |
| 全例が同じ複雑度 | 簡単・中程度・複雑の例を含める |

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

| 検出条件 | 変換方法 |
|----------|----------|
| 常に確定的な回答を要求 | 曖昧な場合のエスカレーション基準を追加 |
| 「いつ止めるか」の指針がない | 明示的な停止条件を追加 |

**スキルでの例:**
- 変更前: 「根本原因を特定する」
- 変更後: 「根本原因を特定する。3回の調査サイクル後も不確定な場合は、上位3仮説を信頼度と根拠付きで報告する。」

## 9つの編集原則

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

| # | 原則 | 合格基準 | 不合格例 |
|---|------|----------|----------|
| 1 | コンテキスト効率 | 全文がLLMの判断に寄与する。冗長な記述なし | 「これは〜に役立つ重要なスキルで...」 |
| 2 | 重複排除 | スキル内・スキル間で同じ抽象レベルにおける概念の重複説明なし。異なる構造的役割（例: 分類体系と実行詳細）での言及は、新たな制約や判断基準を伴う場合に限り重複に該当しない | 関連する複数スキルで同じエラーハンドリング規則が同じ抽象レベルで繰り返される |
| 3 | 関連内容の集約 | 関連する基準を1セクションに集約（読み込み回数最小化） | エラーハンドリング規則が4セクションに散在 |
| 4 | 測定可能性 | 全基準がif-then形式または具体的閾値 | 「きれいなコードを書く」の定義なし |
| 5 | 肯定形 | 指示は「何をするか」を記述（BP-001適用済み） | 「一切使わないこと」→「Xのみ使用する」 |
| 6 | 表記の一貫性 | 見出しレベル、リスト記法、テーブル形式が統一 | 同一文脈で`-`、`*`、`1.`が混在 |
| 7 | 前提条件の明示 | 暗黙の前提知識が全て記述されている | 「DI」を定義せずに使用 |
| 8 | 重要度順の記述 | 最重要項目が先頭、例外は末尾 | エッジケースが共通パターンより先に記述 |
| 9 | スコープ境界 | このスキルが扱う範囲と他スキルへの参照が明示 | 他スキルと重複する記述に相互参照なし |

## References

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