@hegemonart/get-design-done 1.59.2 → 1.59.4

package/scripts/skill-templates/watch-authorities/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gdd-watch-authorities
+description: "Fetches the design-authority feed whitelist, diffs against .design/authority-snapshot.json, and writes .design/authority-report.md (consumed by {{command_prefix}}reflect). Authority monitoring only - no trend-watching."
+argument-hint: "[--refresh] [--since <date>] [--feed <name>] [--schedule <weekly|daily|monthly>]"
+tools: Read, Write, Task, Bash
+---
+
+# {{command_prefix}}watch-authorities
+
+Runs `design-authority-watcher` on demand. Fetches the curated design-authority feed whitelist, diffs against the prior snapshot, classifies new entries into five buckets, and writes `.design/authority-report.md`. Phase 11's reflector picks up the report automatically when you next run `{{command_prefix}}reflect`.
+
+Authority-monitoring only. Not trend-watching. See `reference/authority-feeds.md` §"Rejected kinds" for what this skill will never fetch.
+
+## Steps
+
+1. **Parse args.** Extract optional flags: `--refresh`, `--since <date>`, `--feed <name>`, `--schedule <cadence>`. Anything that doesn't match one of these is an error - print `Unknown flag: <arg>. Valid flags: --refresh --since <date> --feed <name> --schedule <weekly|daily|monthly>.` and STOP.
+
+   Mutual exclusion rules:
+   - `--schedule` is handled entirely by this skill - it does not combine with the other three. If `--schedule` is present alongside any of `--refresh | --since | --feed`, print `--schedule cannot combine with other flags. Schedule registration runs this skill with no flags at the configured cadence.` and STOP.
+   - `--refresh` and `--since` are mutually exclusive - print `--refresh and --since are mutually exclusive. --refresh re-seeds the snapshot silently; --since surfaces a backlog from a boundary date. Pick one.` and STOP.
+
+2. **Handle `--schedule <cadence>` branch** (early-return).
+
+   If `--schedule` is set:
+   - Validate cadence ∈ {`weekly`, `daily`, `monthly`}; else print `Unknown cadence: <value>. Use one of: weekly, daily, monthly.` and STOP.
+   - Probe for the scheduled-tasks MCP via ToolSearch:
+
+     ```
+     ToolSearch({ query: "scheduled-tasks", max_results: 3 })
+     ```
+
+   - If the probe returns an empty result set: print `scheduled-tasks MCP not connected. Install it with: claude mcp add scheduled-tasks ... then retry with --schedule.` - this is a documented fallback (not an error). Terminate with `## WATCH COMPLETE` and exit 0.
+   - If the probe returns one or more `scheduled-tasks` tools: register the cron. Discover the MCP's registration tool name at runtime from the ToolSearch result and follow its schema. Target command: `{{command_prefix}}watch-authorities` with NO flags (the cron invokes the default diff-and-report behavior). Cadence → cron expression mapping:
+     - `weekly`  → `0 9 * * 1` (Mondays 09:00 local)
+     - `daily`   → `0 9 * * *` (every day 09:00 local)
+     - `monthly` → `0 9 1 * *` (1st of each month 09:00 local)
+   - After registration: print `Scheduled {{command_prefix}}watch-authorities to run <cadence>.` and terminate with `## WATCH COMPLETE`.
+
+3. **Validate `--since <date>`** (if present).
+
+   Accept ISO8601 (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`). Sanity-check via Bash `date -d "<value>" +%s` (GNU) or the POSIX equivalent `python3 -c "from datetime import datetime; datetime.fromisoformat('<value>'.replace('Z','+00:00'))"`. On parse failure: print `Invalid --since value: <value>. Use ISO8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ).` and STOP.
+
+   If the parsed date is earlier than `2020-01-01`, ask: `Very old --since value: <value>. Did you mean something more recent? Proceed? [y/N]`. On anything other than `y`/`Y`, STOP.
+
+4. **Spawn the watcher.**
+
+   Build the `Task(subagent_type="design-authority-watcher", ...)` prompt. The prompt supplies the agent's required-reading block (watcher step 0), echoes the invocation flags verbatim (watcher Flags section), and instructs the agent to follow its own fetch/diff/classify/write loop:
+
+   ```
+   Task("design-authority-watcher", """
+   <required_reading>
+   @reference/authority-feeds.md
+   @.design/authority-snapshot.json
+   @.design/STATE.md
+   </required_reading>
+
+   Invocation flags: <joined flag list or "none">
+
+   Fetch the feeds listed in reference/authority-feeds.md, diff against .design/authority-snapshot.json,
+   classify new entries per the D-17 decision table, write .design/authority-snapshot.json and
+   .design/authority-report.md.
+
+   Terminate with ## WATCH COMPLETE.
+   """)
+   ```
+
+   `<joined flag list>` is the subset of `--refresh | --since <date> | --feed <name>` actually passed - e.g., `--refresh`, `--since 2026-03-01`, `--feed wai-aria-apg`, `--refresh --feed radix-ui-releases`, or literally `none` when no flags were supplied.
+
+5. **Print summary.**
+
+   After the agent returns:
+   - If STATE.md gained a `<blocker type="contract-violation">` on this run (snapshot version mismatch, hash-format violation, or over-200 entries per feed), surface the blocker verbatim and stop - do not print the default "review and reflect" line.
+   - Otherwise print the agent's one-line stdout summary (normal mode: `Surfaced N entries across M feeds. K skipped. See .design/authority-report.md.`; first-run / refresh mode: `Seeded snapshot for N feeds — next run will surface new entries.`) followed by: `Review and reflect: {{command_prefix}}reflect`.
+
+6. **Terminate with `## WATCH COMPLETE`.**
+
+## Do Not
+
+- Do not modify `agents/design-authority-watcher.md`.
+- Do not modify `agents/design-reflector.md` - Phase 13.2 does not touch the reflector agent (CONTEXT.md D-25).
+- Do not write to `.design/authority-snapshot.json` or `.design/authority-report.md` directly - those are the agent's writes.
+- Do not fetch URLs outside `reference/authority-feeds.md`. The whitelist is the allow-list.

