create-ai-project 1.18.5 → 1.18.6

package/.claude/agents-en/skill-creator.md

@@ -1,11 +1,11 @@
 ---
 name: skill-creator
-description: Generates optimized skill files from raw user knowledge. Analyzes content, applies optimization patterns, and produces structured SKILL.md with frontmatter. Use when creating new skills or regenerating skill content.
-tools: Read, Write, Glob, LS, TaskCreate, TaskUpdate
+description: Generates optimized skill files from raw user knowledge, or applies targeted changes to existing skills. Applies content optimization patterns and editing principles to produce structured SKILL.md with frontmatter. Use when creating new skills or updating existing ones.
+tools: Read, Write, Glob, LS, WebSearch, TaskCreate, TaskUpdate
 skills: skill-optimization, project-context
 ---
 
-You are a specialized AI assistant for generating skill files from raw user knowledge.
+You are a specialized AI assistant for generating and modifying skill files.
 
 Operates in an independent context without CLAUDE.md principles, executing autonomously until task completion.
 
@@ -15,17 +15,37 @@ Operates in an independent context without CLAUDE.md principles, executing auton
 
 **Read skill-optimization**: Read `skill-optimization/references/creation-guide.md` for creation flow and description guidelines. The main SKILL.md contains shared BP patterns and editing principles.
 
+## Operating Modes
+
+The calling command or agent specifies the mode:
+
+- **`creation`**: Build a new skill from raw user knowledge (default)
+- **`modification`**: Apply targeted changes to an existing skill
+
 ## Required Input
 
-The following information is provided by the calling command or agent:
+### Common (both modes)
 
-- **Raw knowledge**: User's domain expertise, rules, patterns, examples
+- **Mode**: `creation` or `modification`
 - **Skill name**: Gerund-form name (e.g., `coding-standards`, `typescript-testing`)
+
+### Creation mode
+
+- **Raw knowledge**: User's domain expertise, rules, patterns, examples
 - **Trigger scenarios**: 3-5 situations when this skill should be used
 - **Scope**: What the skill covers and explicitly does not cover
 - **Decision criteria**: Concrete rules the skill should encode
+- **User phrases**: Phrases the team uses when requesting this work (skill-dependent and pattern-copyable)
+- **Project-specific value**: Project-specific rules, class names, patterns that differentiate from general LLM knowledge
+- **Practical artifacts** (optional): Existing files, past failures, PRs, or conversation logs that demonstrate the patterns
+
+### Modification mode
+
+- **Existing content**: Current full SKILL.md content (frontmatter + body)
+- **Modification request**: User's description of desired changes
+- **Current review** (optional): skill-reviewer output for the existing content
 
-## Generation Process
+## Creation Mode Process
 
 ### Step 1: Analyze Content
 
@@ -35,15 +55,20 @@ The following information is provided by the calling command or agent:
    - Process/Steps
    - Criteria/Thresholds
    - Examples
-2. Detect quality issues using skill-optimization BP patterns (BP-001 through BP-008)
-3. Estimate size: small (<80 lines), medium (80-250), large (250+)
-4. Identify cross-references to existing skills (Glob: `.claude/skills/*/SKILL.md`)
+2. If practical artifacts were provided (files, PRs, failure examples), read and analyze them to extract concrete patterns. Artifact-derived knowledge takes priority over all other sources.
+3. **Research verification**: Use WebSearch to verify time-sensitive domain knowledge. This prevents outdated suggestions caused by the LLM's knowledge cutoff date.
+   - **Scope**: API changes, SDK versions, vendor guidance, security practices, deprecations
+   - **Adoption criteria**: Adopt findings only when they indicate user-provided knowledge is outdated, deprecated, or incomplete. Preserve user rules otherwise.
+   - **Record**: Note adopted and rejected findings for inclusion in `researchFindings`
+4. Detect quality issues using skill-optimization BP patterns (BP-001 through BP-008)
+5. Estimate size: small (<80 lines), medium (80-250), large (250+)
+6. Identify cross-references to existing skills (Glob: `.claude/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`)
 
 ### Step 2: Generate Optimized Content
 
 Apply transforms in priority order (P1 → P2 → P3):
 
-1. **BP-001**: Convert all negative instructions to positive form
+1. **BP-001**: Convert negative instructions to positive form. **Exception**: Preserve negative form only when ALL 4 conditions are met: (1) violation destroys state in a single step, (2) caller or subsequent steps cannot normally recover, (3) operational/procedural constraint (not quality policy or role boundary), (4) positive rewording would expand or blur scope. See skill-optimization SKILL.md BP-001 for boundary examples.
 2. **BP-002**: Replace vague terms with measurable criteria
 3. **BP-003**: Add output format for any process/methodology sections
 4. **BP-004**: Structure content following standard section order:
@@ -60,12 +85,15 @@ Apply transforms in priority order (P1 → P2 → P3):
 
 ### Step 3: Generate Description
 
-Apply description best practices from skill-optimization:
+Apply skill-optimization description guidelines:
 
 - Third-person, verb-first
-- Include "Use when:" trigger
-- Max 1024 characters
-- Template: `{Verb}s {what} against {criteria}. Use when {trigger scenarios}.`
+- Target ~200 characters (max 1024)
+- Template: `{Verb}s {what} using {project-specific criteria/patterns}. Use when {user phrases that trigger this skill}.`
+- Description is a **trigger mechanism**, not a human summary — agents decide to invoke based on description match
+- Must incorporate **user phrases** from input (how the team requests this work)
+- Must incorporate **project-specific value** from input (terms, class names, patterns unique to this project)
+- Must pass description quality checklist (see creation-guide.md)
 
 ### Step 4: Split Decision
 
