claude-dev-env 1.15.0 → 1.16.1

package/skills/prompt-generator/SKILL.md

@@ -53,7 +53,7 @@ Match `TARGET_OUTPUT.md`. Summary:
 4. **Full audit table / JSON debug object:** Append only after the user uses an explicit debug phrase such as `show debug`, `full audit table`, or `raw internal object`.
 5. **Commit-and-execute:** Pick a drafting approach, run it to completion, ship the XML; change plans only when **new** facts from the user or tools contradict the earlier scope.
 
-**Required XML sections** inside the fence: `<role>`, `<context>`, `<instructions>`, `<constraints>`, `<output_format>`. Optional: `<examples>`, `<open_question>` (use for unresolved discovery — see structural invariant D in `TARGET_OUTPUT.md`).
+**Required XML sections** inside the fence: `<role>`, `<background>`, `<instructions>`, `<constraints>`, `<output_format>`. Optional: `<illustrations>`, `<open_question>` (use for unresolved discovery — see structural invariant D in `TARGET_OUTPUT.md`).
 
 ## Scenario router
 
@@ -64,14 +64,14 @@ Match `TARGET_OUTPUT.md`. Summary:
 | **3 — Long unstructured input** | Many requirements / paths in one message | Verify repo references (packages, shared utils, configs) with targeted tools **before** questions | First question **confirms extracted intent**; ambiguities as **specific** options; **every** user-stated requirement captured in the generated XML by name — track all requirements from the unstructured input and confirm coverage before shipping |
 | **4 — Noisy context** | Long unrelated thread before `/prompt-generator` | Build the subagent brief from: the user’s literal `/prompt-generator` text, a **≤120-word** summary of on-topic facts, and discovery notes—**exclude** raw stack traces and unrelated tangents | As needed (often Scenario 1-shaped) |
 
-**Handoff (Scenario 2):** `<context>` must be **self-contained** — state, **decisions**, files touched, next steps, constraints — so a new session needs no prior chat. Preserve prior decisions verbatim in the handoff; quote the exact decision text where precision matters rather than paraphrasing it away.
+**Handoff (Scenario 2):** `<background>` must be **self-contained** — state, **decisions**, files touched, next steps, constraints — so a new session needs no prior chat. Preserve prior decisions verbatim in the handoff; quote the exact decision text where precision matters rather than paraphrasing it away.
 
 ## Phase ordering (structural invariant A)
 
 For the **final** user-visible turn that ships the artifact:
 
 - Compose the message as **audit line → opening fence → XML → closing fence → end**; keep the byte stream free of `tool_use` blocks **between** the opening and closing fences.
-- **Completeness:** End every numbered step inside `<instructions>` with a complete sentence and a fully written list item. Balance every XML tag explicitly (open and close each `<role>`, `<context>`, `<instructions>`, `<constraints>`, `<output_format>`). The artifact must be copy-pasteable into a new file with zero manual repair.
+- **Completeness:** End every numbered step inside `<instructions>` with a complete sentence and a fully written list item. Balance every XML tag explicitly (open and close each `<role>`, `<background>`, `<instructions>`, `<constraints>`, `<output_format>`). The artifact must be copy-pasteable into a new file with zero manual repair.
 - Global pipeline: **discovery tools** (when applicable) → **AskUserQuestion** → **subagent** (draft + refinement + internal audit) → **one** orchestrator reply containing only audit line + fence.
 
 ## Interactive discovery mode (default)
@@ -116,7 +116,7 @@ Match specificity to task fragility:
 
 ### 3. Collect required missing facts
 
-If AskUserQuestion did not cover something essential, the drafting agent either (a) inserts `<open_question>` in `<context>` with the missing fact spelled out, or (b) signals the orchestrator to run **another** AskUserQuestion round **before** emitting the fence—avoid free-form clarification paragraphs in the orchestrator chat.
+If AskUserQuestion did not cover something essential, the drafting agent either (a) inserts `<open_question>` in `<background>` with the missing fact spelled out, or (b) signals the orchestrator to run **another** AskUserQuestion round **before** emitting the fence—avoid free-form clarification paragraphs in the orchestrator chat.
 
 ### 3A. Anchor scope to concrete artifacts (required)
 
@@ -132,15 +132,15 @@ Use this scope block as the grounding contract for all generated instructions. E
 
 ### 4. Build the prompt
 
-Apply principles from Anthropic’s prompting guide (see REFERENCE.md): XML sections, role, motivation in `<context>`, positive framing, emotion-informed collaborative tone where appropriate, **commit-and-execute** for multi-step agent prompts.
+Apply principles from Anthropic’s prompting guide (see REFERENCE.md): XML sections, role, motivation in `<background>`, positive framing, emotion-informed collaborative tone where appropriate, **commit-and-execute** for multi-step agent prompts.
 
 **Structural invariant D:** Write `<instructions>` / `<constraints>` as direct imperatives (“Open `path/to/file.ts` and …”). Park unresolved items in `<open_question>` tags—one distinct question per tag with the exact decision you need. Inside the fenced XML artifact, use only confident, definitive language: replace hedging phrases (“let me also check”, “actually”, “one more consideration”) and tentative qualifiers (“might be”, “possibly”, “I think”, “could be”) with direct assertions or move genuine uncertainty into `<open_question>` tags.
 
 **Set a role** in the system prompt. Anthropic: "Setting a role in the system prompt focuses Claude's behavior and tone for your use case. Even a single sentence makes a difference."
 
