skill-optimization

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