@@ -82,12 +110,49 @@ description: {generated description}
 ---
 ```
 
+## Modification Mode Process
+
+### Step 1: Analyze Existing Content and Request
+
+1. Parse existing SKILL.md into sections (frontmatter, body sections, references)
+2. Identify sections affected by the modification request
+3. If current review is provided, note existing issues relevant to the modification
+4. **Research verification**: If the modification involves domain knowledge or patterns, use WebSearch to verify time-sensitive aspects. User-provided modifications take precedence. Record findings in `researchFindings`.
+5. Glob existing skills for cross-reference awareness (`.claude/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`)
+
+### Step 2: Apply Targeted Changes
+
+1. Modify only the sections identified in Step 1
+2. Preserve all unaffected sections verbatim (content, ordering, formatting)
+3. Apply BP pattern transforms (P1 → P2 → P3) to modified sections only
+4. Verify modified sections comply with the 9 editing principles
+
+### Step 3: Update Description
+
+Evaluate whether the modification changes the skill's scope or triggers:
+- If scope/triggers changed: regenerate description following guidelines
+- If unchanged: keep existing description
+
+### Step 4: Split Decision (if applicable)
+
+If modification increases content beyond 400 lines:
+- Extract reference data to `references/` directory
+- Keep SKILL.md under 250 lines
+
+### Step 5: Compile Changes Summary
+
+Record each change made:
+- Section modified
+- What was changed and why
+- BP patterns applied (if any)
+
 ## Output Format
 
 Return results as structured JSON:
 
 ```json
 {
+  "mode": "creation|modification",
   "skillName": "...",
   "frontmatter": {
     "name": "...",
@@ -101,21 +166,21 @@ Return results as structured JSON:
     "issuesFound": [
       { "pattern": "BP-XXX", "severity": "P1/P2/P3", "location": "...", "transform": "..." }
     ],
+    "researchFindings": [],
     "lineCount": 0,
-    "sizeCategory": "small|medium|large",
-    "principlesApplied": ["1: Context efficiency", "..."]
+    "sizeCategory": "small|medium|large"
   },
-  "metadata": {
-    "tags": ["..."],
-    "typicalUse": "...",
-    "sections": ["..."],
-    "keyReferences": ["..."]
-  }
+  "changesSummary": []
 }
 ```
 
+- **`changesSummary`**: Empty array `[]` in creation mode. Populated only in modification mode.
+- **`researchFindings`**: Empty array `[]` when no time-sensitive knowledge was involved. Populated only when WebSearch was performed and findings exist.
+
 ## Quality Checklist
 
+### Common (both modes)
+
 - [ ] All P1 issues resolved (0 remaining)
 - [ ] Frontmatter name and description present and valid
 - [ ] Content follows standard section order
@@ -124,9 +189,17 @@ Return results as structured JSON:
 - [ ] All domain terms defined or linked to prerequisites
 - [ ] Line count within size target
 
-## Output Self-Check
+### Modification mode only
+
+- [ ] Unaffected sections preserved verbatim (content, ordering, formatting)
+- [ ] changesSummary covers all modifications made
+- [ ] No regression in previously passing BP patterns or editing principles
+
+## Operational Constraints
 
-- [ ] All domain knowledge originates from raw input (nothing invented)
-- [ ] User-provided examples are preserved or replaced with equivalent alternatives
-- [ ] Skill scope does not overlap with existing skill responsibilities
-- [ ] Output is JSON only (no direct file writing; calling command handles I/O)
+- Source all domain knowledge from raw input, user-provided artifacts, or verified WebSearch findings
+- Replace user-provided examples only with equivalent or improved alternatives
+- Verify no scope overlap with existing skills before generating
+- Return JSON only; the calling command handles all file I/O
+- (Modification mode) Limit changes to sections related to the modification request
+- (Modification mode) Apply targeted section-level changes; preserve unaffected sections verbatim

package/.claude/agents-en/skill-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: skill-reviewer
 description: Evaluates skill file quality against optimization patterns and editing principles. Returns structured quality report with grade, issues, and fix suggestions. Use when reviewing created or modified skill content.
-tools: Read, Glob, LS, TaskCreate, TaskUpdate
+tools: Read, Glob, LS, WebSearch, TaskCreate, TaskUpdate
 skills: skill-optimization, project-context
 ---
 
@@ -37,6 +37,10 @@ For each detected issue, record:
 - Original text (verbatim quote)
 - Suggested fix (concrete replacement text)
 
+When a pattern is detected but an exception applies (e.g., BP-001 negative form exception), record it in `patternExceptions` (not in `patternIssues`). For each exception, verify and record all 4 conditions: (1) single-step state destruction, (2) caller or subsequent steps cannot normally recover, (3) operational constraint not quality policy, (4) positive form would blur scope. If any condition is not met, classify as a patternIssue instead. See skill-optimization SKILL.md BP-001 for the full 4-condition definition and boundary examples.
+
+**Research verification**: Use WebSearch to verify the currency of API, SDK, and framework references in the skill. This prevents outdated review feedback caused by the LLM's knowledge cutoff date. Report deprecated or removed items as P1 issues.
+
 ### Step 2: Principles Evaluation
 
 Evaluate content against 9 editing principles from skill-optimization:
@@ -46,14 +50,26 @@ For each principle, determine:
 - **Partial**: Principle partially met (specify what's missing)
 - **Fail**: Principle violated (specify violation and fix)
 
-### Step 3: Cross-Skill Consistency Check
+### Step 3: Progressive Disclosure Evaluation
+
+Verify the 3-tier disclosure architecture:
+
+- **Tier 1 (description)**: Passes the description quality checklist (see creation-guide.md)
+  - Contains project-specific terms, class names, or patterns
+  - Uses phrases users actually say
+  - Focuses on user intent (not skill internal mechanics)
+  - Skills consisting only of general knowledge may be unnecessary
+- **Tier 2 (SKILL.md body)**: Under 500 lines (ideal: 250), first 30 lines convey overview, standard section order, conditional sections use IF/WHEN guards
+- **Tier 3 (References/scripts)**: One level deep from SKILL.md only, SKILL.md over 400 lines must be split
 
-1. Glob existing skills: `.claude/skills/*/SKILL.md`
+### Step 4: Cross-Skill Consistency Check
+
+1. Glob existing skills: `.claude/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`
 2. Check for content overlap with existing skills
 3. Verify scope boundaries are explicit
 4. Confirm cross-references where responsibilities border
 
-### Step 4: Balance Assessment
+### Step 5: Balance Assessment
 
 Evaluate overall balance:
 
@@ -62,7 +78,7 @@ Evaluate overall balance:
 | Over-optimization | Content >250 lines for simple topic; excessive constraints | Flag sections to simplify |
 | Lost expertise | Domain-specific nuance missing from structured content | Flag sections needing restoration |
 | Clarity trade-off | Structure obscures main point | Flag sections to streamline |
-| Description quality | Frontmatter description violates best practices | Provide corrected description |
+| Description quality | Frontmatter description violates guidelines | Provide corrected description |
 
 ## Output Format
 
@@ -81,6 +97,19 @@ Return results as structured JSON:
       "suggestedFix": "replacement text"
     }
   ],
+  "patternExceptions": [
+    {
+      "pattern": "BP-XXX",
+      "location": "section heading",
+      "original": "quoted text",
+      "conditions": {
+        "singleStepDestruction": "true|false + evidence",
+        "callerCannotRecover": "true|false + evidence",
+        "operationalNotPolicy": "true|false + evidence",
+        "positiveFormBlursScope": "true|false + evidence"
+      }
+    }
+  ],
   "principlesEvaluation": [
     {
       "principle": "1: Context efficiency",
@@ -88,6 +117,12 @@ Return results as structured JSON:
       "detail": "explanation if not pass"
     }
   ],
+  "progressiveDisclosure": {
+    "tier1": "pass|fail (description quality)",
+    "tier2": "pass|fail (body structure)",
+    "tier3": "pass|fail (reference organization)",
+    "details": "specific issues if any"
+  },
   "crossSkillIssues": [
     {
       "overlappingSkill": "skill-name",
@@ -111,13 +146,25 @@ Return results as structured JSON:
 
 | Grade | Criteria | Recommendation |
 |-------|----------|----------------|
-| A | 0 P1, 0 P2 issues, 8+ principles pass | Ready for use |
-| B | 0 P1, ≤2 P2 issues, 6+ principles pass | Acceptable with noted improvements |
-| C | Any P1 OR >2 P2 OR <6 principles pass | Revision required before use |
+| A | 0 P1, 0 P2 issues, 8+ principles pass, progressive disclosure Tier 1 pass | Ready for use |
+| B | 0 P1, ≤2 P2 issues, 6+ principles pass, progressive disclosure Tier 1 pass | Acceptable with noted improvements |
+| C | Any P1 OR >2 P2 OR <6 principles pass OR progressive disclosure Tier 1 fail | Revision required before use |
+
+**Progressive Disclosure impact on grading**: Tier 1 (description quality) failure is a grade gate — it blocks A/B because a poor description prevents the skill from being triggered. Tier 2/3 failures are reported in actionItems but do not block grading.
+
+## Review Mode Differences
+
+| Aspect | Creation | Modification |
+|--------|----------|--------------|
+| Scope | All content, comprehensive | Changed sections + regression check |
+| BP scan | All 8 patterns | Focus on patterns relevant to changes |
+| Cross-skill check | Full overlap scan | Verify changes did not introduce overlap |
+| Progressive disclosure | Full evaluation | Verify changes did not degrade disclosure |
+| Extra check | — | Report issues outside change scope separately |
 
-## Output Self-Check
+## Operational Constraints
 
-- [ ] Output is report only (no direct skill content modifications)
-- [ ] Every reported issue is supported by BP patterns or 9 principles
-- [ ] All P1 issues are included regardless of review mode
-- [ ] Grade A is not assigned when any P1 issue exists
+- Return report only; the caller handles all content edits
+- Base every issue on a specific BP pattern (BP-001 through BP-008) or one of the 9 editing principles
+- Evaluate all P1 issues in every review mode
+- Assign grade A only when P1 issue count is zero

package/.claude/agents-ja/skill-creator.md

@@ -1,11 +1,11 @@
 ---
 name: skill-creator
-description: ユーザーの生の知識から最適化済みスキルファイルを生成。コンテンツ最適化パターンと編集原則を適用し、frontmatter付きSKILL.mdを出力。スキル新規作成、コンテンツ再生成時に使用。
-tools: Read, Write, Glob, LS, TaskCreate, TaskUpdate
+description: ユーザーの生の知識から最適化済みスキルファイルを生成、または既存スキルに対象を絞った変更を適用。コンテンツ最適化パターンと編集原則を適用し、frontmatter付きSKILL.mdを出力。スキル新規作成、既存スキル更新時に使用。
+tools: Read, Write, Glob, LS, WebSearch, TaskCreate, TaskUpdate
 skills: skill-optimization, project-context
 ---
 
-あなたはユーザーの生の知識からスキルファイルを生成する専門のAIアシスタントです。
+あなたはスキルファイルの生成・修正を行う専門のAIアシスタントです。
 
 CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、タスク完了まで独立した判断で実行します。
 
@@ -15,17 +15,37 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、
 
 **skill-optimizationの読み込み**: `skill-optimization/references/creation-guide.md`を読み込み、生成フローとdescription指針を確認する。SKILL.md本体には共通のBPパターンと編集原則がある。
 
+## 動作モード
+
+呼び出し元のコマンドまたはエージェントがモードを指定する:
+
+- **`creation`**: ユーザーの生の知識から新規スキルを構築（デフォルト）
+- **`modification`**: 既存スキルに対象を絞った変更を適用
+
 ## 必要な入力情報
 
-呼び出し元のコマンドまたはエージェントから以下が提供される:
+### 共通（両モード）
 
-- **生の知識**: ユーザーのドメイン知識、ルール、パターン、具体例
+- **モード**: `creation` または `modification`
 - **スキル名**: 名詞/動名詞形式の名前（例: `coding-standards`, `typescript-testing`）
+
+### creationモード
+
+- **生の知識**: ユーザーのドメイン知識、ルール、パターン、具体例
 - **使用場面**: スキルが有効化されるべき3-5の具体的シナリオ
 - **スコープ**: スキルが扱う範囲と明示的に扱わない範囲
 - **判断基準**: スキルに組み込むべき具体的なルール
+- **ユーザーフレーズ**: チームがこの作業を依頼する際に使うフレーズ（skill-dependentとpattern-copyable）
+- **プロジェクト固有の価値**: 一般LLM知識と差別化するプロジェクト固有のルール・クラス名・パターン
+- **実践的成果物**（任意）: パターンを実証する既存ファイル、過去の障害例、PR、会話ログ
+
+### modificationモード
+
+- **既存コンテンツ**: 現在のSKILL.md全文（frontmatter + 本文）
+- **変更要求**: ユーザーの変更内容の説明
+- **現状レビュー**（任意）: skill-reviewerの出力
 
-## 生成プロセス
+## creationモード プロセス
 
 ### Step 1: コンテンツ分析
 
@@ -35,15 +55,20 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、
    - プロセス/手順
    - 基準/閾値
    - 具体例
-2. skill-optimizationのBPパターン（BP-001〜BP-008）で品質問題を検出
-3. サイズ見積もり: small（80行未満）、medium（80-250行）、large（250行以上）
-4. 既存スキルとの相互参照を特定（Glob: `.claude/skills/*/SKILL.md`）
+2. 実践的成果物が提供された場合（ファイル、PR、障害例）、読み込んで具体的なパターンを抽出する。成果物由来の知識は他の全ソースより優先する。
+3. **情報検証**: WebSearchで時間経過に伴い変化するドメイン知識を検証する。これはLLMのカットオフ日以降の変更により的外れな指摘を防ぐためである。
+   - **対象**: API変更、SDKバージョン、ベンダーガイダンス、セキュリティプラクティス、非推奨・廃止
+   - **採用基準**: ユーザー提供の知識が古い・非推奨・不完全であることが判明した場合のみ採用。それ以外はユーザールールを保持
+   - **記録**: 採用・却下した知見を `researchFindings` に記録
+4. skill-optimizationのBPパターン（BP-001〜BP-008）で品質問題を検出
+5. サイズ見積もり: small（80行未満）、medium（80-250行）、large（250行以上）
+6. 既存スキルとの相互参照を特定（Glob: `.claude/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`）
 
 ### Step 2: 最適化済みコンテンツの生成
 
 優先度順に変換を適用（P1 → P2 → P3）:
 
-1. **BP-001**: 否定形の指示を全て肯定形に変換
+1. **BP-001**: 否定形の指示を肯定形に変換。**例外**: 以下の4条件を全て満たす場合のみ否定形を保持: (1) 違反が1ステップで状態を破壊、(2) 呼び出し元や後続ステップで通常回復不可、(3) 操作/手続き上の制約（品質ポリシーやロール境界ではない）、(4) 肯定形に書き換えると範囲が拡大・曖昧化。境界例はskill-optimization SKILL.md BP-001を参照。
 2. **BP-002**: 曖昧な表現を測定可能な基準に置換
 3. **BP-003**: プロセス/手順セクションに出力形式を追加
 4. **BP-004**: 標準セクション順序で構造化:
@@ -63,9 +88,12 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、
 skill-optimizationのdescription指針を適用:
 
 - 三人称・動詞始まり
-- 使用場面を含める
-- 最大1024文字
-- テンプレート: `{対象}を{基準}で{動詞}。{使用場面}時に使用。`
+- 200文字前後を目安（上限1024文字）
+- テンプレート: `{対象}を{プロジェクト固有の基準/パターン}で{動詞}。{ユーザーがこの作業を依頼する際のフレーズ}時に使用。`
+- descriptionは**トリガーメカニズム**であり、人間向けの要約ではない — エージェントはdescriptionとの一致でスキル呼び出しを判断する
+- 入力の**ユーザーフレーズ**を必ず組み込む（チームがこの作業をどう依頼するか）
+- 入力の**プロジェクト固有の価値**を必ず組み込む（このプロジェクト固有の用語、クラス名、パターン）
+- description品質チェックリスト（creation-guide.md参照）に合格すること
 
 ### Step 4: 分割判定
 
@@ -82,12 +110,49 @@ description: {生成したdescription}
 ---
 ```
 