-**Add motivation behind constraints** in `<context>`. Anthropic: "Providing context or motivation behind your instructions... can help Claude better understand your goals and deliver more targeted responses." Claude generalizes from the explanation.
+**Add motivation behind constraints** in `<background>`. Anthropic: "Providing context or motivation behind your instructions... can help Claude better understand your goals and deliver more targeted responses." Claude generalizes from the explanation.
 
-**Frame positively (zero-negative-keyword rule).** Anthropic: state the desired outcome directly. "Your response should be composed of smoothly flowing prose paragraphs" provides clearer guidance than a prohibition-only instruction. Apply this rule absolutely inside the fenced XML artifact across all sections (`<role>`, `<context>`, `<instructions>`, `<constraints>`, `<output_format>`): every instruction states what to do, what to produce, what to enforce. Use affirmative directives exclusively: "only X", "always X", "ensure X", "require X." Banned keywords inside generated XML: "no", "not", "don't", "do not", "never", "avoid", "without", "refrain", "stop", "prevent", "exclude", "prohibit", "forbid", "reject", "cannot", "unless." Also banned: indirect negative patterns such as "instead of X", "rather than X", "as opposed to." Example pass: "Ensure all functions have explicit return types." Example fail: "Do not leave return types implicit." When a boundary is needed, phrase it as what is permitted: "only run commands within the scoped paths" rather than a prohibition.
+**Frame positively (zero-negative-keyword rule).** Anthropic: state the desired outcome directly. "Your response should be composed of smoothly flowing prose paragraphs" provides clearer guidance than a prohibition-only instruction. Apply this rule absolutely inside the fenced XML artifact across all sections (`<role>`, `<background>`, `<instructions>`, `<constraints>`, `<output_format>`): every instruction states what to do, what to produce, what to enforce. Use affirmative directives exclusively: "only X", "always X", "ensure X", "require X." Banned keywords inside generated XML: "no", "not", "don't", "do not", "never", "avoid", "without", "refrain", "stop", "prevent", "exclude", "prohibit", "forbid", "reject", "cannot", "unless." Also banned: indirect negative patterns such as "instead of X", "rather than X", "as opposed to." Example pass: "Ensure all functions have explicit return types." Example fail: "Do not leave return types implicit." When a boundary is needed, phrase it as what is permitted: "only run commands within the scoped paths" rather than a prohibition.
 
 **Emotion-informed framing.** Anthropic's emotion concepts research (2026) shows that internal activation patterns causally influence output quality. Apply: explicit success criteria with "say so if you're unsure" as an accepted answer; collaborative language ("help figure out", "work on this together"); framing tasks as interesting problems rather than chores; constructive, forward-looking tone. Cross-model caveat: studied on Sonnet 4.5; the patterns align with Anthropic's prompting best practices independently. Full pattern catalog and citations: `packages/claude-dev-env/docs/emotion-informed-prompt-design.md`.
 
@@ -164,9 +164,18 @@ State desired outcomes explicitly; use XML inside the generated prompt when mixi
 
 Tune verbosity in the **generated** prompt: summaries after tool use vs direct answers — as appropriate to the user’s AskUserQuestion answers.
 
-### 7. Add examples
+### 7. Add illustrations (`<illustrations>`)
 
