claude-dev-env 4.3.0 → 7.0.0

package/.agents/skills/skill-builder/references/description-field.md

@@ -1,111 +0,0 @@
-# Description field (trigger catalog)
-
-Source: [Anthropic — Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) (Writing effective descriptions; metadata pre-load), [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code/skills), Thariq lessons (`thariq-x-post-skills.json`).
-
-## Role
-
-At session start, **only** each skill’s `name` and `description` load into context. The body loads after selection.
-
-The description is **selection metadata**, not a summary of the skill and not process documentation. It answers: *should Claude load this skill for this user turn?*
-
-> "The description field is not a summary — it’s a description of when to trigger."
-
-> "The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills."
-
-## Hard limits
-
-| Rule | Value |
-|---|---|
-| Voice | Third person only (no I/you) |
-| Max length | 1024 characters |
-| XML | Forbidden |
-| Empty | Forbidden |
-
-## Required shape: trigger catalog
-
-Two parts, dense, no story prose:
-
-1. **Capability stem** (what) — 5–20 words of capability tokens. Fragments or semicolon-separated verbs. No motivation, no audience address, no “helps you”.
-2. **Triggers** (when) — concrete phrases, slash-commands, file types, and domain nouns the user or model might emit. Prefer a labeled `Triggers:` segment.
-
-### Canonical template
-
-```yaml
-description: >-
-  <capability tokens>. Triggers: <phrase>, <phrase>, <slash>, <filetype>, <near-miss exclusion if needed>.
-```
-
-### Good
-
-```yaml
-description: >-
-  Extract PDF text/tables; fill forms; merge docs. Triggers: PDF, .pdf, forms, document extraction, fill this form, merge PDFs.
-```
-
-```yaml
-description: >-
-  Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose sub-skills, polish description triggers. Triggers: build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity.
-```
-
-```yaml
-description: >-
-  Generate commit messages from git diffs. Triggers: commit message, write a commit, staged changes, git commit help.
-```
-
-### Bad (story / waste)
-
-```yaml
-# Narrative — burns always-on tokens, weak for matching
-description: >-
-  This skill helps you work with PDF files by guiding Claude through a careful
-  process of extraction and form filling so you get reliable results every time.
-```
-
-```yaml
-# Vague — no match surface
-description: Helps with documents
-```
-
-```yaml
-# Implementation dump — body material, not metadata
-description: >-
-  Uses pdfplumber and a five-step validate loop. See scripts/ for helpers.
-```
-
-```yaml
-# First/second person
-description: I can help you process Excel files
-description: You can use this to process Excel files
-```
-
-## Authoring steps
-
-1. List **capability tokens** (what the skill owns in one breath).
-2. List **10+ user phrasings** that should select this skill (formal, casual, slash, file-type).
-3. List **near-misses** that must *not* select it (sibling skills). Fold only the shortest distinguishing tokens into Triggers if needed.
-4. Assemble stem + `Triggers:` list. Strip adjectives, benefits, and process narrative.
-5. Count characters (≤1024). Prefer under ~400 when possible — every skill’s description is always loaded.
-6. Register the task seeds below on the session task list (`TaskCreate` / `TodoWrite`); complete each with evidence. Do not use markdown checkboxes as the tracker.
-
-## Description task seeds
-
-- Third person; no I/you
-- Capability stem present (what), ≤20 words of tokens
-- Triggers: segment (or equivalent dense when-list) with concrete phrases
-- No story prose, benefits language, or implementation steps
-- No XML; length ≤1024
-- Distinguishable from sibling skills in the same domain
-- Body holds process detail — not the description
-
-## Where process lives
-
-| Content | Location |
-|---|---|
-| When to select the skill | `description` frontmatter |
-| How to run the skill | SKILL.md body + companions |
-| Refusal / boundary narrative | When-this-applies section in body |
-| Sub-skill invocation | Body Sub-skills table (`skill-modularity.md`) |
-
-## Polish workflow
-
-`workflows/polish-skill.md` Step 1 is the dedicated description pass: rewrite any story description into a trigger catalog and re-check discovery against phrase lists.

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

@@ -1,218 +0,0 @@
-# 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/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`), 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/.agents/skills/skill-builder/references/progressive-disclosure.md