package/scripts/skill-templates/zoom-out/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: zoom-out
+description: "Asks the agent to go up a layer of abstraction and map the relevant modules and callers using the project's CONTEXT.md vocabulary. Use when the user is working in an unfamiliar area of code and needs orientation before deep work."
+disable-model-invocation: true
+argument-hint: "[scope]"
+---
+
+Source: mattpocock/skills (MIT) - adapted with permission. See `../NOTICE` for the full attribution block.
+
+# Zoom Out
+
+**Role:** Give the user a map, not a fix.
+
+I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary (`CONTEXT.md`) vocabulary.
+
+When invoked, produce a one-screen map that names:
+
+1. **Modules in scope** - one-line description of each, using terms from `CONTEXT.md` (see `./../reference/context-md-format.md` for the schema). Do not invent terms.
+2. **Callers** - who calls these modules from elsewhere, with file paths.
+3. **Seams** - where data crosses module boundaries, named per `./../reference/architecture-vocabulary.md`.
+
+Do not propose fixes. Do not write code. The output is a map.
+
+If `CONTEXT.md` is absent, suggest `{{command_prefix}}discuss` to start one, but still produce the map using basenames and inferred terms.
+
+## ZOOM-OUT COMPLETE

package/sdk/cli/commands/build.ts

@@ -1,7 +1,7 @@
 // sdk/cli/commands/build.ts — Phase 42 (COMPILE-06).
 //
 // `gdd-sdk build skills [--harness <id>] [--zip] [--check]` — compile the per-harness skill bundles
-// from skill-templates/ via the orchestrator scripts/build-skills.cjs. The orchestrator is a separate
+// from scripts/skill-templates/ via the orchestrator scripts/build-skills.cjs. The orchestrator is a separate
 // dep-free CJS process (no bundling entanglement with the SDK); we resolve it relative to the package
 // root and spawn it, forwarding stdout/stderr.
 //