-For format- or tone-sensitive **generated** prompts, include 3–5 `<example>` blocks where helpful.
+Use the optional `<illustrations>` section when concrete samples make format, tone, or structure obvious to the downstream reader.
+
+**Code and command samples inside `<illustrations>` (drafting subagent — follow in order):**
+
+1. **Indented block (default for chat-stable rendering):** Put each line of sample shell, Python, JSON, or config text at **four spaces** of indentation from the left margin of the XML text so the sample reads as a single monospaced block inside `<illustrations>` using **only** leading spaces on each sample line (plain text inside the XML).
+2. **Tilde fence:** When the sample needs explicit fence delimiters, use a **tilde** fence only: an opening line `~~~` plus an optional info word (e.g. `~~~bash`), the sample lines, then a closing line `~~~` alone on its own line.
+3. **Triple-backtick inner fence:** When the sample must use backtick fences, emit a **complete pair**: an opening line beginning with three backticks plus an info string (e.g. `` ```bash ``), the sample lines, then a closing line containing only three backticks. The prompt-workflow hook and clipboard path treat that pair as one unit inside the outer `` ```xml `` fence. For the **most stable on-screen rendering** in chat UIs, use step 1 or step 2 above before this option.
+4. **Cap count:** Include **three to five** distinct illustration blocks (narrative plus optional sample) unless the user’s brief asks for a different depth.
+
+These steps are **machine-facing obligations** for the orchestrator and drafting subagent. The person invoking `/prompt-generator` receives the finished fenced XML; the skill text above is what the model follows when filling `<illustrations>`.
 
 ### 8. Light self-check (subagent, pre-return)
 
@@ -185,7 +194,8 @@ Expand the light self-check with this internal checklist when useful:
 - [ ] Emotion-informed framing is present: collaborative language, explicit success criteria, and explicit permission to express uncertainty ("say so if unsure")
 - [ ] Constraints are surfaced upfront (proactive constraint awareness) so the model can incorporate them into its plan, and each non-obvious constraint carries its motivation
 - [ ] Self-correction chaining is considered when the prompt must hold up over time (generate → review → refine)
-- [ ] All five required XML sections (`<role>`, `<context>`, `<instructions>`, `<constraints>`, `<output_format>`) are present with both opening and closing tags in the fenced artifact
+- [ ] All five required XML sections (`<role>`, `<background>`, `<instructions>`, `<constraints>`, `<output_format>`) are present with both opening and closing tags in the fenced artifact
+- [ ] If `<illustrations>` is present, code or command samples inside it follow §7 (indented block, or tilde fence, or complete triple-backtick pair in that priority order)
 
 ### 9. Deliver (orchestrator)
 
@@ -197,25 +207,25 @@ Audit: pass 15/15
 
 (or `fail N/15 — …`), immediately followed by **one** fenced XML block; **send boundary** is immediately after the closing fence so the user receives a copy-ready pair (audit line + artifact) in one assistant message before the conversation continues.
 
-**Render-survival:** When the fenced XML uses tag names that **collide with HTML5 elements** (`context`, `section`, `summary`, `details`, `header`, `footer`, `main`, `aside`, `article`, `nav`, `figure`), or when the artifact is **very large**, **write the artifact to a file** and give the user the path together with the usual one-line audit. Add a brief **section inventory** (confirming the five required sections) so the user can trust the file even if the inline fence would render poorly. Details: **TARGET_OUTPUT.md — Structural invariant E**.
+**Render-survival:** When the fenced XML uses tag names that **collide with HTML5 elements** (`section`, `summary`, `details`, `header`, `footer`, `main`, `aside`, `article`, `nav`, `figure`), or when the artifact is **very large**, **write the artifact to a file** and give the user the path together with the usual one-line audit. Add a brief **section inventory** (confirming the five required sections) so the user can trust the file even if the inline fence would render poorly. Required grounding uses `<background>` (the old `context` name matched HTML). Details: **TARGET_OUTPUT.md — Structural invariant E**.
 
 ### 10. Default refinement mode (subagent-internal)
 
 For non-trivial requests, run inside the drafting subagent (use **draft-only** when the user explicitly asks for a quick draft / no refinement loop):
 
 1. Base draft
-2. Section refinement in order: `role`, `context`, `instructions`, `constraints`, `output_format`, `examples` (examples optional if unused)
+2. Section refinement in order: `role`, `background`, `instructions`, `constraints`, `output_format`, `illustrations` (illustrations optional if unused)
 3. Merge to one canonical XML prompt
 4. Final **15-row compliance audit** pass/fail with evidence (internal)
 5. If fail: targeted fixes + capped re-audit rounds
 
-Required section list is immutable for this pipeline: `role`, `context`, `instructions`, `constraints`, `output_format`, `examples`.
+Required section list is immutable for this pipeline: `role`, `background`, `instructions`, `constraints`, `output_format`, `illustrations`.
 
 ### 11. Compliance audit — 15-row checklist (internal, audit numerator)
 
 **Two-tier validation — tier 2:** The `15` in `Audit: pass 15/15` counts these **compliance** rows (stable ids for hooks). Tier 1 is the **light self-check** in §8—keep the steps separate so models do not merge them.
 
-**Runtime Stop hook:** In addition to the 15-row internal audit, the `prompt-workflow-stop-guard` Stop hook enforces **section presence** on prompt-workflow responses: any fenced Markdown XML block must include opening and closing tags for `role`, `context`, `instructions`, `constraints`, and `output_format`. Missing tags trigger a retry before the user sees a passing turn. Pair this with **Structural invariant E** in `TARGET_OUTPUT.md` so users still receive intact XML when chat renderers strip HTML-named tags.
+**Runtime Stop hook:** In addition to the 15-row internal audit, the `prompt-workflow-stop-guard` Stop hook enforces **section presence** on prompt-workflow responses: any fenced Markdown XML block must include opening and closing tags for `role`, `background`, `instructions`, `constraints`, and `output_format`. Missing tags trigger a retry before the user sees a passing turn. Pair this with **Structural invariant E** in `TARGET_OUTPUT.md` so users still receive intact XML when chat renderers strip HTML-named tags. `prompt_workflow_gate_core.extract_fenced_xml_content` scans each inner Markdown fence (` ```lang ` through its closing `` ``` `` line) as a unit so hooks and clipboard copy see the **full** XML body, including everything after inner fences inside `<illustrations>`.
 
 | # | Row name |
 |---|----------|

package/skills/prompt-generator/TARGET_OUTPUT.md

@@ -36,7 +36,7 @@ This file is the **target output spec** for eval-driven iteration of the `prompt
 
 **Output:** Send audit line, then one `xml` fence with the full prompt, then stop—the handoff message is complete.
 
-**Handoff prompt quality:** `<context>` must include the bullet lists above so a new session can continue with **zero** access to this chat. Quote decision text verbatim where precision matters.
+**Handoff prompt quality:** `<background>` must include the bullet lists above so a new session can continue with **zero** access to this chat. Quote decision text verbatim where precision matters.
 
 ## Scenario 3: Long unstructured input
 
@@ -70,15 +70,15 @@ This file is the **target output spec** for eval-driven iteration of the `prompt
 ## Structural invariant B — Fenced block closes cleanly
 
 - Use one opening ``` and one closing ``` for the artifact.
-- Balance every XML tag; close `<instructions>`, `<context>`, etc. explicitly.
+- Balance every XML tag; close `<instructions>`, `<background>`, etc. explicitly.
 - End each numbered step inside `<instructions>` with a complete sentence and a fully written list item.
 - The user can copy from the opening ``` through the closing ``` into a new file without manual repair.
 
 ## Structural invariant C — Discovery before lock-in
 
-- When the user is unsure where logic lives, run discovery **before** you freeze the XML; record findings in `<context>` with paths from Glob/Grep.
+- When the user is unsure where logic lives, run discovery **before** you freeze the XML; record findings in `<background>` with paths from Glob/Grep.
 - If discovery finds the owner file(s), reference them with repo-relative paths in `<instructions>`.
-- If discovery is inconclusive, add `<open_question>` in `<context>` naming what you searched and what remains unknown.
+- If discovery is inconclusive, add `<open_question>` in `<background>` naming what you searched and what remains unknown.
 - After the opening fence of the artifact, treat the XML as frozen: finish editing inside that fence; route any new repo searches to a later user turn if needed.
 
 ## Structural invariant D — Certainty in instructions, questions in tags
@@ -89,9 +89,11 @@ This file is the **target output spec** for eval-driven iteration of the `prompt
 
 ## Structural invariant E — Render-survival for XML sections
 
-- **Problem:** Tag names used for prompt XML sections can overlap **HTML5 element names**. Chat renderers may treat those tokens as HTML and hide or alter the content between tags. High-risk examples include: `context`, `section`, `summary`, `details`, `header`, `footer`, `main`, `aside`, `article`, `nav`, `figure`. The raw assistant text may be complete while the **rendered** message looks like sections are missing (notably `<context>`).
-- **Primary mitigation:** When the fenced XML artifact **contains any tag whose local name is on that HTML-collision list**, or when the artifact is **large enough that render truncation is likely**, the orchestrator **must write the full artifact to a file** (default: under `data/prompts/` or a path the user supplied earlier) and **paste the absolute file path** in the chat message. Pair the path with a **short section inventory** confirming all five required sections (`role`, `context`, `instructions`, `constraints`, `output_format`) are present in the file.
-- **Fallback when file write is unavailable:** Escape the **opening angle bracket** of colliding tags (for example `&lt;context>` — user restores `<` when pasting) or use another distinctive wrapper **documented in the same message**, so the user can recover literal XML. State explicitly that the user should restore brackets when copying into another system.
+- **Problem (HTML):** Tag names used for prompt XML sections can overlap **HTML5 element names**. Chat renderers may treat those tokens as HTML and hide or alter the content between tags. High-risk examples include: `section`, `summary`, `details`, `header`, `footer`, `main`, `aside`, `article`, `nav`, `figure`. The former required name `context` matched an HTML element; **required** sections now use `<background>` for situational grounding so the name stays off that list. The raw assistant text may be complete while the **rendered** message looks like sections are missing.
+- **Problem (nested Markdown fences):** A ` ```bash ` (or other inner) line inside the outer ` ```xml ` block is still a line of text in the transcript, but many Markdown renderers treat it as **opening a nested code fence**, which **closes the outer fence early**. Everything after that point (including `</illustrations>` and other closing tags) can appear outside the code block or look “swallowed.” Hooks historically used a regex that stopped at the **first** triple-backtick line; `extract_fenced_xml_content` now walks inner fences (` ```lang ` … closing `` ``` ``) before accepting the outer `` ``` `` that ends the `xml` block.
+- **Primary mitigation:** When the fenced XML artifact **contains any tag whose local name is on the HTML-collision list**, or when the artifact is **large enough that render truncation is likely**, the orchestrator **must write the full artifact to a file** (default: under `data/prompts/` or a path the user supplied earlier) and **paste the absolute file path** in the chat message. Pair the path with a **short section inventory** confirming all five required sections (`role`, `background`, `instructions`, `constraints`, `output_format`) are present in the file.
+- **Authoring rules for code inside `<illustrations>` (orchestrator + drafting subagent — see `SKILL.md` §7):** (1) Format each sample line with **four leading spaces** inside `<illustrations>` as the default for stable rendered chat. (2) **Or** use a **tilde fence**: `~~~` + optional language on the opening line, body, then `~~~` on its own line. (3) **Or** use a **complete triple-backtick pair** (opening `` ```lang `` line, body, closing `` ``` `` line); hooks and clipboard treat the pair as one unit inside the outer `` ```xml `` fence.
+- **Fallback when file write is unavailable:** Escape the **opening angle bracket** of colliding tags (for example `&lt;section>` — user restores `<` when pasting) or use another distinctive wrapper **documented in the same message**, so the user can recover literal XML. State explicitly that the user should restore brackets when copying into another system.
 - **Structural safety net:** Regardless of renderer behavior, the **Stop hook section-presence gate** blocks any prompt-workflow response whose fenced XML is missing any required opening/closing section tag pair. Methodology: [Anthropic — Agent Skills: evaluation and iteration](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#evaluation-and-iteration).
 
 ## XML artifact (minimum sections)
@@ -99,12 +101,12 @@ This file is the **target output spec** for eval-driven iteration of the `prompt
 Include at least:
 
 - `<role>...</role>`
-- `<context>...</context>`
+- `<background>...</background>`
 - `<instructions>...</instructions>`
 - `<constraints>...</constraints>`
 - `<output_format>...</output_format>`
 
-Add `<examples>` when format or tone is easy to misunderstand; nest sections when the task has natural hierarchy.
+Add `<illustrations>` when format or tone is easy to misunderstand; nest sections when the task has natural hierarchy. **Long code samples belong in `<illustrations>`** using the same ordered choices as Structural invariant E: four-space-indented lines first, then tilde fences, then a complete triple-backtick pair if the brief requires backtick fences (see `SKILL.md` §7).
 
 ## Internal 15-row compliance checklist (audit numerator)
 

package/skills/prompt-generator/evals/prompt-generator.json

@@ -15,7 +15,7 @@
         "AskUserQuestion contains 2-4 questions, each with 2-4 options, recommended option first",
         "Final response contains exactly: 1-liner audit status + one fenced XML prompt block",
         "No commentary, tables, audit rows, or explanation outside the fenced block",
-        "Fenced block contains <role>, <context>, <instructions>, <constraints>, <output_format>",
+        "Fenced block contains <role>, <background>, <instructions>, <constraints>, <output_format>",
         "Prompt generation delegated to a subagent (Agent tool call visible in the flow)"
       ]
     },