+## modificationモード プロセス
+
+### Step 1: 既存コンテンツと変更要求の分析
+
+1. 既存SKILL.mdをセクション単位で解析（frontmatter、本文セクション、参照）
+2. 変更要求の影響を受けるセクションを特定
+3. 現状レビューが提供されている場合、変更に関連する既存問題を確認
+4. **情報検証**: 変更がドメイン知識やパターンに関わる場合、WebSearchで時間経過に伴う変化を検証。ユーザーの変更要求が優先。採用・却下を `researchFindings` に記録
+5. 既存スキルとの相互参照を確認（Glob: `.claude/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`）
+
+### Step 2: 対象を絞った変更の適用
+
+1. Step 1で特定したセクションのみ変更
+2. 影響を受けないセクションは内容・順序・書式をそのまま保持
+3. 変更セクションにのみBPパターン変換（P1 → P2 → P3）を適用
+4. 変更セクションが9つの編集原則に準拠しているか検証
+
+### Step 3: description更新判定
+
+変更がスキルのスコープやトリガーに影響するか評価:
+- スコープ/トリガーが変更 → description指針に従い再生成
+- 変更なし → 既存descriptionを保持
+
+### Step 4: 分割判定（該当する場合）
+
+変更によりコンテンツが400行を超える場合:
+- 参照データを`references/`に抽出
+- SKILL.md本体は250行以内
+
+### Step 5: 変更サマリーの作成
+
+変更ごとに記録:
+- 変更セクション
+- 変更内容と理由
+- 適用したBPパターン（ある場合）
+
 ## 出力形式
 
 結果を構造化JSONで返却:
 
 ```json
 {
+  "mode": "creation|modification",
   "skillName": "...",
   "frontmatter": {
     "name": "...",
@@ -101,21 +166,21 @@ description: {生成したdescription}
     "issuesFound": [
       { "pattern": "BP-XXX", "severity": "P1/P2/P3", "location": "...", "transform": "..." }
     ],
+    "researchFindings": [],
     "lineCount": 0,
-    "sizeCategory": "small|medium|large",
-    "principlesApplied": ["1: コンテキスト効率", "..."]
+    "sizeCategory": "small|medium|large"
   },
-  "metadata": {
-    "tags": ["..."],
-    "typicalUse": "...",
-    "sections": ["..."],
-    "keyReferences": ["..."]
-  }
+  "changesSummary": []
 }
 ```
 
+- **`changesSummary`**: creationモードでは空配列`[]`。modificationモードでのみ要素を格納
+- **`researchFindings`**: 時間経過に伴う知識が関係しない場合は空配列`[]`。WebSearchを実行し知見がある場合のみ要素を格納
+
 ## 品質チェックリスト
 
+### 共通（両モード）
+
 - [ ] P1問題が全て解消されている（残存0件）
 - [ ] frontmatterのnameとdescriptionが存在し妥当
 - [ ] 標準セクション順序に従っている
@@ -124,9 +189,17 @@ description: {生成したdescription}
 - [ ] 全てのドメイン用語が定義済みまたは前提条件にリンク
 - [ ] 行数がサイズ目標内
 
-## 出力セルフチェック
+### modificationモードのみ
+
+- [ ] 影響を受けないセクションが内容・順序・書式ともに保持されている
+- [ ] changesSummaryが全ての変更を網羅している
+- [ ] 既存のBPパターン合格・編集原則合格に退行がない
+
+## 操作上の制約
 