@@ -30,7 +30,7 @@ const BUILD_FLAGS: readonly FlagSpec[] = [
 
 export const BUILD_USAGE = `gdd-sdk build skills [flags]
 
-Compile per-harness skill bundles from skill-templates/ into dist/<bundle>/ (and regenerate the
+Compile per-harness skill bundles from scripts/skill-templates/ into dist/<bundle>/ (and regenerate the
 committed Claude-Code surface skills/). One source, N provider bundles.
 
 Flags:

package/sdk/cli/index.js

@@ -9664,7 +9664,7 @@ var BUILD_FLAGS = [
 ];
 var BUILD_USAGE = `gdd-sdk build skills [flags]
 
-Compile per-harness skill bundles from skill-templates/ into dist/<bundle>/ (and regenerate the
+Compile per-harness skill bundles from scripts/skill-templates/ into dist/<bundle>/ (and regenerate the
 committed Claude-Code surface skills/). One source, N provider bundles.
 
 Flags:
@@ -9984,7 +9984,7 @@ Commands:
   query <op>       Typed STATE.md read operations.
   audit            Probe connections + dry-run verify.
   init             Bootstrap a new project.
-  build skills     Compile per-harness skill bundles from skill-templates/.
+  build skills     Compile per-harness skill bundles from scripts/skill-templates/.
   dashboard        Open the GDD dashboard (TUI; --web for the browser graph).
 
 Use 'gdd-sdk <command> -h' for command-specific flags.

package/sdk/cli/index.ts

@@ -36,7 +36,7 @@ Commands:
   query <op>       Typed STATE.md read operations.
   audit            Probe connections + dry-run verify.
   init             Bootstrap a new project.
-  build skills     Compile per-harness skill bundles from skill-templates/.
+  build skills     Compile per-harness skill bundles from scripts/skill-templates/.
   dashboard        Open the GDD dashboard (TUI; --web for the browser graph).
 
 Use 'gdd-sdk <command> -h' for command-specific flags.

package/skills/README.md

@@ -1,14 +1,21 @@
-# `skill-templates/` - Editable Skill Source (Single Source of Truth)
+# `scripts/skill-templates/` - Editable Skill Source (Single Source of Truth)
 
 This directory is the **only** place to edit skill content. Every `SKILL.md` and sibling
 doc here is the editable truth - the per-skill prose, examples, procedure files
 (`*-procedure.md`, `*-rules.md`, emitters, etc.) all live here.
 
 The user-facing `skills/` directory at the repo root is a **build artifact**, not source.
-It's gitignored and regenerated automatically:
+It is **committed** (since v1.58.1, NOT gitignored) and regenerated from this directory:
 
-- on `npm install` (via the `prepare` lifecycle script) - so developer clones work immediately
+- on `npm install` (via the `prepare` lifecycle script) - so contributor clones rebuild it from source
 - on `npm pack` / `npm publish` (via `prepack`) - so the published tarball ships pre-built skills
+- on demand via `node scripts/build-skills.cjs`, with the `build:skills:check` drift gate (CI)
+  failing the build whenever the committed `skills/` no longer matches `scripts/skill-templates/`
+
+It stays in git because the Claude Code marketplace install path git-clones the plugin
+**without** running `npm install`, so `./skills/` must already exist post-clone. v1.58.0
+briefly gitignored it and broke that path; v1.58.1 restored it as a committed, drift-gated
+build output.
 
 End users installing `@hegemonart/get-design-done` from the npm registry receive a tarball
 with `skills/` already built; no build step runs on their machine.
@@ -23,32 +30,33 @@ The previous layout (Phase 42) put templates under `source/skills/` AND committe
 rendered `skills/` alongside. That meant 232 tracked files for 116 distinct skills with
 identical content modulo a single placeholder substitution. Pure git churn.
 
-v1.58.0 fixes this: templates are tracked once at `skill-templates/`, the rendered output
+v1.58.0 fixes this: templates are tracked once at `scripts/skill-templates/`, the rendered output
 is generated on demand.
 
 ## Source-of-truth split (what lives where)
 
 | Concern | Source of truth | How it reaches `skills/` |
 |---|---|---|
-| **Body content** (everything below the frontmatter) | `skill-templates/<slug>/SKILL.md` | `scripts/build-skills.cjs` walks `skill-templates/`, applies per-harness placeholder substitution, writes to `skills/` |
-| **Universal frontmatter** (`name`, `description`, `argument-hint`, `tools`, `user-invocable`, `disable-model-invocation`) | `scripts/lib/manifest/skills.json` | `scripts/generate-skill-frontmatter.cjs` writes the managed block into `skill-templates/<slug>/SKILL.md`, then `build:skills` copies it onward |
-| **Non-managed frontmatter** (e.g. `color`, `model`, custom keys) | `skill-templates/<slug>/SKILL.md` itself (preserved verbatim) | carried through both generators unchanged |
+| **Body content** (everything below the frontmatter) | `scripts/skill-templates/<slug>/SKILL.md` | `scripts/build-skills.cjs` walks `scripts/skill-templates/`, applies per-harness placeholder substitution, writes to `skills/` |
+| **Universal frontmatter** (`name`, `description`, `argument-hint`, `tools`, `user-invocable`, `disable-model-invocation`) | `scripts/lib/manifest/skills.json` | `scripts/generate-skill-frontmatter.cjs` writes the managed block into `scripts/skill-templates/<slug>/SKILL.md`, then `build:skills` copies it onward |
+| **Non-managed frontmatter** (e.g. `color`, `model`, custom keys) | `scripts/skill-templates/<slug>/SKILL.md` itself (preserved verbatim) | carried through both generators unchanged |
 
-The forward direction is **`skills.json` -> `skill-templates/` -> `skills/`**.
+The forward direction is **`skills.json` -> `scripts/skill-templates/` -> `skills/`**.
 Treat that direction as canonical; the `--extract` mode of `generate-skill-frontmatter.cjs` exists
 only to seed the manifest from current sources when reconciling drift.
 
 ## Editing protocol
 
-1. **Edit body** -> modify `skill-templates/<slug>/SKILL.md` (anything below the frontmatter delimiter).
+1. **Edit body** -> modify `scripts/skill-templates/<slug>/SKILL.md` (anything below the frontmatter delimiter).
 2. **Edit universal frontmatter** -> modify `scripts/lib/manifest/skills.json`, then run
    `npm run generate:skill-frontmatter`.
-3. **Edit non-managed frontmatter** -> modify `skill-templates/<slug>/SKILL.md` directly; the generator
+3. **Edit non-managed frontmatter** -> modify `scripts/skill-templates/<slug>/SKILL.md` directly; the generator
    preserves it.
-4. **Regenerate the built surface** -> `npm run build:skills`. This rewrites the gitignored
-   `skills/<slug>/SKILL.md` byte-for-byte from the templates.
+4. **Regenerate the built surface** -> `npm run build:skills`. This rewrites the committed
+   `skills/<slug>/SKILL.md` byte-for-byte from the templates; commit the regenerated `skills/`
+   alongside your template edit so the `build:skills:check` drift gate stays green.
 5. **Verify the build** -> `npm run build:skills:check` (CI gate) confirms compile determinism
-   and that the on-disk `skills/` matches what `skill-templates/` would generate.
+   and that the on-disk `skills/` matches what `scripts/skill-templates/` would generate.
 
 ## Placeholders
 
@@ -68,7 +76,7 @@ Full grammar + the per-harness substitution table: `reference/skill-placeholders
 
 ## What npm ships
 
-`package.json` `files` lists `skills/` (the built surface); `skill-templates/` is repo-only and
+`package.json` `files` lists `skills/` (the built surface); `scripts/skill-templates/` is repo-only and
 is **not** distributed via npm. The `prepack` lifecycle runs `npm run build:skills` so the tarball
 always contains a freshly-built `skills/`.
 

package/skills/help/SKILL.md

@@ -7,73 +7,46 @@ disable-model-invocation: true
 
 # Get Design Done - Help
 
-**Role:** Print a formatted reference of all `/gdd:` commands, grouped by purpose.
+**Role:** Print a complete, formatted reference of every `/gdd:` command with a one-line description. The list is built from the skill manifest at runtime so it can never drift from the installed skills.
 
 ---
 
-## Output
+## Procedure
 
-Print the following table:
+1. **Read the manifest.** Open `scripts/lib/manifest/skills.json`. Its `skills` array is the source of truth: one object per skill, each with a `name` (the command, used as `/gdd:<name>`) and a `description`. Some records also carry `user_invocable`, `disable_model_invocation`, `composes_with`, `next_skills`, and `registered_in_phase` - use those only to refine grouping, never to drop a skill.
+
+2. **Cover every skill.** The output must include every object in `skills` exactly once. Do not hardcode a command list and do not print a fixed count - the only authority is the manifest you just read. If a skill is in the manifest, it appears in the help; if it is removed from the manifest, it disappears from the help automatically.
+
+3. **One-line each.** For every skill, emit `/gdd:<name>` followed by a single condensed line drawn from its `description`. Trim each description to its first sentence (cut at the first sentence-ending period) so the table stays scannable. Strip any leading "Stage N of 5" boilerplate into a short `Stage N` tag where it helps. Never invent a description - if a record has only a terse `description`, use it verbatim (condensed).
+
+4. **Group sensibly.** The manifest has no explicit category field, so derive groups from what each skill does and lead with the ones users reach for first. A good order:
+   - **Pipeline stages (run in order):** `brief`, `explore`, `plan`, `design`, `verify` - the five-stage spine, in that sequence.
+   - **Standalone analysis:** one-shot audits and deltas (for example `style`, `darkmode`, `compare`, `audit`, `start`).
+   - **Navigation and status:** `next`, `help`, `progress`, `health`, `stats`, `quick`, `fast`.
+   - **Exploration and ideation:** `discuss`, `list-assumptions`, `sketch`, `sketch-wrap-up`, `spike`, `spike-wrap-up`, `map`, `bootstrap-ds`.
+   - **Lifecycle and session:** `new-project`, `new-cycle`, `complete-cycle`, `pause`, `resume`, `continue`, `do`, `ship`, `pr-branch`, `undo`.
+   - **Everything else:** every remaining skill not yet listed, alphabetically. This catch-all is what guarantees completeness - sweep the manifest for any `name` you have not already printed and place it here.
+
+   Grouping is a presentation aid, not a filter. If you are ever unsure where a skill belongs, fall back to a single alphabetical list of all manifest skills - completeness beats tidy buckets.
+
+5. **Render.** Use this header and shape (a fenced reference block):
 
 ```
-━━━ Get Design Done — Command Reference ━━━
+=== Get Design Done - Command Reference ===
 
 Pipeline stages (run in order):
-  brief              Stage 1 — capture problem statement, audience, constraints → BRIEF.md
-  explore            Stage 2 — inventory scan + design context interview → DESIGN.md, DESIGN-DEBT.md, DESIGN-CONTEXT.md
-  plan               Stage 3 — decompose into executable tasks → DESIGN-PLAN.md
-  design             Stage 4 — execute tasks with wave coordination → DESIGN-SUMMARY.md
-  verify             Stage 5 — audit, verify, score → DESIGN-VERIFICATION.md
+  brief              <first sentence of brief.description>
+  explore            <first sentence of explore.description>
+  ...
 
 Standalone analysis:
-  style [Component]  Generate component handoff doc → DESIGN-STYLE-[Name].md
-  darkmode           Audit dark mode architecture + contrast → DARKMODE-AUDIT.md
-  compare            Delta between baseline and verification → COMPARE-REPORT.md
-
-Ergonomics:
-  next               Route to the next pipeline stage based on STATE.md
-  help               This reference
-  progress           Show current pipeline state
-  health             Health check of .design/ artifacts
-  quick              Fast pass through the whole pipeline
-  fast               Aggressive speed mode
-
-Exploration:
-  discuss            Open discussion thread with design-discussant agent
-  list-assumptions   Print active D-XX decisions from STATE.md
-  sketch             Open a design sketch scratchpad
-  sketch-wrap-up     Close sketch and merge learnings
-  spike              Time-boxed exploratory spike
-  spike-wrap-up      Close spike and capture outcomes
-  map                Map the codebase structure
-  audit              Run audit-only pass
-
-Maintenance:
-  note               Record a quick note to STATE.md
-  plant-seed         Record an idea for later
-  add-backlog        Append item to backlog
-  review-backlog     Review pending backlog
-  todo               List/manage design TODOs
-  stats              Print pipeline stats
-  settings           View/edit plugin settings
-  update             Update the plugin
-  reapply-patches    Reapply any pending patches
-  debug              Enter systematic debugging mode
-  undo               Revert the last stage action
-
-Lifecycle:
-  new-project        Initialize STATE.md + .design/ directory
-  new-cycle          Start a new design cycle on an existing project
-  complete-cycle     Archive the current cycle
-  pause              Pause work and save context
-  resume             Resume paused work
-  do                 Execute a specific task
-  ship               Create PR from completed work
-  pr-branch          Create/switch PR branch
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ...
+
+(continue for every group, ending with the alphabetical catch-all)
 ```
 
+   Pad command names to a consistent column so descriptions align. Keep the `/gdd:` convention: show the bare name in the table (it is already understood to be a `/gdd:` command), and use the full `/gdd:<name>` form in any surrounding prose.
+
 ## Update notice (safe-window surface)
 
 After the command reference, emit the plugin-update banner if one is present:

package/skills/new-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-new-skill
-description: "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes skill-templates/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command."
+description: "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes scripts/skill-templates/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command."
 argument-hint: "<skill-name>"
 tools: Read, Write, Bash, AskUserQuestion
 user-invocable: true
@@ -8,7 +8,7 @@ user-invocable: true
 
 # /gdd:new-skill
 
-**Role:** Interactively scaffold a contract-compliant skill. Gather the fields, then write `skill-templates/<name>/SKILL.md` from the pure generator at `scripts/lib/manifest/scaffolder.cjs`. This skill writes ONE source file. It does NOT touch `scripts/lib/manifest/skills.json` and does NOT run the build; it prints the exact follow-up commands instead.
+**Role:** Interactively scaffold a contract-compliant skill. Gather the fields, then write `scripts/skill-templates/<name>/SKILL.md` from the pure generator at `scripts/lib/manifest/scaffolder.cjs`. This skill writes ONE source file. It does NOT touch `scripts/lib/manifest/skills.json` and does NOT run the build; it prints the exact follow-up commands instead.
 
 Read `reference/skill-authoring-contract.md` first for the length cap, the frontmatter required fields, and the v3 description form.
 
@@ -27,7 +27,7 @@ Either way the answers feed the same record builder. Never block waiting on a TT
 
 ## Step 1 - Gather the fields
 
-1. **name**: the slug from `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. Reject `skill-templates/<name>/` collisions.
+1. **name**: the slug from `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. Reject `scripts/skill-templates/<name>/` collisions.
 2. **description**: a multi-paragraph v3 form. Sentence one is what the skill does. Sentence two is `Use when <triggers>`. Sentence three is `Activates for requests involving <kw1>, <kw2>, <kw3>.` Keep it 20 to 1024 chars.
 3. **lifecycle stage**: pick one of brief / explore / plan / verify / ship / figma / token / report (free text allowed). This seeds the composition suggestions.
 4. **tools**: a comma list (for example `Read, Write, Bash`). Empty means inherit-all.
@@ -45,7 +45,7 @@ Present the suggestions; let the user accept, edit, or clear them.
 
 ## Step 2 - Length pre-check
 
-Before writing, estimate the body length. If the planned body would exceed about 100 lines, warn the user (the authoring contract warns at 100 and blocks at 250) and suggest extracting domain content into a co-located `skill-templates/<name>/<topic>.md` reference. The generated skeleton is small; the warning is for the prose the user will add next.
+Before writing, estimate the body length. If the planned body would exceed about 100 lines, warn the user (the authoring contract warns at 100 and blocks at 250) and suggest extracting domain content into a co-located `scripts/skill-templates/<name>/<topic>.md` reference. The generated skeleton is small; the warning is for the prose the user will add next.
 
 ## Step 3 - Write the file
 
@@ -66,7 +66,7 @@ process.stdout.write(s.renderSkillMd(rec));
 "
 ```
 
-`buildSkillRecord` throws on an invalid name, an out-of-budget description, or a malformed tools list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to `skill-templates/<name>/SKILL.md` via the Write tool.
+`buildSkillRecord` throws on an invalid name, an out-of-budget description, or a malformed tools list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to `scripts/skill-templates/<name>/SKILL.md` via the Write tool.
 
 ## Step 4 - Tell the user the follow-up