@@ -1,122 +0,0 @@
-# Progressive Disclosure
-
-Source A: [Anthropic — Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
-Source B: [Lessons from Building Claude Code](thariq-x-post-skills.json)
-
-## Core concept
-
-> Source A: "SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide."
-
-> Source A: "At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed."
-
-> Source B: "You should think of the entire file system as a form of context engineering and progressive disclosure."
-
-## Standard folder conventions
-
-Every skill is a folder. These are the standard subdirectories, each with a specific role:
-
-| Directory | Purpose | When to use |
-|---|---|---|
-| `SKILL.md` | Hub — overview, gotchas, process, file index | Always |
-| `reference/` | Deep-dive reference material loaded on demand | Domain knowledge, API surfaces, schemas |
-| `scripts/` | Executable scripts (executed, not read into context) | Deterministic operations, validators, helpers |
-| `workflows/` | Multi-step sub-workflows for different scenarios | Complex branching processes |
-| `templates/` | Output templates or file scaffolds to copy and fill | Structured output formats |
-| `assets/` | Static data files, images, config templates | Reference data, configuration |
-| `examples/` | Copy-pasteable examples and usage patterns | Library/API reference skills |
-
-> Source A: "As your Skill grows, you can bundle additional content that Claude loads only when needed."
-
-> Source B: "The simplest form of progressive disclosure is to point to other markdown files for Claude to use."
-
-## The hub pattern
-
-SKILL.md is an index, not a textbook. It tells Claude what exists and when to read it.
-
-Observed in model skills (bugteam, pr-converge), the proven layout:
-
-1. Core principle (one sentence)
-2. Gotchas (highest-signal content)
-3. When this skill applies (trigger + refusal)
-4. The Process (checklist)
-5. Skill type routing (if applicable)
-6. Principles / constraints
-7. File index (what every file does)
-8. Folder map (end of file)
-
-> Source B: "Tell Claude what files are in your skill, and it will read them at appropriate times."
-
-## Three progressive disclosure patterns
-
-### Pattern 1: High-level guide with references
-
-> Source A: "Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed."
-
-```markdown
-## Quick start
-[essential content inline]
-
-## Advanced features
-**Form filling**: See [FORMS.md](FORMS.md)
-**API reference**: See [REFERENCE.md](REFERENCE.md)
-**Examples**: See [EXAMPLES.md](EXAMPLES.md)
-```
-
-### Pattern 2: Domain-specific organization
-
-> Source A: "When a user asks about sales metrics, Claude only needs to read sales-related schemas, not finance or marketing data."
-
-```markdown
-**Finance**: Revenue, ARR → See [reference/finance.md](reference/finance.md)
-**Sales**: Pipeline, accounts → See [reference/sales.md](reference/sales.md)
-**Product**: API usage, features → See [reference/product.md](reference/product.md)
-```
-
-### Pattern 3: Conditional details
-
-> Source A: "Show basic content, link to advanced content."
-
-```markdown
-For simple edits, modify the XML directly.
-
-**For tracked changes**: See [REDLINING.md](REDLINING.md)
-**For OOXML details**: See [OOXML.md](OOXML.md)
-```
-
-## Hard rules
-
-### 500-line cap on SKILL.md body
-
-> Source A: "Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files."
-
-### One level deep
-
-> Source A: "Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md."
-
-> Source A: "Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information."
-
-**Bad:** `SKILL.md → advanced.md → details.md`
-**Good:** `SKILL.md → advanced.md`, `SKILL.md → details.md`
-
-### TOC for files over 100 lines
-
-> Source A: "For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads."
-
-### Forward slashes only
-
-> Source A: "Always use forward slashes in file paths, even on Windows. Unix-style paths work across all platforms."
-
-## File naming conventions
-
-> Source A: "Name files descriptively: Use names that indicate content: `form_validation_rules.md`, not `doc2.md`."
-
-> Source A: "Organize for discovery: Structure directories by domain or feature. Good: `reference/finance.md`, `reference/sales.md`. Bad: `docs/file1.md`, `docs/file2.md`."
-
-## Scripts: execute vs read
-
-> Source A: "Make clear in your instructions whether Claude should execute the script or read it as reference."
-
-- **Execute:** "Run `analyze_form.py` to extract fields"
-- **Read as reference:** "See `analyze_form.py` for the extraction algorithm"
-
-> Source A: "For most utility scripts, execution is preferred because it's more reliable and efficient."

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

@@ -1,126 +0,0 @@
-# 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.
-
-**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.
-  > "Default assumption: Claude is already very smart."
-- **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.
-  > "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`.
-  > "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.
-  > "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.
-  > "Be specific and include key terms."
-- **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.
-  > "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.
-  > "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.
-  > "Don't include information that will become outdated."
-- **Consistent terminology** — One term per concept throughout.
-  > "Consistency helps Claude understand and follow instructions."
-- **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.
-  > "Don't present multiple approaches unless necessary. Provide a default with escape hatch."
-- **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.
-  > "Focus on information that pushes Claude out of its normal way of thinking."
-- **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.
-  > 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.
-  > "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.
-  > "Examples help Claude understand the desired style and level of detail more clearly than descriptions alone."
-- **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.
-  > bugteam pattern — constraints file with design rationale.
-- **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.
-  > "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).
-  > Pattern 2 — domain-specific organization.
-
-## Deterministic elements
-
-Mandatory for every skill. Spec: `deterministic-elements.md`. Progressive disclosure alone does not satisfy these items.
-
-- **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."
-- **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 (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 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 (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.
-  > "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.
-  > "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.
-  > "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.
-  > "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).
-  > "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.
-  > "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/`).
-  > 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.
-  > "Skills can include hooks that are only activated when the skill is called."
-
----
-
-## Usage
-
-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.
-