@@ -30,7 +30,7 @@
       ],
       "expected_behavior": [
         "AskUserQuestion has 1-2 questions — lighter than Scenario 1",
-        "Generated prompt <context> includes: session state, decisions, files modified, next steps",
+        "Generated prompt <background> includes: session state, decisions, files modified, next steps",
         "No redundant discovery tool calls for information already in conversation",
         "Handoff prompt is self-contained — a new session can resume without prior context",
         "Prior decisions preserved in the handoff, not lost or paraphrased away",
@@ -72,10 +72,10 @@
       "prompt": "/prompt-generator Create a prompt for an agent that traces a routing bug across shared_utils/export_handler.py, orchestrator.py, and download_manager.py — find where extract_apk is called and whether it handles APK signature check failures",
       "files": ["packages/samsung-automation/shared_utils/export_handler.py"],
       "expected_behavior": [
-        "No tool_use blocks appear after the first fence marker of the prompt artifact",
+        "No tool_use blocks appear after the first fence marker of the canonical prompt artifact",
         "All Glob/Grep discovery calls precede the AskUserQuestion",
         "All AskUserQuestion interactions precede the fenced block",
-        "Prompt artifact emits in a single uninterrupted response"
+        "Review the last successful Audit + fenced xml pair; blocked retry attempts preserved by flattened transcript exports do not count as additional delivered artifacts"
       ]
     },
     {
@@ -85,7 +85,7 @@
       "prompt": "/prompt-generator Write a detailed agent-harness prompt for a TDD bug-fix workflow that traces a routing error across 5+ files, with state management for multi-window execution and structured test tracking",
       "files": [],
       "expected_behavior": [
-        "Opening fence has a matching closing fence",
+        "The canonical prompt artifact has one opening xml fence and one matching closing fence; flattened transcript exports are normalized to that same boundary before review",
         "Every XML tag properly opened and closed",
         "No truncation at numbered-list bullets (the Issue #41 failure mode)",
         "No mid-sentence cuts or incomplete sections",
@@ -101,9 +101,9 @@
       "expected_behavior": [
         "Discovery tool calls attempt to locate scoring logic before prompt generation",
         "If resolved: prompt references concrete file paths from discovery",
-        "If unresolved: prompt contains <open_question> in <context> for downstream agent",
-        "No re-entry to discovery after fenced block starts",
-        "AskUserQuestion may surface the uncertainty if discovery was inconclusive"
+        "If unresolved: prompt contains <open_question> in <background> for downstream agent",
+        "No re-entry to discovery after the canonical artifact fence starts",
+        "AskUserQuestion may surface the uncertainty if discovery was inconclusive; when discovery resolves concrete paths before the artifact, absence of <open_question> is expected"
       ]
     },
     {
@@ -131,7 +131,7 @@
         "Every instruction phrased as a positive directive: what TO do, what TO produce, what TO enforce",
         "Constraints section uses affirmative boundaries: 'only X', 'always X', 'ensure X', 'require X' — positive framing throughout",
         "Example: 'Ensure all functions have explicit return types' passes; 'Do not leave return types implicit' fails; 'Avoid missing return types' fails",
-        "Applies to all sections inside the fenced block: <role>, <context>, <instructions>, <constraints>, <output_format>"
+        "Applies to all sections inside the fenced block: <role>, <background>, <instructions>, <constraints>, <output_format>"
       ]
     },
     {
@@ -141,7 +141,7 @@
       "prompt": "/prompt-generator Write a system prompt for a Python linting agent that auto-fixes code style issues in this repo",
       "files": [],
       "expected_behavior": [
-        "Fenced XML block contains opening and closing tags for all five required sections: role, context, instructions, constraints, output_format",
+        "Fenced XML block contains opening and closing tags for all five required sections: role, background, instructions, constraints, output_format",
         "Each required section contains substantive content (minimum one sentence each)",
         "The Stop hook section-presence check passes for this output (no missing section tags)",
         "Sections appear in order: role first, output_format last among the five required sections"
@@ -151,10 +151,10 @@
       "id": 11,
       "name": "section_missing_triggers_hook_block",
       "scenario": "Section completeness gate — failure path",
-      "prompt": "Synthetic eval: assistant final message is prompt-workflow shaped (overall_status, checklist, scope anchors, runtime signals) with a fenced Markdown XML block whose body omits the entire context section (no context opening/closing tags); observer asserts Stop hook behavior and successful retry.",
+      "prompt": "Synthetic eval: assistant final message is prompt-workflow shaped (overall_status, checklist, scope anchors, runtime signals) with a fenced Markdown XML block whose body omits the entire background section (no background opening/closing tags); observer asserts Stop hook behavior and successful retry.",
       "files": [],
       "expected_behavior": [
-        "The Stop hook runs _check_required_xml_sections and returns a block decision naming context as a missing section",
+        "The Stop hook runs _check_required_xml_sections and returns a block decision naming background as a missing section",
         "The model retry includes all five required sections with both opening and closing tags",
         "The retry output passes the section-presence gate (empty missing list from missing_required_xml_sections)"
       ]
@@ -166,10 +166,22 @@
       "prompt": "/prompt-generator Write a comprehensive agent prompt for migrating a large Prisma schema and all related API routes, with step-by-step rollout, rollback, and verification — artifact sized like the migration prompt that triggered chat render stripping.",
       "files": [],
       "expected_behavior": [
-        "When the artifact exceeds a size threshold or contains XML section tag names that collide with HTML5 elements (context, section, summary, details, header, footer, main, aside, article, nav, figure), the orchestrator writes the full artifact to a file under data/prompts/ or a user-specified path",
+        "When the artifact exceeds a size threshold or contains XML section tag names that collide with HTML5 elements (section, summary, details, header, footer, main, aside, article, nav, figure), the orchestrator writes the full artifact to a file under data/prompts/ or a user-specified path",
         "The file contains the complete XML with all tags preserved as literal text",
         "The user-facing message states the file path and briefly inventories which required sections the artifact contains"
       ]
+    },
+    {
+      "id": 13,
+      "name": "nested_inner_fence_does_not_truncate_xml_for_hooks",
+      "scenario": "Structural invariant E — nested Markdown fences inside ```xml",
+      "prompt": "/prompt-generator Include <illustrations> with a bash snippet using triple-backtick fences inside the XML, mirroring real prompts that previously hid </illustrations> in chat and broke hook extraction.",
+      "files": [],
+      "expected_behavior": [
+        "prompt_workflow_gate_core.extract_fenced_xml_content includes text after inner ```bash ... ``` lines up to the final closing ``` of the xml fence",
+        "missing_required_xml_sections sees closing tags for role, background, instructions, constraints, output_format when those appear after nested fences",
+        "SKILL.md §7 states ordered authoring steps for <illustrations>: four-space-indented sample lines, then tilde fences, then a complete triple-backtick pair when required"
+      ]
     }
   ]
 }