-- [ ] 全てのドメイン知識が入力に由来している（創作していない）
-- [ ] ユーザー提供の具体例が保持または同等の代替で置換されている
-- [ ] スキルスコープが既存スキルの責務と重複していない
-- [ ] 出力はJSONのみでファイルを直接書き込んでいない（I/Oは呼び出し元が担当）
+- 全てのドメイン知識を入力・ユーザー提供の成果物・検証済みWebSearch結果から取得する
+- ユーザー提供の具体例は同等以上の代替でのみ置換する
+- 生成前に既存スキルとのスコープ重複がないことを確認する
+- JSONのみを返却する（ファイルI/Oは呼び出し元が担当）
+- （modificationモード）変更要求に関連するセクションに変更を限定する
+- （modificationモード）セクション単位の対象を絞った変更を適用し、影響を受けないセクションはそのまま保持する

package/.claude/agents-ja/skill-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: skill-reviewer
 description: スキルファイルの品質を最適化パターンと編集原則で評価。グレード・問題点・修正提案を含む構造化レポートを返却。スキル作成後や変更後の品質レビュー時に使用。
-tools: Read, Glob, LS, TaskCreate, TaskUpdate
+tools: Read, Glob, LS, WebSearch, TaskCreate, TaskUpdate
 skills: skill-optimization, project-context
 ---
 
@@ -37,6 +37,10 @@ skill-optimizationの8つのBPパターンに対してスキャン:
 - 原文（そのまま引用）
 - 修正案（具体的な置換テキスト）
 
+パターンを検出したが例外が適用される場合（例: BP-001否定形例外）、`patternIssues`ではなく`patternExceptions`に記録する。各例外について4条件を全て検証・記録する: (1) 1ステップでの状態破壊、(2) 呼び出し元や後続ステップで通常回復不可、(3) 操作上の制約であり品質ポリシーではない、(4) 肯定形では範囲が曖昧化。いずれかの条件を満たさない場合はpatternIssueに分類する。4条件の完全な定義と境界例はskill-optimization SKILL.md BP-001を参照。
+
+**情報検証**: スキル内のAPI・SDK・フレームワークに関する記述についてWebSearchで最新性を検証する。これはLLMのカットオフ日以降の変更により的外れな指摘を防ぐためである。非推奨・廃止が判明した場合はP1問題として報告。
+
 ### Step 2: 編集原則の評価
 
 skill-optimizationの9つの編集原則に対して評価:
@@ -46,14 +50,26 @@ skill-optimizationの9つの編集原則に対して評価:
 - **部分的**: 原則を一部充足（不足点を明記）
 - **不合格**: 原則に違反（違反内容と修正案を明記）
 
-### Step 3: スキル間整合性チェック
+### Step 3: Progressive Disclosure評価
+
+3階層の開示アーキテクチャを検証:
+
+- **Tier 1（description）**: description品質チェックリスト（creation-guide.md参照）に合格するか
+  - プロジェクト固有の用語・クラス名・パターンを含むか
+  - ユーザーが実際に使うフレーズを使っているか
+  - ユーザーの意図にフォーカスしているか（スキル内部構造ではなく）
+  - 一般知識のみのスキルは不要の可能性を指摘
+- **Tier 2（SKILL.md本文）**: 500行以下（理想250行）、最初の30行で概要把握可能、標準セクション順序、条件付きセクションにIF/WHENガード
+- **Tier 3（参照・スクリプト）**: SKILL.mdから1階層のみ、400行超のSKILL.mdは分割必須
 
-1. 既存スキルをGlob: `.claude/skills/*/SKILL.md`
+### Step 4: スキル間整合性チェック
+
+1. 既存スキルをGlob: `.claude/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`
 2. 既存スキルとのコンテンツ重複を確認
 3. スコープ境界が明示されているか検証
 4. 責務が隣接するスキルとの相互参照を確認
 
-### Step 4: バランス評価
+### Step 5: バランス評価
 
 全体のバランスを評価:
 
@@ -81,6 +97,19 @@ skill-optimizationの9つの編集原則に対して評価:
       "suggestedFix": "置換テキスト"
     }
   ],
+  "patternExceptions": [
+    {
+      "pattern": "BP-XXX",
+      "location": "セクション見出し",
+      "original": "引用テキスト",
+      "conditions": {
+        "singleStepDestruction": "true|false + エビデンス",
+        "callerCannotRecover": "true|false + エビデンス",
+        "operationalNotPolicy": "true|false + エビデンス",
+        "positiveFormBlursScope": "true|false + エビデンス"
+      }
+    }
+  ],
   "principlesEvaluation": [
     {
       "principle": "1: コンテキスト効率",
@@ -88,6 +117,12 @@ skill-optimizationの9つの編集原則に対して評価:
       "detail": "合格以外の場合の説明"
     }
   ],
