OpenSkillIndex← back to search
claude-code

Ai-coding-project-boilerplate skill-optimization

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

install
source · Clone the upstream repo
git clone https://github.com/shinpr/ai-coding-project-boilerplate
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/shinpr/ai-coding-project-boilerplate "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills-ja/skill-optimization" ~/.claude/skills/shinpr-ai-coding-project-boilerplate-skill-optimization-48c59b && rm -rf "$T"
manifest: .claude/skills-ja/skill-optimization/SKILL.md
source content

スキルコンテンツ最適化

基本方針

  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