package/skills/skill-builder/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: skill-builder
+description: >-
+  Orchestrates the complete skill-building lifecycle using evaluation-driven
+  development. Routes through gap analysis, eval creation, skill writing (via
+  skill-writer), subagent testing (via skill-creator infrastructure), and
+  iterative refinement. Use when creating new skills, improving existing skills,
+  or optimizing skill descriptions. Triggers: 'build a skill', 'new skill
+  workflow', 'improve this skill', 'optimize skill description', 'skill
+  development lifecycle'.
+---
+
+@${CLAUDE_SKILL_DIR}/references/eval-driven-flow.md
+
+# Skill Builder
+
+**Core principle:** Evaluation-driven development. Build evals BEFORE writing extensive documentation. This ensures skills solve real problems rather than documenting imagined ones.
+
+Source: [Anthropic Skill Best Practices - Evaluation and Iteration](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#evaluation-and-iteration)
+
+## When this skill applies
+
+Trigger for requests to **build**, **improve**, or **polish** a skill through the full evaluation-driven lifecycle. This skill orchestrates the process -- it delegates writing to `/skill-writer` and evaluation infrastructure to the `skill-creator` plugin.
+
+For quick skill syntax questions or one-off SKILL.md edits, use `/skill-writer` directly instead.
+
+## Routing
+
+Assess the user's intent from conversation context and existing artifacts. Route directly:
+
+**Creating a new skill?**
+Read `${CLAUDE_SKILL_DIR}/workflows/new-skill.md` and follow it.
+
+**Improving an existing skill?**
+Read `${CLAUDE_SKILL_DIR}/workflows/improve-skill.md` and follow it.
+
+**Final polish only (description optimization, trigger eval)?**
+Read `${CLAUDE_SKILL_DIR}/workflows/polish-skill.md` and follow it.
+
+**Ambiguous?** Ask: "Are you creating a new skill, improving an existing one, or doing a final polish pass?"
+
+## The Claude A / Claude B Pattern
+
+You and the user are **Claude A** -- the expert who designs and refines the skill. Subagents running the built skill on eval tasks are **Claude B** -- the agent using the skill to perform real work.
+
+> "Work with one instance of Claude ('Claude A') to create a Skill that is used by other instances ('Claude B'). Claude A helps you design and refine instructions, while Claude B tests them in real tasks."
+
+The feedback loop: observe Claude B's behavior, bring insights back, refine the skill, test again.
+
+## Phase Overview
+
+| Phase | Purpose | Delegated To |
+|-------|---------|-------------|
+| 1. Identify gaps | Document what fails without the skill | This skill (guided conversation) |
+| 2. Build evals | Create 3+ scenarios testing the gaps | This skill (templates + user input) |
+| 3. Write skill | Minimal instructions addressing gaps | `/skill-writer` |
+| 4. Test | Subagent runs with/without skill, grade, benchmark | `skill-creator` eval infrastructure |
+| 5. Iterate | Review results, refine, re-test | This skill + `/skill-writer` + Phase 4 |
+| 6. Polish | Description optimization, trigger eval, final check | `skill-creator` description optimizer |
+
+## Principles (apply across all phases)
+
+1. **Evals before documentation.** Never write extensive skill content without evaluation scenarios to validate it.
+
+2. **Minimal instructions first.** Write just enough to pass evaluations. Resist the urge to over-document.
+
+3. **Generalize from feedback.** The skill will be used across many prompts. Do not overfit to test cases.
+
+4. **Explain the why.** Theory of mind beats rigid rules. Help the model understand reasoning, not just constraints.
+
+5. **Observe, do not assume.** Iterate based on what Claude B actually does, not what you think it should do.
+
+## Delegation Details
+
+See `${CLAUDE_SKILL_DIR}/references/delegation-map.md` for exact invocation patterns and integration points between this orchestrator, `/skill-writer`, and `skill-creator`.
+
+## File Index
+
+| File | Purpose |
+|------|---------|
+| `workflows/new-skill.md` | Full lifecycle for new skills (6 phases) |
+| `workflows/improve-skill.md` | Observation-first flow for existing skills |
+| `workflows/polish-skill.md` | Description optimization and final validation |
+| `references/eval-driven-flow.md` | Official Anthropic methodology with citations |
+| `references/delegation-map.md` | Integration map for skill-writer and skill-creator |
+| `templates/gap-analysis.md` | Template for Phase 1 gap documentation |
+| `templates/eval-scenario.json` | Eval template matching skill-creator schema |

package/skills/skill-builder/references/delegation-map.md

@@ -0,0 +1,151 @@
+# Delegation Map
+
+How the skill-builder orchestrator integrates with external skills at each phase.
+
+## Phase 1: Identify Gaps -- This Orchestrator
+
+No external delegation. The orchestrator guides a conversation with the user to document what fails without a skill.
+
+**Output:** `[skill-name]-workspace/gap-analysis.md` using the template at `templates/gap-analysis.md`.
+
+## Phase 2: Build Evals -- This Orchestrator
+
+No external delegation. The orchestrator helps the user transform gaps into eval scenarios.
+
+**Output:** `[skill-name]-workspace/evals/evals.json` using the template at `templates/eval-scenario.json`.
+
+**Baseline runs:** Spawn subagents WITHOUT any skill for each eval scenario. These run as background Agent tasks.
+
+## Phase 3: Write Skill -- Delegate to `/skill-writer`
+
+Invoke `/skill-writer` with the following context in your prompt:
+
+```
+Create a skill based on this gap analysis and eval scenarios.
+
+Gap analysis: [paste or reference gap-analysis.md]
+Eval scenarios: [paste or reference evals.json expected_output fields]
+Baseline failures: [summarize what Claude got wrong without the skill]
+
+Constraint: Write the minimum instructions needed to address these specific gaps.
+Do not over-document. Every line must serve a documented gap.
+```
+
+skill-writer handles: type classification, degree of freedom, frontmatter, body structure, progressive disclosure, self-check.
+
+**Output:** The skill's SKILL.md (and optional REFERENCE.md, scripts, etc.)
+
+## Phase 4: Test -- Delegate to skill-creator Infrastructure
+
+The skill-creator plugin provides the eval infrastructure. Reference its components directly:
+
+### Spawning test runs
+
+For each eval, spawn TWO subagents in the SAME turn (parallel):
+
+**With-skill subagent:**
+```
+Execute this task:
+- Read the skill at [path-to-skill]/SKILL.md and follow its instructions
+- Task: [eval prompt from evals.json]
+- Input files: [eval files if any]
+- Save all output files to: [workspace]/iteration-N/eval-[name]/with_skill/outputs/
+- Save a transcript of your complete work to: [workspace]/iteration-N/eval-[name]/with_skill/transcript.md
+- At the end, write a metrics.json with tool call counts and file list
+```
+
+**Without-skill subagent** (baseline):
+For iteration-1, reuse baseline results from Phase 2 (iteration-0). For later iterations, the original baseline persists.
+
+### Grading
+
+Read the grading agent instructions from the skill-creator plugin:
+`[skill-creator-plugin-path]/agents/grader.md`
+
+Spawn a grader subagent for each run with:
+- The expectations from evals.json
+- The transcript path
+- The outputs directory
+
+**Output:** `grading.json` in each run directory.
+
+### Benchmarking
+
+Run the aggregation script from the skill-creator plugin directory:
+```bash
+cd [skill-creator-plugin-path] && python -m scripts.aggregate_benchmark [workspace]/iteration-N --skill-name [name]
+```
+
+**Output:** `benchmark.json` and `benchmark.md` in the iteration directory.
+
+### Eval Viewer
+
+Launch the viewer from the skill-creator plugin:
+```bash
+python [skill-creator-plugin-path]/eval-viewer/generate_review.py \
+  [workspace]/iteration-N \
+  --skill-name "[name]" \
+  --benchmark [workspace]/iteration-N/benchmark.json
+```
+
+For iteration 2+, add: `--previous-workspace [workspace]/iteration-[N-1]`
+
+If no browser/display available, add: `--static [workspace]/iteration-N/review.html`
+
+**Output:** Browser-based reviewer where the user inspects outputs and leaves feedback.
+
+### Finding the skill-creator plugin path
+
+The skill-creator plugin is installed at a path like:
+`~/.claude/plugins/marketplaces/claude-plugins-official/plugins/skill-creator/skills/skill-creator/`
+
+To find it dynamically, search for the skill-creator SKILL.md:
+```bash
+find ~/.claude/plugins -name "SKILL.md" -path "*/skill-creator/*" 2>/dev/null | head -1
+```
+
+Then derive the plugin root from that path.
+
+## Phase 5: Iterate -- This Orchestrator + `/skill-writer`
+
+The orchestrator reads feedback.json and transcripts, synthesizes observations, then delegates refinement to `/skill-writer`:
+
+```
+Refine this existing skill based on these observations from testing.
+
+Current SKILL.md: [paste or reference]
+User feedback: [from feedback.json]
+Behavioral observations: [from transcript analysis]
+
+Specific issues to address:
+1. [Issue from feedback]
+2. [Issue from observation]
+
+Constraint: Only change what the feedback demands. Do not reorganize working content.
+```
+
+Then return to Phase 4 with the refined skill.
+
+## Phase 6: Polish -- Delegate to skill-creator Description Optimizer
+
+The skill-creator plugin includes a description optimization loop:
+
+### Trigger eval generation
+
+Generate 20 realistic eval queries (10 should-trigger, 10 should-not-trigger). Use the HTML review template from:
+`[skill-creator-plugin-path]/assets/eval_review.html`
+
+### Optimization loop
+
+```bash
+cd [skill-creator-plugin-path] && python -m scripts.run_loop \
+  --eval-set [path-to-trigger-eval.json] \
+  --skill-path [path-to-skill] \
+  --model [current-model-id] \
+  --max-iterations 5 \
+  --verbose
+```
+
+### Final validation
+
+Run the skill-writer self-check rubric (from skill-writer's Step 9) against the finished skill. All items must pass.

package/skills/skill-builder/templates/gap-analysis.md

@@ -0,0 +1,41 @@
+# Gap Analysis: [Skill Name]
+
+## Task Description
+
+[What the user is trying to accomplish -- the capability this skill should provide]
+
+## Gaps Identified
+
+### Gap 1: [Descriptive Name]
+
+- **What happened:** [Description of the failure or missing context when working without a skill]
+- **What was needed:** [The specific context, instruction, or knowledge that would fix it]
+- **Frequency:** [How often this comes up in real usage]
+- **Example task:** [A concrete task that exposes this gap]
+
+### Gap 2: [Descriptive Name]
+
+- **What happened:** [Description]
+- **What was needed:** [Context/instruction needed]
+- **Frequency:** [Frequency]
+- **Example task:** [Concrete example]
+
+### Gap 3: [Descriptive Name]
+
+- **What happened:** [Description]
+- **What was needed:** [Context/instruction needed]
+- **Frequency:** [Frequency]
+- **Example task:** [Concrete example]
+
+## Patterns
+
+- [Recurring themes across gaps -- e.g., "Claude consistently lacks knowledge about X"]
+- [Common failure modes -- e.g., "Without guidance, Claude chooses library A when library B is required"]
+- [Context that was repeatedly provided manually]
+
+## Candidate Eval Scenarios
+
+- [Task that would expose Gap 1 -- becomes the seed for an eval]
+- [Task that would expose Gap 2]
+- [Task that would expose multiple gaps simultaneously]
+- [Edge case that tests boundary behavior]