shinpr/skill-optimization

スキルコンテンツ最適化

基本方針

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