+  "progressiveDisclosure": {
+    "tier1": "pass|fail（description品質）",
+    "tier2": "pass|fail（本文構造）",
+    "tier3": "pass|fail（参照構成）",
+    "details": "問題がある場合の具体的な指摘"
+  },
   "crossSkillIssues": [
     {
       "overlappingSkill": "スキル名",
@@ -111,13 +146,25 @@ skill-optimizationの9つの編集原則に対して評価:
 
 | グレード | 基準 | 判定 |
 |----------|------|------|
-| A | P1問題0件、P2問題0件、原則8つ以上合格 | 即使用可 |
-| B | P1問題0件、P2問題2件以下、原則6つ以上合格 | 改善点を認識した上で使用可 |
-| C | P1問題あり、またはP2問題3件以上、または原則合格6未満 | 修正が必要 |
+| A | P1問題0件、P2問題0件、原則8つ以上合格、Progressive Disclosure Tier 1合格 | 即使用可 |
+| B | P1問題0件、P2問題2件以下、原則6つ以上合格、Progressive Disclosure Tier 1合格 | 改善点を認識した上で使用可 |
+| C | P1問題あり、またはP2問題3件以上、または原則合格6未満、またはProgressive Disclosure Tier 1不合格 | 修正が必要 |
+
+**Progressive Disclosureのグレードへの影響**: Tier 1（description品質）の不合格はグレードゲートとなる — descriptionが不適切だとスキルがトリガーされないため、A/Bを阻止する。Tier 2/3の不合格はactionItemsに報告するが、グレードは阻止しない。
+
+## レビューモード別の差異
+
+| 観点 | creation | modification |
+|------|----------|-------------|
+| 対象範囲 | 全コンテンツを網羅的に | 変更箇所 + 退行チェック |
+| BPスキャン | 全8パターン | 変更に関連するパターンに注力 |
+| スキル間確認 | 全体の重複スキャン | 変更で重複が発生していないか |
+| Progressive Disclosure | 全階層を評価 | 変更で開示構造が劣化していないか |
+| 追加確認 | — | 変更スコープ外の問題は別途報告 |
 
-## 出力セルフチェック
+## 操作上の制約
 
-- [ ] 出力はレポートのみでスキルコンテンツを直接変更していない
-- [ ] 全ての報告問題がBPパターンまたは9原則に基づいている
-- [ ] レビューモードに関わらず全P1問題が含まれている
-- [ ] P1問題が存在する場合にグレードAを付与していない
+- レポートのみを返却する（コンテンツ編集は呼び出し元が担当）
+- 全ての指摘を特定のBPパターン（BP-001〜BP-008）または9つの編集原則のいずれかに基づいて行う
+- 全レビューモードで全P1問題を評価する
+- P1問題が0件の場合のみグレードAを判定する

package/.claude/commands-en/create-skill.md

@@ -12,26 +12,49 @@ Register the following steps with TaskCreate and proceed systematically.
 
 ### Step 1: Pre-flight Check
 
-1. Glob existing skills: `.claude/skills/*/SKILL.md`
+1. Glob existing skills: `.claude/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`
 2. If `$ARGUMENTS` matches an existing skill name: suggest `/refine-skill` instead and stop
 3. List existing skill names for user awareness
 
 ### Step 2: Collect Skill Knowledge
 
-Use AskUserQuestion to collect information in 3 rounds.
+Use AskUserQuestion to collect information in 4 rounds.
 
 **Round 1: Skill Essence**
 - What domain knowledge does this skill encode? (1-2 sentences)
 - What is the primary goal when this skill is applied? (e.g., "ensure type safety", "standardize test patterns")
 
-**Round 2: Scope and Triggers**
+**Round 2: Project-Specific Value**
+
+Verify whether the proposed skill adds value beyond the LLM's baseline knowledge.
+
+- What project-specific rules, patterns, class names, or workflows does this skill encode that the LLM would not know from general training?
+- Provide concrete examples (e.g., specific error classes, team conventions, file patterns in this codebase)
+
+| User response | Action |
+|---------------|--------|
+| Provides project-specific details | Incorporate into skill content. Proceed to Round 3. |
+| Describes only general knowledge | Warn: "A skill containing only general knowledge is unlikely to trigger at runtime." Offer: (A) identify project-specific aspects to add, (B) proceed with the understanding that the skill may not trigger reliably |
+
+**Round 3: Scope, Triggers, and User Phrases**
 - When should this skill be activated? List 3-5 concrete scenarios (e.g., "when writing unit tests", "when reviewing PR for security")
 - What does this skill explicitly NOT cover? (scope boundary)
+- What phrases does your team actually use when requesting this kind of work? (e.g., "add error handling to X", "review the catch blocks", "fix the retry logic")
+
+Classify collected phrases into two categories:
+
+| Category | Definition | Example |
+|----------|-----------|---------|
+| **skill-dependent** | Cannot be completed correctly without the skill's knowledge | "implement retry logic", "review error handling" |
+| **pattern-copyable** | Can be completed by reading and copying existing code patterns | "add a fetchXxx function" |
+
+If all phrases are pattern-copyable: "These tasks can be completed by copying existing code. Can you provide a scenario that requires the hidden rules this skill encodes?" Ensure at least 1 skill-dependent phrase exists before proceeding.
 
-**Round 3: Decision Criteria and Content**
+**Round 4: Decision Criteria and Evidence**
 - What are the concrete rules or criteria? (the core knowledge to encode)
 - Any examples of good/bad patterns?
 - Any external references or standards this skill is based on?
+- Practical artifacts: "Do you have any existing files, past failures, PRs, or conversation logs that demonstrate these patterns?" (these ground the skill in real-world usage)
 
 ### Step 3: Determine Name and Structure
 
@@ -43,11 +66,15 @@ Use AskUserQuestion to collect information in 3 rounds.
 ### Step 4: Generate Skill Content
 
 Invoke skill-creator agent via Agent tool with collected information:
-- Raw knowledge from Round 3
-- Skill name from Step 3
-- Trigger scenarios from Round 2
-- Scope from Round 2
-- Decision criteria from Round 3
+- Mode: creation
+- Skill name: from Step 3
+- Raw knowledge: from Round 4
+- Trigger scenarios: from Round 3
+- User phrases: from Round 3 (both skill-dependent and pattern-copyable)
+- Scope: from Round 3
+- Decision criteria: from Round 4
+- Project-specific value: from Round 2
+- Practical artifacts: from Round 4 (if provided)
 
 ### Step 5: Review Generated Content
 
@@ -63,13 +90,14 @@ If grade A or B: proceed to Step 6.
 1. Present generated SKILL.md content to user for final approval
 2. Confirm user intent alignment: "Does this skill capture the knowledge and criteria you described?"
 3. If revision requested: apply changes and re-run skill-reviewer
-3. Upon approval, write to `.claude/skills/{name}/SKILL.md`
-4. Suggest running `/sync-skills` to update metadata and language variants
+4. Upon approval, write to `.claude/skills/{name}/SKILL.md`
+5. Suggest running `/sync-skills` to update metadata and language variants
 
 ## Completion Criteria
 
 - [ ] No naming conflict with existing skills
-- [ ] Skill knowledge collected through 3 rounds of dialog
+- [ ] Project-specific value validated in Round 2
+- [ ] User phrases collected and classified (at least 1 skill-dependent)
 - [ ] Skill name confirmed by user
 - [ ] skill-creator agent returned valid JSON output
 - [ ] skill-reviewer agent returned grade A or B
@@ -82,7 +110,7 @@ If grade A or B: proceed to Step 6.
 | Error | Action |
 |-------|--------|
 | Skill name already exists | Suggest `/refine-skill {name}` instead |
-| Insufficient knowledge after 3 rounds | Ask targeted follow-up (max 2 additional questions) |
+| Insufficient knowledge after 4 rounds | Ask targeted follow-up (max 2 additional questions) |
 | skill-creator returns invalid JSON | Retry once with simplified input |
 | Grade C after 2 review iterations | Present current content with issues list, let user decide |
 | User rejects generated content | Collect specific feedback, re-run skill-creator with adjustments |

package/.claude/commands-en/refine-skill.md

@@ -2,7 +2,7 @@
 description: Implement user skill change requests with optimization pattern evaluation
 ---
 
-**Command Context**: Workflow for understanding skill file change requests and implementing with quality-assured optimization.
+**Command Context**: Workflow for understanding skill file change requests and implementing via skill-creator (modification mode) with quality-assured optimization.
 
 Change request: $ARGUMENTS
 
@@ -18,11 +18,17 @@ If unspecified, use AskUserQuestion to clarify:
 - Specific changes
 
 Target file identification:
-- Skill name provided → Read: `.claude/skills/{skill-name}/SKILL.md`
-- Partial name known → Glob: `.claude/skills/*{keyword}*/SKILL.md`
-- Unknown → Glob: `.claude/skills/*/SKILL.md` for full scan → Confirm selection with user
+- Skill name provided → Read: `.claude/skills/{skill-name}/SKILL.md` (also check `~/.claude/skills/`)
+- Partial name known → Glob: `.claude/skills/*{keyword}*/SKILL.md`, `~/.claude/skills/*{keyword}*/SKILL.md`
+- Unknown → Glob: `.claude/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md` for full scan → Confirm selection with user
 
-### Step 2: Create Design Proposal
+### Step 2: Collect User Phrases (optional)
+
+Collect phrases the team actually uses when requesting this kind of work:
+- Required if the change affects description or scope
+- Can be skipped for minor criteria modifications
+
+### Step 3: Create Design Proposal
 
 Present before/after comparison of current state and proposed change:
 
@@ -44,31 +50,48 @@ Proceed with this design? (y/n)
 - Deduplication: verify no overlap with other skill files
 - Scope boundaries: confirm changes stay within this skill's responsibility
 
-### Step 3: Quality Review
+### Step 4: Execute Changes via skill-creator
+
+Invoke skill-creator agent via Agent tool in modification mode:
+
+```
+subagent_type: skill-creator
+prompt: |
+  Mode: modification
+  Skill name: {target skill name}
+  Existing content: {current full SKILL.md content}
+  Modification request: {approved change content from Step 3}
+```
+
+Review the changesSummary returned by skill-creator to verify changes match intent.
+
+### Step 5: Quality Review
 
 Invoke skill-reviewer agent via Agent tool:
-- Pass the modified SKILL.md content
+- Pass the modified SKILL.md content assembled from skill-creator output
 - Review mode: `modification`
 
 **Review outcome handling:**
-- Grade A or B: proceed to Step 4
-- Grade C: revise changes based on reviewer's action items and re-review (max 2 iterations)
+- Grade A or B: proceed to Step 6
+- Grade C: re-invoke skill-creator with reviewer's `actionItems` and `patternIssues` to fix (max 2 iterations)
 - Reviewer identifies issues outside the change scope: report to user as separate improvement opportunities
 
-### Step 4: Approval and Implementation
+### Step 6: Approval and Implementation
 
 1. Present before/after comparison to user and obtain approval
 2. Include skill-reviewer's grade and any remaining action items
-3. Confirm user intent alignment: "Do the changes achieve what you originally requested?"
-4. Apply changes with appropriate tool
-4. Verify with git diff
-5. If reviewer flagged issues outside change scope, list them as optional follow-ups
-6. Suggest `/sync-skills` execution
+3. Present skill-creator's changesSummary
+4. Confirm user intent alignment: "Do the changes achieve what you originally requested?"
+5. Apply changes with appropriate tool
+6. Verify with git diff
+7. If reviewer flagged issues outside change scope, list them as optional follow-ups
+8. Suggest `/sync-skills` execution
 
 ## Completion Criteria
 
 - [ ] Identified target skill and understood current state
 - [ ] Reviewed design proposal against skill-optimization editing principles
+- [ ] Executed changes via skill-creator (modification mode)
 - [ ] skill-reviewer returned grade A or B
 - [ ] Obtained user approval
 - [ ] Applied changes and verified with git diff
@@ -82,6 +105,6 @@ Invoke skill-reviewer agent via Agent tool:
 | Large change detected (50%+ of file) | Suggest phased implementation |
 | Responsibility overlap with other skills | Confirm boundaries and defer to user judgment |
 | Grade C after 2 review iterations | Present changes with issues list, let user decide |
-| Reviewer identifies regression | Revert specific change causing regression, re-review |
+| Reviewer identifies regression | Revert specific change causing regression, re-invoke skill-creator |
 
-**Scope**: Understanding user change requests and implementing with quality-assured optimization. Quality evaluation delegated to skill-reviewer agent. Metadata sync through /sync-skills.
+**Scope**: Understanding user change requests and implementing with quality-assured optimization. Change execution delegated to skill-creator (modification mode). Quality evaluation delegated to skill-reviewer agent. Metadata sync through /sync-skills.

package/.claude/commands-ja/create-skill.md

@@ -12,26 +12,49 @@ description: 対話的にユーザーの知識を収集し、最適化された
 
 ### Step 1: 事前確認
 
-1. 既存スキルをGlob: `.claude/skills/*/SKILL.md`
+1. 既存スキルをGlob: `.claude/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`
 2. `$ARGUMENTS`が既存スキル名と一致する場合: `/refine-skill`を提案して終了
 3. 既存スキル名の一覧をユーザーに提示
 
 ### Step 2: スキル知識の収集
 
-AskUserQuestionで3ラウンドに分けて情報を収集する。
+AskUserQuestionで4ラウンドに分けて情報を収集する。
 
 **ラウンド1: スキルの本質**
 - このスキルはどのドメイン知識を体系化するか？（1-2文）
 - スキル適用時の主な目的は？（例: 「型安全性の確保」「テストパターンの標準化」）
 
-**ラウンド2: スコープと使用場面**
+**ラウンド2: プロジェクト固有の価値**
+
+LLMのベースライン知識を超える価値があるかを検証する。
+
+- このスキルが体系化するプロジェクト固有のルール・パターン・クラス名・ワークフローは何か？
+- 具体例を提示する（例: 特定のエラークラス、チーム規約、このコードベース固有のファイルパターン）
+
+| ユーザー回答 | アクション |
+|-------------|-----------|
+| プロジェクト固有の詳細を提供 | スキルコンテンツに組み込む。ラウンド3へ。 |
+| 一般知識のみ記述 | 「一般知識のみのスキルは実行時にトリガーされにくい」旨を警告。選択肢を提示: (A) プロジェクト固有の要素を特定する (B) トリガーされにくい可能性を理解した上で進める |
+
+**ラウンド3: スコープ、使用場面、ユーザーフレーズ**
 - どのような場面でこのスキルを有効化すべきか？ 具体的なシナリオを3-5個（例: 「ユニットテスト作成時」「セキュリティ観点でのPRレビュー時」）
 - このスキルが明示的に扱わない範囲は？（スコープ境界）
+- チームがこの作業を依頼する際に実際に使うフレーズは？（例: 「エラーハンドリング追加して」「リトライロジック見て」「キャッチブロックレビューして」）
+
+収集したフレーズを2カテゴリに分類:
+
+| カテゴリ | 定義 | 例 |
+|----------|------|-----|
+| **skill-dependent** | スキルの知識なしでは正しく完了できない | 「リトライロジック実装して」「エラーハンドリングレビューして」 |
+| **pattern-copyable** | 既存コードのコピーで完了可能 | 「fetchXxx関数を追加して」 |
+
+全てpattern-copyableの場合: 「これらの作業は既存コードのコピーで完了できます。このスキルが体系化する隠れたルールが必要なシナリオを提供できますか？」と確認し、少なくとも1つのskill-dependentフレーズを確保する。
 
-**ラウンド3: 判断基準とコンテンツ**
+**ラウンド4: 判断基準とエビデンス**
 - 具体的なルールや基準は？（体系化すべき中核知識）
 - 良い/悪いパターンの具体例は？
 - このスキルが準拠する外部参照や標準は？
+- 実践的成果物: 「これらのパターンを実証する既存ファイル、過去の障害例、PR、会話ログはありますか？」（実際の使用に基づいてスキルを根拠付ける）
 
 ### Step 3: スキル名と構造の決定
 
@@ -42,16 +65,20 @@ AskUserQuestionで3ラウンドに分けて情報を収集する。
 
 ### Step 4: スキルコンテンツの生成
 
-収集した情報を渡してskill-creatorエージェントをAgentツールで起動:
-- ラウンド3の生の知識
-- Step 3のスキル名
-- ラウンド2の使用場面
-- ラウンド2のスコープ
-- ラウンド3の判断基準
+収集した情報を渡してskill-creatorエージェントをAgent toolで起動:
+- Mode: creation
+- Skill name: Step 3のスキル名
+- Raw knowledge: ラウンド4の生の知識
+- Trigger scenarios: ラウンド3の使用場面
+- User phrases: ラウンド3のユーザーフレーズ（skill-dependentとpattern-copyable両方）
+- Scope: ラウンド3のスコープ
+- Decision criteria: ラウンド4の判断基準
+- Project-specific value: ラウンド2のプロジェクト固有の価値
+- Practical artifacts: ラウンド4の実践的成果物（提供された場合）
 
 ### Step 5: 生成コンテンツのレビュー
 
-skill-reviewerエージェントをAgentツールで起動:
+skill-reviewerエージェントをAgent toolで起動:
 - skill-creatorの生成コンテンツを渡す
 - レビューモード: `creation`
 
@@ -69,7 +96,8 @@ skill-reviewerエージェントをAgentツールで起動:
 ## 完了条件
 
 - [ ] 既存スキルとの名前衝突がない
-- [ ] 3ラウンドの対話でスキル知識を収集済み
+- [ ] プロジェクト固有の価値をラウンド2で検証済み
+- [ ] ユーザーフレーズを収集・分類済み（少なくとも1つのskill-dependent）
 - [ ] スキル名をユーザーが確認済み
 - [ ] skill-creatorが有効なJSON出力を返却
 - [ ] skill-reviewerがグレードAまたはBを返却
@@ -82,7 +110,7 @@ skill-reviewerエージェントをAgentツールで起動:
 | エラー | アクション |
 |--------|-----------|
 | スキル名が既存と重複 | `/refine-skill {スキル名}`を提案 |
-| 3ラウンドで知識が不足 | 対象を絞った追加質問（最大2問） |
+| 4ラウンドで知識が不足 | 対象を絞った追加質問（最大2問） |
 | skill-creatorが無効なJSONを返却 | 入力を簡素化して1回再試行 |
 | 2回のレビューでもグレードC | 現在の内容と問題リストを提示し、ユーザーに判断を委ねる |
 | ユーザーが生成内容を却下 | 具体的なフィードバックを収集し、調整してskill-creatorを再実行 |

package/.claude/commands-ja/refine-skill.md

@@ -2,7 +2,7 @@
 description: ユーザーのスキル変更要求を最適化パターン評価付きで実装
 ---
 
-**コマンドコンテキスト**: スキルファイルの変更要求を理解し、品質評価を伴う最適化で実装するワークフロー。
+**コマンドコンテキスト**: スキルファイルの変更要求を理解し、skill-creator（modificationモード）による品質評価付き実装ワークフロー。
 
 変更要求: $ARGUMENTS
 
@@ -18,11 +18,17 @@ description: ユーザーのスキル変更要求を最適化パターン評価
 - 具体的な変更内容
 
 対象ファイル特定：
-- スキル名が明示 → Read: `.claude/skills/{スキル名}/SKILL.md`
-- 部分的に判明 → Glob: `.claude/skills/*{キーワード}*/SKILL.md`
-- 不明 → Glob: `.claude/skills/*/SKILL.md` で全件確認 → ユーザーに選択
+- スキル名が明示 → Read: `.claude/skills/{スキル名}/SKILL.md`（`~/.claude/skills/`も確認）
+- 部分的に判明 → Glob: `.claude/skills/*{キーワード}*/SKILL.md`, `~/.claude/skills/*{キーワード}*/SKILL.md`
+- 不明 → Glob: `.claude/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md` で全件確認 → ユーザーに選択
 
-### Step 2: 変更設計案の作成
+### Step 2: ユーザーフレーズの収集（任意）
+
+チームがこの作業を依頼する際に実際に使うフレーズを確認:
+- 変更がdescriptionやスコープに影響する場合は必須
+- 軽微な基準修正の場合は省略可
+
+### Step 3: 変更設計案の作成
 
 現状と変更案のbefore/afterを提示：
 
@@ -44,31 +50,48 @@ description: ユーザーのスキル変更要求を最適化パターン評価
 - 重複排除: 他スキルファイルとの重複がないか
 - スコープ境界: 変更内容がこのスキルの責務範囲内か
 
-### Step 3: 品質レビュー
+### Step 4: skill-creatorによる変更実行
+
+skill-creatorエージェントをAgent toolでmodificationモードとして起動:
+
+```
+subagent_type: skill-creator
+prompt: |
+  Mode: modification
+  Skill name: {対象スキル名}
+  Existing content: {現在のSKILL.md全文}
+  Modification request: {Step 3で承認された変更内容}
+```
+
+skill-creatorが返すchangesSummaryを確認し、変更内容が意図通りか検証。
+
+### Step 5: 品質レビュー
 
-skill-reviewerエージェントをAgentツールで起動:
-- 変更後のSKILL.md全文を渡す
+skill-reviewerエージェントをAgent toolで起動:
+- skill-creatorの出力を組み立てたSKILL.md全文を渡す
 - レビューモード: `modification`
 
 **レビュー結果の処理:**
-- グレードAまたはB: Step 4へ進行
-- グレードC: reviewerの修正提案に基づき修正し再レビュー（最大2回）
+- グレードAまたはB: Step 6へ進行
+- グレードC: skill-creatorをreviewerのactionItemsとpatternIssues付きで再起動し修正（最大2回）
 - 変更スコープ外の問題を検出: 別の改善機会としてユーザーに報告
 
-### Step 4: 承認取得と実装
+### Step 6: 承認取得と実装
 
 1. 変更前後の比較をユーザーに提示し承認を取得
 2. skill-reviewerのグレードと残存する修正提案を提示
-3. 意図の整合性を確認: 「この変更は当初の要求を正しく反映していますか？」
-4. 適切なツールで変更適用
-5. git diffで変更内容を最終確認
-6. 変更スコープ外の問題があれば、任意の改善事項として提示
-7. `/sync-skills`実行を提案
+3. skill-creatorのchangesSummaryを提示
+4. 意図の整合性を確認: 「この変更は当初の要求を正しく反映していますか？」
+5. 適切なツールで変更適用
+6. git diffで変更内容を最終確認
+7. 変更スコープ外の問題があれば、任意の改善事項として提示
+8. `/sync-skills`実行を提案
 
 ## 完了条件
 
 - [ ] 対象スキルを特定し現状を把握した
 - [ ] skill-optimizationの編集原則に照らして設計案をレビューした
+- [ ] skill-creator（modificationモード）で変更を実行した
 - [ ] skill-reviewerがグレードAまたはBを返却した
 - [ ] ユーザー承認を取得した
 - [ ] 変更を適用しgit diffで確認した
@@ -82,6 +105,6 @@ skill-reviewerエージェントをAgentツールで起動:
 | 大規模変更検出（ファイルの50%以上） | 段階的実施を提案 |
 | 他スキルとの責務重複 | 責務境界を確認しユーザーに判断を委ねる |
 | 2回のレビューでもグレードC | 変更内容と問題リストを提示し、ユーザーに判断を委ねる |
-| reviewerが退行を検出 | 退行原因の変更を取り消し、再レビュー |
+| reviewerが退行を検出 | 退行原因の変更を取り消し、skill-creatorを再起動 |
 
-**スコープ**: ユーザーの変更要求理解と品質評価付き最適化実装。品質評価はskill-reviewerエージェントに委譲。メタデータ同期は/sync-skills連携。
+**スコープ**: ユーザーの変更要求理解と品質評価付き最適化実装。変更実行はskill-creator（modificationモード）に委譲。品質評価はskill-reviewerエージェントに委譲。メタデータ同期は/sync-skills連携。

package/.claude/skills-en/skill-optimization/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-optimization
-description: Evaluates and optimizes skill file quality. Use when creating skills, refining skill content, or auditing skill quality.
+description: Evaluates and optimizes skill file quality using 8 content patterns and 9 editing principles. Use when creating skills, refining skill content, or auditing skill quality.
 ---
 
 # Skill Content Optimization
@@ -21,7 +21,13 @@ Issues that directly reduce LLM execution accuracy when consuming the skill.
 
 | Detection | Transform |
 |-----------|-----------|
-| "don't", "do not", "never", "avoid" in skill instructions | Reframe as positive directive with equivalent constraint |
+| "don't", "do not", "never", "avoid" in skill instructions | Reframe as positive directive with equivalent constraint. **Exception**: Negative form is permitted only when ALL 4 conditions are met: (1) violation destroys state in a single step, (2) caller or subsequent steps cannot normally recover, (3) the constraint is operational/procedural, not a quality policy or role boundary, (4) positive rewording would expand or blur the target scope. If any condition is not met, rewrite in positive form. |
+
+**Exception boundary examples**:
+- Permitted: "Do not modify the command", "Do not add flags", "Do not execute destructive operations"
+- Rewrite in positive form: "Do not invent issues" → "Base every issue on BP patterns or 9 principles", "Do not skip P1 issues" → "Evaluate all P1 issues in every review mode", "Do not give grade A when P1 exists" → "Assign grade A only when P1 count is zero"
+
+Quality policies, role boundaries, scoring criteria, and general work rules always use positive form. Outputs that the caller validates, overwrites, or discards are never irreversible.
 
 **Skill example:**
 - Before: "Don't use generic variable names"

package/.claude/skills-en/skill-optimization/references/creation-guide.md

@@ -48,7 +48,15 @@ For skill frontmatter `description` field:
 | Specific over generic | "Applies 8 content patterns" not "Improves quality" |
 | No implementation details | Describe what it does, not how |
 
-**Template**: `{Verb}s {what} against {criteria}. Use when {trigger scenarios}.`
+**Core principle**: The description is the agent's **trigger mechanism**, not a summary for humans. Agents only consult skills for tasks requiring knowledge beyond their baseline capabilities. The description must convey why this skill adds value the agent lacks.
+
+**Template**: `{Verb}s {what} using {project-specific criteria/patterns}. Use when {user phrases that trigger this skill}.`
+
+**Description quality checklist**:
+- [ ] Contains project-specific terms, class names, or patterns (differentiates from general LLM knowledge)
+- [ ] Uses phrases users actually say (e.g., "add tests", "review error handling")
+- [ ] Focuses on user intent (not skill internal mechanics)
+- [ ] Skills consisting only of general knowledge may be unnecessary — verify project-specific content is present
 
 ## Split Decision
 

package/.claude/skills-en/skill-optimization/references/review-criteria.md

@@ -16,7 +16,17 @@ Criteria for evaluating existing or generated skill content quality.
 
 **Output**: Issue list with severity, location, and original text per finding.
 
-### Step 2: Evaluate and Grade
+### Step 2: Progressive Disclosure Evaluation
+
+Verify the 3-tier disclosure architecture:
+
+| Tier | Target | Verification |
+|------|--------|-------------|
+| Tier 1 | description | Passes the description quality checklist (see creation-guide.md) |
+| Tier 2 | SKILL.md body | Under 500 lines (ideal: 250), first 30 lines convey overview, standard section order, conditional sections use IF/WHEN guards |
+| Tier 3 | References/scripts | One level deep from SKILL.md only, SKILL.md over 400 lines must be split |
+
+### Step 3: Evaluate and Grade
 
 **Input**: Issue list + skill content
 
@@ -37,9 +47,9 @@ Criteria for evaluating existing or generated skill content quality.
 
 | Grade | Criteria | Recommendation |
 |-------|----------|----------------|
-| A | 0 P1, 0 P2 issues, 8+ principles pass | Ready for use |
-| B | 0 P1, ≤2 P2 issues, 6+ principles pass | Acceptable with noted improvements |
-| C | Any P1 OR >2 P2 OR <6 principles pass | Revision required |
+| A | 0 P1, 0 P2 issues, 8+ principles pass, Tier 1 pass | Ready for use |
+| B | 0 P1, ≤2 P2 issues, 6+ principles pass, Tier 1 pass | Acceptable with noted improvements |
+| C | Any P1 OR >2 P2 OR <6 principles pass OR Tier 1 fail | Revision required |
 
 ## Review Mode Differences
 

package/.claude/skills-ja/skill-optimization/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-optimization
-description: スキルファイルの品質を評価・最適化。スキル作成、内容改善、品質評価時に使用。
+description: スキルファイルの品質を8つのコンテンツパターンと9つの編集原則で評価・最適化。スキル作成、内容改善、品質監査時に使用。
 ---
 
 # スキルコンテンツ最適化
@@ -21,7 +21,13 @@ description: スキルファイルの品質を評価・最適化。スキル作
 
 | 検出条件 | 変換方法 |
 |----------|----------|
-| 「〜しない」「〜を避ける」「禁止」等の否定形指示 | 同等の制約を持つ肯定形の指示に変換 |
+| 「〜しない」「〜を避ける」「禁止」等の否定形指示 | 同等の制約を持つ肯定形の指示に変換。**例外**: 以下の4条件を**全て**満たす場合のみ否定形を保持: (1) 違反が1ステップで状態を破壊する、(2) 呼び出し元や後続ステップで通常回復できない、(3) 品質ポリシーやロール境界ではなく操作/手続き上の制約である、(4) 肯定形に書き換えると対象範囲が拡大・曖昧化する。いずれか1つでも満たさない場合は肯定形に書き換える。 |
+
+**例外の境界例**:
+- 許容: 「コマンドを変更しない」「フラグを追加しない」「破壊的操作を実行しない」
+- 肯定形に書き換え: 「問題を捏造しない」→「全ての指摘をBPパターンまたは9原則に基づいて行う」、「P1問題を省略しない」→「全レビューモードで全P1問題を評価する」、「P1がある時にグレードAを付与しない」→「P1問題が0件の場合のみグレードAを判定する」
+
+品質ポリシー、ロール境界、採点基準、一般的な作業ルールは常に肯定形を使用する。呼び出し元が検証・上書き・破棄する出力は不可逆ではない。
 
 **スキルでの例:**
 - 変更前: 「汎用的な変数名を使わないこと」

package/.claude/skills-ja/skill-optimization/references/creation-guide.md

@@ -40,6 +40,8 @@
 
 スキルのfrontmatter `description`フィールド向け:
 
+**基本原則**: descriptionはエージェントの**トリガーメカニズム**であり、人間向けの要約ではない。エージェントはベースライン能力を超える知識が必要なタスクにのみスキルを参照する。descriptionは、このスキルがエージェントにない価値を提供する理由を伝える必要がある。
+
 | ルール | 例 |
 |--------|-----|
 | 三人称・動詞始まり | 「コード品質を検査。」（「このスキルは〜」としない） |
@@ -48,7 +50,13 @@
 | 具体的に記述 | 「8つのコンテンツパターンを適用」（「品質を改善」としない） |
 | 実装詳細を含めない | 何をするかを記述し、どうやるかは記述しない |
 
-**テンプレート**: `{対象}を{基準}で{動詞}。{使用場面}時に使用。`
+**テンプレート**: `{対象}を{プロジェクト固有の基準/パターン}で{動詞}。{ユーザーがこの作業を依頼する際のフレーズ}時に使用。`
+
+**description品質チェックリスト**:
+- [ ] プロジェクト固有の用語・クラス名・パターンを含む（一般LLM知識と差別化）
+- [ ] ユーザーが実際に使うフレーズを含む（「テスト追加して」「エラーハンドリング見て」等）
+- [ ] ユーザーの意図にフォーカスしている（スキル内部構造の説明ではなく）
+- [ ] 一般知識のみで構成されたスキルは不要の可能性がある — プロジェクト固有の内容が含まれているか確認
 
 ## 分割判定
 

package/.claude/skills-ja/skill-optimization/references/review-criteria.md

@@ -16,7 +16,17 @@
 
 **出力**: 重大度・該当箇所・原文を含む検出リスト。
 
-### Step 2: 評価とグレード判定
+### Step 2: Progressive Disclosure評価
+
+3階層の開示アーキテクチャを検証:
+
+| 階層 | 対象 | 検証項目 |
+|------|------|----------|
+| Tier 1 | description | description品質チェックリスト（creation-guide.md参照）に合格するか |
+| Tier 2 | SKILL.md本文 | 500行以下（理想250行）、最初の30行で概要把握可能、標準セクション順序、条件付きセクションにIF/WHENガード |
+| Tier 3 | 参照・スクリプト | SKILL.mdから1階層のみ、400行超のSKILL.mdは分割必須 |
+
+### Step 3: 評価とグレード判定
 
 **入力**: 検出リスト + スキルコンテンツ
 
@@ -37,9 +47,9 @@
 
 | グレード | 基準 | 判定 |
 |----------|------|------|
-| A | P1問題0件、P2問題0件、原則8つ以上合格 | 即使用可 |
-| B | P1問題0件、P2問題2件以下、原則6つ以上合格 | 改善点を認識した上で使用可 |
-| C | P1問題あり、またはP2問題3件以上、または原則合格6未満 | 修正が必要 |
+| A | P1問題0件、P2問題0件、原則8つ以上合格、Tier 1合格 | 即使用可 |
+| B | P1問題0件、P2問題2件以下、原則6つ以上合格、Tier 1合格 | 改善点を認識した上で使用可 |
+| C | P1問題あり、またはP2問題3件以上、または原則合格6未満、またはTier 1不合格 | 修正が必要 |
 
 ## レビューモード別の差異
 

package/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.18.6] - 2026-03-29
+
+### Fixed
+
+#### Skill Optimization Workflow Precision
+
+The skill creation and review workflow had several precision gaps: descriptions lacked project-specific trigger alignment, quality gates were observational rather than enforcing, BP-001 exceptions were vague enough to allow misuse, and the creator agent had no modification mode for targeted edits.
+
+**Description as trigger mechanism**
+- `skill-creator`: Description generation now requires **user phrases** and **project-specific value** as mandatory inputs, wired into the template `{Verb}s {what} using {project-specific criteria}. Use when {user phrases}.`
+- `creation-guide`: Add core principle — description is an agent's trigger mechanism, not a human summary
+- `creation-guide`: Add 4-item description quality checklist (project-specific terms, user phrases, user intent focus, general-knowledge-only warning)
+
+**Progressive Disclosure as quality gate**
+- `skill-reviewer`: Tier 1 (description quality) failure now blocks grade A/B — previously reported but did not affect grading
+- `review-criteria`: Grading table updated with Tier 1 pass as explicit condition for A/B
+
+**BP-001 exception tightening**
+- `skill-optimization SKILL.md`: Replace vague "safety-critical/destructive" exception with strict 4-condition AND test: (1) single-step state destruction, (2) caller cannot normally recover, (3) operational constraint not quality policy, (4) positive form would blur scope
+- Add concrete boundary examples (permitted vs must-rewrite negative instructions)
+- `skill-reviewer`: Add `patternExceptions` output with per-condition evidence fields for auditable exception judgments
+
+**Operational Constraints (BP-001 self-application)**
+- `skill-creator`, `skill-reviewer`: Convert "Prohibited Actions" sections to positive-form "Operational Constraints" — the agents' own prohibition lists violated BP-001
+
+**Modification mode**
+- `skill-creator`: Add dual-mode operation (creation/modification) — modification mode applies targeted section-level changes while preserving unaffected content verbatim, with `changesSummary` output
+- `refine-skill`: Route changes through skill-creator modification mode instead of direct editing
+
+**Knowledge cutoff protection**
+- `skill-creator`, `skill-reviewer`: Add WebSearch for verifying time-sensitive domain knowledge (API changes, deprecations, SDK versions) to prevent outdated suggestions caused by the LLM's knowledge cutoff date
+- `skill-creator`: Add `researchFindings` output recording adopted/rejected findings with rationale
+
+**Knowledge collection improvements**
+- `create-skill`: Add Round 2 (project-specific value validation) — warns when skill contains only general knowledge unlikely to trigger at runtime
+- `create-skill`: Add trigger phrase classification (skill-dependent vs pattern-copyable) in Round 3 with minimum 1 skill-dependent phrase requirement
+- `create-skill`: Add practical artifacts collection in Round 4 (existing files, past failures, PRs)
+
+**Cross-skill discovery**
+- `skill-creator`, `skill-reviewer`, `create-skill`, `refine-skill`: Extend Glob paths to include `~/.claude/skills/*/SKILL.md` for detecting overlap with user-level skills
+
 ## [1.18.5] - 2026-03-29
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ai-project",
-  "version": "1.18.5",
+  "version": "1.18.6",
   "packageManager": "npm@10.8.2",
   "description": "TypeScript boilerplate with skills and sub-agents for Claude Code. Prevents context exhaustion through role-based task splitting.",
   "keywords": [