claude-dev-env 2.0.2 → 2.2.0

package/skills/skill-builder/references/deterministic-elements.md

@@ -0,0 +1,218 @@
+# Deterministic skill elements
+
+Source: [Anthropic — Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) (scripts, progressive disclosure), [Lessons from Building Claude Code](thariq-x-post-skills.json), repo skill conventions (`skills/CLAUDE.md`), `docs/CODE_RULES.md`, host task tools (`TaskCreate`, `TodoWrite`, and equivalents).
+
+## Contents
+
+- [Rule](#rule)
+- [What counts as deterministic](#what-counts-as-deterministic)
+- [Placement](#placement)
+- [Task-tool tracking (not markdown checklists)](#task-tool-tracking-not-markdown-checklists)
+- [CODE_RULES bar (every code file in the skill)](#code_rules-bar-every-code-file-in-the-skill)
+- [Inventory (required before Write)](#inventory-required-before-write)
+- [Required task seeds (Gather / gates)](#required-task-seeds-gather--gates)
+- [Anti-patterns (fail self-audit)](#anti-patterns-fail-self-audit)
+- [How the body should look](#how-the-body-should-look)
+- [Relation to other skill-builder specs](#relation-to-other-skill-builder-specs)
+
+## Rule
+
+Any skill element that is **deterministic** ships as **code**, a **fixed artifact**, or a **session task** — never as prose-only work tracking.
+
+| Deterministic shape | Required home |
+|---|---|
+| Validators, transforms, detection, mechanical sequences | `scripts/` or `workflow/*.mjs` (+ tests, `*_constants/`) |
+| Verbatim templates | `templates/` |
+| Long fixed tables / catalogs Claude must not paraphrase | `reference/` |
+| Ordered work the agent must complete without skipping | Host **task tool** (`TaskCreate`, `TodoWrite`, or equivalent) |
+
+> "One of the most powerful tools you can give Claude is code — letting Claude spend its turns on composition rather than reconstructing boilerplate."
+
+> "These can include deterministic scripts or tools for maximum robustness."
+
+Judgment, routing, and refusal stay in markdown. Fixed procedures and transforms stay in scripts. Required step lists stay on the task list — not as markdown `[ ]` boxes.
+
+## What counts as deterministic
+
+A process step is deterministic when **all** of these hold:
+
+1. Same inputs → same outputs (no open-ended taste or design judgment).
+2. Success or failure is machine-checkable (exit code, schema, path exists, token present, task marked complete with evidence).
+3. A human could write the step as a pure function, a fixed command sequence, or a fixed task list.
+
+### Deterministic (must leave prose-only tracking)
+
+| Shape | Home |
+|---|---|
+| Validators, linters, schema/packet checks | `scripts/` (or `workflow/*.mjs`) |
+| Multi-step mechanical sequences (compile, collect, gate, scan) | `scripts/` |
+| Detection logic (regex sets, path rules, pattern catalogs) | `scripts/` + `*_constants/` |
+| Sorting, ranking, ID assignment, path resolution | `scripts/` |
+| Verbatim prompt or output templates | `templates/` (skill body points to the path) |
+| Long fixed tables / catalogs | `reference/` or a script that prints the list |
+| Inline Python / JS fences meant to run | Extract to `scripts/` or `workflow/` |
+| Ordered gates, audits, author checks the agent must finish | **Task tool** — seed each item; mark complete with evidence |
+
+### Judgment (markdown is correct)
+
+| Shape | Home |
+|---|---|
+| When to invoke the skill; refusal lines | `SKILL.md` |
+| How to weigh trade-offs or pick among valid approaches | `SKILL.md` / `reference/` |
+| Gotchas and failure modes | `SKILL.md` |
+| Sub-skill routing and composition | `SKILL.md` |
+| Degree-of-freedom guidance | `SKILL.md` |
+
+### Borderline
+
+- A one-liner that only launches a tool with no branching → may stay in body; the moment it grows patterns, branches, or magic strings → `scripts/`.
+- A short narrative process outline (Step 1 / Step 2 headings) may stay in body **if** every required work item is also registered on the task list. Headings are orientation; the task list is the completion surface.
+- Markdown `[ ]` as the only place an agent is expected to track progress → **always fail** when a task tool is available.
+
+## Placement
+
+| Artifact | Directory / surface | Role |
+|---|---|---|
+| Python helpers | `scripts/` | Run, do not load into context as source |
+| Workflow scripts | `workflow/` (`*.mjs`) | Host `Workflow` tool entrypoints |
+| Named constants | `*_constants/` next to the scripts that import them | CODE_RULES config surface for skill code |
+| Fixed templates | `templates/` | Copy/fill or pass to a script |
+| Domain tables, long fixed lists | `reference/` | Load on demand |
+| Required work items | Host task tool | Create at skill start; complete with evidence |
+| Process skeleton + pointers | `SKILL.md` | "Run `scripts/foo.py` …" / "Register tasks from …" |
+
+`SKILL.md` names the script, when to run it, what it prints, and how to treat non-zero exit. It does not restate the algorithm. It names which task-seed lists to load and when to register them.
+
+## Task-tool tracking (not markdown checklists)
+
+Harnesses expose task tools so agents cannot silently skip steps. A skill that expects the agent to finish an ordered set of work **must**:
+
+1. Publish the items as a **task seed list** (plain bullets or numbered lines in a reference file — **no** `- [ ]` syntax).
+2. Instruct the agent, at the start of that phase, to **create one session task per item** via the host tool:
+   - Prefer `TaskCreate` (or host `Task` / tasks MCP) when present.
+   - Else `TodoWrite` / equivalent.
+   - Fail closed: if no task tool exists, say so and stop — do not fall back to markdown checkboxes as the tracking plan.
+3. Require each task to be marked complete only with evidence (PASS / FAIL+file:line / N/A+reason / exit code / path).
+4. Ban "copy this checklist into your response and check it off" as the primary tracking method.
+
+Reference files may still **catalog** the required items so authors and agents know what to seed. Catalogs are data for `TaskCreate`; they are not the live work board.
+
+### Skills that ship multi-step process
+
+Any skill whose process has two or more required steps must include a short **Task seeding** instruction in `SKILL.md` or the active workflow:
+
+```markdown
+## Task seeding
+
+Before Step N, register every item under [reference/…-tasks.md] as a session task
+(TaskCreate / TodoWrite). Work only from the task list. Mark complete with evidence.
+```
+
+The seed list file lives under `reference/` (or is a named section of an existing reference). Do not use `- [ ]` in that file.
+
+## CODE_RULES bar (every code file in the skill)
+
+Skill scripts are production code. They obey the same rules as the rest of the repo (`docs/CODE_RULES.md` / root `AGENTS.md`), including:
+
+- **Named constants** — no bare magic numbers/strings in function bodies; skill-local values live in a `*_constants/` package the script imports.
+- **Types** — parameters and returns annotated; no bare `Any` / untyped escape hatches.
+- **Naming** — full words; `is_`/`has_` booleans; `all_` collections; `each_` multi-letter loops; banned prefixes (`handle_`, `process_`, `manage_`, `do_`).
+- **Errors** — catch specific exceptions; exit with a clear code and message; do not punt raw traces to Claude as the recovery plan.
+- **Tests** — every new production path ships a paired test in the same change (`test_*.py` beside the script, or `*.test.mjs` for workflow helpers).
+- **Execute intent** — body says `Run scripts/…` (execute), not "see the script for the algorithm," unless the script is deliberately reference-only.
+
+JS/TS skill helpers follow the same spirit: named constants, no silent stubs, paired tests.
+
+## Inventory (required before Write)
+
+Every new skill and every improve pass that touches process steps records a **deterministic elements inventory** in the gap analysis:
+
+| Column | Content |
+|---|---|
+| Step | Short name |
+| Class | `deterministic` \| `judgment` \| `borderline` |
+| Home | Path (`scripts/…`, `workflow/…`, `templates/…`, `reference/…`, `task-seed:…`, or `SKILL.md`) |
+| Evidence | Why this class (one line) |
+| Paired test | Path if code; `task-tool` if work list; N/A + reason if pure judgment |
+
+Rules:
+
+- Every `deterministic` row has a real path under `scripts/`, `workflow/`, `templates/`, `reference/`, or a `task-seed:` pointer — not prose-only.
+- Every code path under `scripts/` or `workflow/` has a paired test path (or a one-line pure-data reason).
+- Every required multi-step work list has a `task-seed:` home and a body instruction to register those tasks.
+- A `borderline` row kept in prose has a one-line why it is not worth extracting.
+
+## Required task seeds (Gather / gates)
+
+At the **deterministic-elements gate** (and again at self-audit), register **each** line below as its own session task, then complete it with evidence. Do not track these as markdown checkboxes.
+
+1. Every process step is classified (deterministic / judgment / borderline).
+2. Every deterministic step has a script, workflow, template, reference, or task-seed path — not prose-only.
+3. No fenced executable source lives only inside `SKILL.md` when it is meant to run.
+4. No multi-branch detection/validation logic lives only as an `rg`/`grep` one-liner in the body.
+5. Each script states execute vs read intent from the body.
+6. Each script uses a `*_constants/` (or equivalent) package for non-obvious literals.
+7. Each new script path has a paired test in the same delivery.
+8. `SKILL.md` process steps point at paths; they do not re-implement the script in markdown.
+9. Every required multi-step work list in the skill is a task-seed catalog plus a seed instruction — not a markdown `- [ ]` board.
+
+## Anti-patterns (fail self-audit)
+
+- Full Python/JS program in a markdown code fence as the skill's real implementation.
+- Giant shell one-liner with many alternations as the only form of a detector.
+- 10+ step mechanical verification sequence written only as numbered markdown with no script.
+- "Deterministic" claim in prose with no executable path Claude can run.
+- Script that dumps unhandled exceptions for Claude to interpret.
+- Magic literals and unnamed thresholds inside skill scripts.
+- New script with no paired test.
+- Markdown `- [ ]` checklist as the agent's progress tracker when a task tool is available.
+- "Copy this checklist into your response and check off items" as the skill's completion protocol.
+- Task-seed list written with checkbox syntax (`- [ ]`) so agents tick markdown instead of creating tasks.
+
+## How the body should look
+
+**Good (script):**
+
+```markdown
+## Step 3: Validate packet
+
+Run `scripts/validate_packet.py --packet <path>`.
+- Exit 0 → continue.
+- Exit 2 → fix listed paths, re-run (do not invent missing sections).
+```
+
+**Good (required work list):**
+
+```markdown
+## Task seeding
+
+Before self-audit, register every item in `reference/self-audit-tasks.md`
+as a session task (TaskCreate). Complete each with PASS / FAIL+evidence / N/A+reason.
+```
+
+**Bad:**
+
+```markdown
+## Step 3: Validate packet
+
+Check that README.md, packet.json, context/source-map.md, …
+Also run compileall, then pytest --collect-only, then scan for …
+(and three more mechanical steps only in prose)
+
+## Self-audit
+
+Copy this checklist into your response and check every box:
+- [ ] Item one
+- [ ] Item two
+```
+
+## Relation to other skill-builder specs
+
+| Spec | Concern |
+|---|---|
+| `progressive-disclosure.md` | Where files live and how the hub points to them |
+| `skill-modularity.md` | One capability; compose peer skills by name |
+| `description-field.md` | Frontmatter trigger catalog |
+| **This file** | Which elements must be code, task-tool lists, or fixed artifacts |
+
+Progressive disclosure alone does not satisfy this file: moving a mechanical sequence into `reference/` as prose still fails when the sequence is deterministic — it belongs in `scripts/` or on the task list.

package/skills/skill-builder/references/self-audit-checklist.md

@@ -1,109 +1,126 @@
-# Self-Audit Checklist
+# Self-Audit Task Seeds
 
 Mandatory post-build verification. Every item must pass before a skill is delivered. Run after writing a new skill, improving an existing one, or polishing.
 
-Source synthesis: [Anthropic best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), [Lessons from Building Claude Code](thariq-x-post-skills.json), model skills (bugteam, pr-converge).
+**How to run:** Register **each** bullet below as a session task (`TaskCreate`, `TodoWrite`, or host equivalent). Complete tasks only with evidence (PASS / FAIL+file:line / N/A+reason). Do not track progress as markdown `- [ ]` boxes in chat.
+
+Source synthesis: [Anthropic best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), [Lessons from Building Claude Code](thariq-x-post-skills.json), model skills (bugteam, pr-converge), host task tools.
 
 ## Core quality
 
-- [ ] **Conciseness** — Only context Claude doesn't already have. Every line justifies its token cost.
+- **Conciseness** — Only context Claude doesn't already have. Every line justifies its token cost.
   > "Default assumption: Claude is already very smart."
-- [ ] **Degree of freedom** — Matches task fragility. Low for narrow bridges, high for open fields.
+- **Degree of freedom** — Matches task fragility. Low for narrow bridges, high for open fields.
   > "Match the level of specificity to the task's fragility and variability."
-- [ ] **Naming convention** — Name uses gerund form (verb-ing) unless it's a well-known acronym or proper name. Lowercase, numbers, hyphens only. Max 64 chars. No reserved words.
+- **Naming convention** — Name uses gerund form (verb-ing) unless it's a well-known acronym or proper name. Lowercase, numbers, hyphens only. Max 64 chars. No reserved words.
   > "Use consistent naming patterns to make Skills easier to reference."
-- [ ] **Description is a trigger catalog** — Capability stem (what tokens) + concrete Triggers list (when). Third person. Max 1024 chars. No XML. Spec: `description-field.md`.
+- **Description is a trigger catalog** — Capability stem (what tokens) + concrete Triggers list (when). Third person. Max 1024 chars. No XML. Spec: `description-field.md`.
   > "The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills."
-- [ ] **Description is not a story** — No narrative prose, benefits language ("helps you"), first/second person, or process/implementation dump in frontmatter.
+- **Description is not a story** — No narrative prose, benefits language ("helps you"), first/second person, or process/implementation dump in frontmatter.
   > "The description field is not a summary — it's a description of when to trigger."
-- [ ] **Description match surface** — Includes specific phrases, slash forms, and file types a user would say; distinguishable from sibling skills.
+- **Description match surface** — Includes specific phrases, slash forms, and file types a user would say; distinguishable from sibling skills.
   > "Be specific and include key terms."
-- [ ] **SKILL.md body under 500 lines**
+- **SKILL.md body under 500 lines**
   > "Keep SKILL.md body under 500 lines for optimal performance."
-- [ ] **One level deep** — All reference files link directly from SKILL.md. No nested references.
+- **One level deep** — All reference files link directly from SKILL.md. No nested references.
   > "Claude may partially read files when they're referenced from other referenced files."
-- [ ] **TOC on files over 100 lines** — Every reference file >100 lines has a table of contents.
+- **TOC on files over 100 lines** — Every reference file >100 lines has a table of contents.
   > "This ensures Claude can see the full scope of available information even when previewing with partial reads."
-- [ ] **No time-sensitive claims** — Or isolated in "old patterns" section.
+- **No time-sensitive claims** — Or isolated in "old patterns" section.
   > "Don't include information that will become outdated."
-- [ ] **Consistent terminology** — One term per concept throughout.
+- **Consistent terminology** — One term per concept throughout.
   > "Consistency helps Claude understand and follow instructions."
-- [ ] **Forward slashes only** — File paths use `/`, not `\`.
+- **Forward slashes only** — File paths use `/`, not `\`.
   > "Unix-style paths work across all platforms."
-- [ ] **Default provided, not options menu** — One recommended approach, escape hatch for special cases.
+- **Default provided, not options menu** — One recommended approach, escape hatch for special cases.
   > "Don't present multiple approaches unless necessary. Provide a default with escape hatch."
-- [ ] **Gotchas section present** — Highest-signal content. Built from real failure observations.
+- **Gotchas section present** — Highest-signal content. Built from real failure observations.
   > "The highest-signal content in any skill is the Gotchas section."
-- [ ] **Doesn't state the obvious** — Pushes Claude out of defaults, doesn't re-teach what Claude knows.
+- **Doesn't state the obvious** — Pushes Claude out of defaults, doesn't re-teach what Claude knows.
   > "Focus on information that pushes Claude out of its normal way of thinking."
-- [ ] **Not railroading** — Gives information and flexibility, not rigid scripts.
+- **Not railroading** — Gives information and flexibility, not rigid scripts.
   > "Give Claude the information it needs, but give it the flexibility to adapt to the situation."
-- [ ] **When-this-applies section** — Trigger conditions clear. Refusal cases with exact response text.
+- **When-this-applies section** — Trigger conditions clear. Refusal cases with exact response text.
   > bugteam pattern — "Refusals — first match wins; respond with the quoted line exactly and stop."
-- [ ] **File index present** — Every file in the package listed with its purpose.
+- **File index present** — Every file in the package listed with its purpose.
   > "Tell Claude what files are in your skill, and it will read them at appropriate times."
-- [ ] **Concrete examples** — Input/output pairs or exit scenarios, not abstract descriptions.
+- **Concrete examples** — Input/output pairs or exit scenarios, not abstract descriptions.
   > "Examples help Claude understand the desired style and level of detail more clearly than descriptions alone."
-- [ ] **Workflows have checklists** — Multi-step processes include copyable `[ ]` checklists.
-  > "For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses."
-- [ ] **Feedback loops where quality-critical** — Run validator → fix → repeat pattern.
+- **Workflows seed tasks** — Multi-step processes ship a task-seed list and instruct the agent to register each item on the host task tool (`TaskCreate` / `TodoWrite`). No markdown `- [ ]` as the progress board when a task tool is available.
+  > Spec: `deterministic-elements.md` — Task-tool tracking.
+- **Feedback loops where quality-critical** — Run validator → fix → repeat pattern.
   > "This pattern greatly improves output quality."
-- [ ] **Constraints separated** — Non-negotiables in CONSTRAINTS.md or equivalent section.
+- **Constraints separated** — Non-negotiables in CONSTRAINTS.md or equivalent section.
   > bugteam pattern — constraints file with design rationale.
-- [ ] **Folder map at bottom** — Lists directories and their purposes.
+- **Folder map at bottom** — Lists directories and their purposes.
   > pr-converge pattern — "Folder map" section.
 
 ## Skill-type-specific
 
-- [ ] **Skill type classified** — Fits one of 9 types. Folder structure matches type recommendation.
+- **Skill type classified** — Fits one of 9 types. Folder structure matches type recommendation.
   > "The best skills fit cleanly into one; the more confusing ones straddle several."
-- [ ] **Domain layout appropriate** — If multiple domains, organized by domain (reference/finance.md, reference/sales.md).
+- **Domain layout appropriate** — If multiple domains, organized by domain (reference/finance.md, reference/sales.md).
   > Pattern 2 — domain-specific organization.
 
-## Code and scripts (if applicable)
+## Deterministic elements
+
+Mandatory for every skill. Spec: `deterministic-elements.md`. Progressive disclosure alone does not satisfy these items.
 
-- [ ] **Scripts solve, don't punt** — Error handling explicit, no raw exceptions for Claude to figure out.
+- **Process steps classified** — Every process step is marked deterministic, judgment, or borderline (inventory in gap analysis or equivalent).
+  > "One of the most powerful tools you can give Claude is code."
+- **Deterministic steps are not prose-only** — Each deterministic step has a real path under `scripts/`, `workflow/`, `templates/`, `reference/`, or a task-seed list — not only markdown steps, fenced source, markdown checkboxes, or a giant shell one-liner in the body.
+  > "These can include deterministic scripts or tools for maximum robustness."
+- **Body points at code** — SKILL.md names when to run each script, what it prints, and how to treat non-zero exit; it does not restate the algorithm.
+  > "Make clear in your instructions whether Claude should execute the script or read it as reference."
+- **No executable-only fences** — Full programs meant to run do not live only inside `SKILL.md` code fences.
+- **CODE_RULES on skill scripts** — Any `scripts/` or `workflow/` code uses named constants (`*_constants/` or equivalent), type annotations where the language supports them, specific error handling, and no banned identifier/prefix patterns from CODE_RULES.
+- **Paired tests for new scripts** — Each new production script path ships a paired test in the same delivery (N/A only when the package has zero code files).
+- **Task seeds for required work lists** — Every ordered gate/audit/process list the agent must finish is a plain task-seed catalog plus a seed instruction; no markdown checkbox board.
+- **Scripts solve, don't punt** — Error handling explicit, no raw exceptions for Claude to figure out.
   > "Handle error conditions rather than punting to Claude."
-- [ ] **No voodoo constants** — Every magic number has a documented justification.
-  > "Configuration parameters should be justified and documented."
-- [ ] **Execute vs read intent clear** — "Run script.py" (execute) vs "See script.py for algorithm" (read).
+- **Execute vs read intent clear** — "Run script.py" (execute) vs "See script.py for algorithm" (read).
   > "Make clear in your instructions whether Claude should execute the script or read it as reference."
-- [ ] **Dependencies listed** — Required packages stated, verified as available.
+- **Dependencies listed** — Required packages stated, verified as available (N/A when no scripts).
   > "List required packages in your SKILL.md and verify they're available."
-- [ ] **MCP tools fully qualified** — `ServerName:tool_name` format.
+- **MCP tools fully qualified** — `ServerName:tool_name` format when MCP tools appear.
   > "Always use fully qualified tool names to avoid 'tool not found' errors."
-- [ ] **Plan-validate-execute for high-stakes ops** — Verifiable intermediate outputs before destructive actions.
+- **Plan-validate-execute for high-stakes ops** — Verifiable intermediate outputs before destructive actions (N/A when no high-stakes ops).
   > "Catches errors early: validation finds problems before changes are applied."
 
 ## Setup and memory (if applicable)
 
-- [ ] **Setup instructions clear** — config.json pattern or AskUserQuestion for initial context.
+- **Setup instructions clear** — config.json pattern or AskUserQuestion for initial context.
   > "If the config is not set up, the agent can then ask the user for information."
-- [ ] **Persistent data uses `${CLAUDE_PLUGIN_DATA}`** — Not stored in skill directory itself.
+- **Persistent data uses `${CLAUDE_PLUGIN_DATA}`** — Not stored in skill directory itself.
   > "Data stored in the skill directory may be deleted when you upgrade the skill."
 
 ## Modularity and composition
 
 Mandatory for every skill. Spec: `skill-modularity.md`. Progressive disclosure (file split) does not satisfy these items.
 
-- [ ] **Single capability boundary** — One clear job in one sentence. Unrelated jobs are separate skills or an orchestrator that only routes to named sub-skills.
+- **Single capability boundary** — One clear job in one sentence. Unrelated jobs are separate skills or an orchestrator that only routes to named sub-skills.
   > "The best skills fit cleanly into one; the more confusing ones straddle several."
-- [ ] **Compose before reimplement** — Steps an existing skill already owns are invoked by name, not pasted into this package. Local reimplementation has a one-line why in the gap analysis or gotchas.
+- **Compose before reimplement** — Steps an existing skill already owns are invoked by name, not pasted into this package. Local reimplementation has a one-line why in the gap analysis or gotchas.
   > "You can just reference other skills by name, and the model will invoke them if they are installed."
-- [ ] **Sub-skills table (when composing)** — Each invoked skill lists when to call it, what it produces, and missing-install behavior. N/A only when the skill is a pure leaf (invokes no peers).
+- **Sub-skills table (when composing)** — Each invoked skill lists when to call it, what it produces, and missing-install behavior. N/A only when the skill is a pure leaf (invokes no peers).
   > "You may want to have skills that depend on each other."
-- [ ] **Sibling boundary clear** — Description and when-this-applies distinguish this skill from related skills in the same domain. No silent overlap.
+- **Sibling boundary clear** — Description and when-this-applies distinguish this skill from related skills in the same domain. No silent overlap.
   > "The description field is not a summary — it's a description of when to trigger."
-- [ ] **No monolith packing** — Multi-capability content is not stuffed under one description. Either split packages or thin orchestrator + peer sub-skills (not nested fake skills under `workflows/`).
+- **No monolith packing** — Multi-capability content is not stuffed under one description. Either split packages or thin orchestrator + peer sub-skills (not nested fake skills under `workflows/`).
   > skill-modularity.md — anti-patterns: monolith, silent reimplementation, folder nesting as composition.
 
 ## Hooks (if applicable)
 
-- [ ] **Hooks declared** — If skill registers hooks, their purpose and scope is stated.
+- **Hooks declared** — If skill registers hooks, their purpose and scope is stated.
   > "Skills can include hooks that are only activated when the skill is called."
 
 ---
 
 ## Usage
 
-Copy this checklist into your response after building. Check off each item. Any item that fails → fix before delivering. Any item marked "if applicable" that doesn't apply → mark N/A with a one-line reason. Sub-skills table may be N/A for pure leaf skills; single capability boundary and no-monolith never are.
+1. Register every bullet in this file as a session task (batch create is fine).
+2. Work only from the task list. Mark complete with PASS, FAIL+file:line+fix, or N/A+one-line reason.
+3. Any FAIL must be fixed before delivery; re-open a task if the fix needs re-check.
+4. Sub-skills table may be N/A for pure leaf skills; single capability boundary and no-monolith never are. Process-step classification and "deterministic steps are not prose-only" never are N/A — pure-judgment skills still inventory steps and mark each as judgment.
+5. Deliver a short audit summary (counts of PASS / N/A / FAIL fixed) — not a markdown checkbox dump.
+

package/skills/skill-builder/references/skill-modularity.md

@@ -100,14 +100,13 @@ Self-audit requires this table (or equivalent) whenever the skill composes other
 - **Vague dependency** — "use other skills as needed" with no names, when, or outputs.
 - **Redundant twin** — a new skill whose description overlaps an existing one without a refusal boundary.
 
-## Checklist for authors
+## Task seeds for authors
 
-Copy into the response during new-skill Gather and improve Diagnose:
+Register each item as a session task during new-skill Gather and improve Diagnose (`TaskCreate` / `TodoWrite`). Complete with evidence. Do not track as markdown checkboxes.
+
+- Capability fits one sentence without an unrelated "and"
+- Related skills scanned; inventory written
+- Reusable steps map to named skills (or justify local procedure)
+- Multi-capability work is split or is an orchestrator with sub-skills
+- SKILL.md will name each sub-skill with when + produces + missing behavior
 
-```
-- [ ] Capability fits one sentence without an unrelated "and"
-- [ ] Related skills scanned; inventory written
-- [ ] Reusable steps map to named skills (or justify local procedure)
-- [ ] Multi-capability work is split or is an orchestrator with sub-skills
-- [ ] SKILL.md will name each sub-skill with when + produces + missing behavior
-```

package/skills/skill-builder/templates/CLAUDE.md

@@ -6,9 +6,9 @@ Reusable templates for skill-building artifacts.
 
 | File | Purpose |
 |---|---|
-| `gap-analysis.md` | Template for gaps, composition plan, and description triggers. Used in new-skill Gather and improve diagnosis. |
+| `gap-analysis.md` | Template for gaps, composition plan, description triggers, and deterministic-elements inventory. Used in new-skill Gather and improve diagnosis. |
 
 ## Conventions
 
 - Fill the template inline during the workflow; do not commit completed gap analyses to this directory.
-- Composition plan and Description triggers sections are required before Write on a new skill.
+- Composition plan, Description triggers, and Deterministic Elements Inventory sections are required before Write on a new skill.

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

@@ -36,6 +36,21 @@ description: >-
   <stem>. Triggers: <phrases>.
 ```
 
+## Deterministic Elements Inventory
+
+See `references/deterministic-elements.md`. Required before Write.
+
+| Step | Class (`deterministic` / `judgment` / `borderline`) | Home path | Evidence (one line) | Paired test (if code) |
+|---|---|---|---|---|
+| [step name] | [class] | [`scripts/…` / `workflow/…` / `templates/…` / `reference/…` / `SKILL.md`] | [why this class] | [`test_…` / N/A + reason] |
+
+Rules:
+
+- Every `deterministic` row has a real path under `scripts/`, `workflow/`, `templates/`, `reference/`, or `task-seed:…` — not prose-only.
+- Every code path has a paired test path (or a one-line pure-data reason).
+- Every required multi-step work list uses `task-seed:…` plus a body seed instruction (no markdown `- [ ]` board).
+- A `borderline` row kept in prose has a one-line why it stays in the body.
+
 ## Gaps Identified
 
 ### Gap 1: [Descriptive Name]

package/skills/skill-builder/workflows/CLAUDE.md

@@ -6,14 +6,14 @@ Step-by-step workflow files for each skill lifecycle phase, loaded on demand by
 
 | File | Purpose |
 |---|---|
-| `new-skill.md` | Full lifecycle: classify, scaffold, gather (composition + description triggers), write via skill-writer, self-audit, deliver. |
-| `improve-skill.md` | Observation-first improve: diagnose activation/modularity/quality, targeted fix, re-audit. |
-| `polish-skill.md` | Description trigger-catalog audit, progressive disclosure + modularity audit, checklist sign-off. |
+| `new-skill.md` | Full lifecycle: classify, scaffold, gather (composition + description triggers + deterministic inventory), write via skill-writer, self-audit, deliver. |
+| `improve-skill.md` | Observation-first improve: diagnose activation/modularity/quality/deterministic prose, targeted fix, re-audit. |
+| `polish-skill.md` | Description trigger-catalog audit; progressive disclosure + modularity + deterministic audit; task-seeded self-audit. |
 
 ## Conventions
 
 - `SKILL.md` routes to exactly one workflow file per invocation based on the user's intent (new / improve / polish).
 - Each workflow references `../references/self-audit-checklist.md` at its final verification step.
-- New and improve load `skill-modularity.md` and `description-field.md` when gathering or diagnosing.
-- Polish Step 1 is the dedicated description rewrite pass.
+- New and improve load `skill-modularity.md`, `description-field.md`, and `deterministic-elements.md` when gathering or diagnosing.
+- Polish Step 1 is the dedicated description rewrite pass; Step 2 covers structure, modularity, and deterministic placement.
 - Load only the workflow that matches the active task; the other two stay out of context.

package/skills/skill-builder/workflows/improve-skill.md

@@ -52,10 +52,16 @@ Failure classification:
 | Claude over-explains basics | Skill states what Claude already knows | Principles: Concision |
 | Claude follows instructions too rigidly | Skill railroads instead of guiding | Principles: Degree of freedom |
 | Claude makes same mistake repeatedly | Missing gotcha | Principles: Gotchas |
-| Claude errors on script execution | Script doesn’t handle errors, missing deps | Principles: Scripts |
+| Claude errors on script execution | Script doesn’t handle errors, missing deps | Principles: Scripts + `deterministic-elements.md` CODE_RULES bar |
 | Output format is wrong | Missing template or examples | Principles: Templates and examples |
+| Mechanical sequence only in markdown | Deterministic work left as prose | `deterministic-elements.md` — extract to scripts/workflow |
+| Detection/validation is a giant one-liner in body | Executable logic not in `scripts/` | `deterministic-elements.md` |
+| Fenced Python/JS in SKILL.md is the real implementation | Code not shipped as a file | Extract to `scripts/` or `workflow/` + paired test |
+| Script has magic literals / no tests | CODE_RULES bar missed | `deterministic-elements.md` + CODE_RULES |
+| Skill uses `- [ ]` for agent progress | Work list not on task tool | Task-seed catalog + seed instruction (`deterministic-elements.md`) |
+| "Copy checklist into response" protocol | Markdown as tracker | Switch to TaskCreate / TodoWrite seeding |
 
-When scope or activation is in play, re-read `${CLAUDE_SKILL_DIR}/references/skill-modularity.md` and `${CLAUDE_SKILL_DIR}/references/description-field.md`.
+When scope, activation, or deterministic placement is in play, re-read `${CLAUDE_SKILL_DIR}/references/skill-modularity.md`, `${CLAUDE_SKILL_DIR}/references/description-field.md`, and `${CLAUDE_SKILL_DIR}/references/deterministic-elements.md`.
 
 **Output:** Diagnosis per failure — which best practice was violated.
 
@@ -69,11 +75,13 @@ When scope or activation is in play, re-read `${CLAUDE_SKILL_DIR}/references/ski
 
 For each diagnosis from Step 2:
 
-1. Read the matching reference (`description-field.md`, `skill-modularity.md`, `progressive-disclosure.md`, or SKILL.md principles).
+1. Read the matching reference (`description-field.md`, `skill-modularity.md`, `deterministic-elements.md`, `progressive-disclosure.md`, or SKILL.md principles).
 2. Make the minimum change that addresses the failure.
 3. For description failures: rewrite frontmatter into a trigger catalog (capability stem + Triggers list); strip story prose.
 4. For modularity failures: add sub-skills table, split packages, or thin the orchestrator; do not paste peer skill procedures.
-5. Verify the fix doesn’t break anything that was working.
+5. For deterministic failures: extract mechanical work to `scripts/` / `workflow/` / `templates/` / `reference/`; body only points and handles exit codes; apply CODE_RULES + paired tests to new code.
+6. For checkbox/tracker failures: replace markdown `- [ ]` boards with a plain task-seed list and a seed instruction (`TaskCreate` / `TodoWrite`).
+7. Verify the fix doesn’t break anything that was working.
 
 Delegate larger rewrites to `/skill-writer` using the refine-skill handoff from delegation-map.md.
 
@@ -104,10 +112,10 @@ For each failure observed in Step 1:
 Same process as new-skill Step 5:
 
 1. Read `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`.
-2. Check every item. Fix failures. Re-check.
+2. Register every bullet as a session task; complete with evidence. Fix failures. Re-complete those tasks.
 3. Pay special attention to items that overlap with the diagnosis from Step 2 — those were the failures; confirm they’re now fixed.
 
-**Output:** Completed checklist, all PASS or N/A.
+**Output:** Audit summary; all PASS or N/A.
 
 ---
 
@@ -122,6 +130,7 @@ Present to the user:
 3. **What changed** — delta summary (files modified, lines added/removed).
 4. **Description** — final frontmatter if rewritten (paste the trigger catalog).
 5. **Composition** — sub-skills or splits if modularity changed.
-6. **New gotchas added** — list of gotchas captured.
-7. **Audit summary** — post-fix audit results.
-8. **Suggested re-test** — a concrete task to verify the fix with Claude B.
+6. **Deterministic extracts** — scripts/workflows/templates added or moved out of prose.
+7. **New gotchas added** — list of gotchas captured.
+8. **Audit summary** — post-fix audit results.
+9. **Suggested re-test** — a concrete task to verify the fix with Claude B.