@vegastack/skills 0.6.0 → 0.7.0

package/skill/skill-maintainer/SKILL.md

@@ -9,7 +9,7 @@ Maintenance skill for this repository. Every change under `skills/` must satisfy
 
 ## Operating rules
 
-1. Skill content lives only in `skills/<name>/`. Wiring lives outside it: the packaging allowlist in `packages/cli/scripts/sync-skill.mjs`, the root `README.md` skills table, and `CHANGELOG.md` (via changesets).
+1. Skill content lives only in `skills/<name>/`. Wiring lives outside it: the per-skill packaging allowlist in `packages/cli/packaging.json`, the root `README.md` skills table, and `CHANGELOG.md` (via changesets). The skillify scaffolder writes all three when creating a skill.
 2. Frontmatter is exactly two keys: `name` and `description`. The open spec also allows `license`, `compatibility`, and `metadata`, but this repo defaults to the minimal two; adding any other key is a policy exception needing maintainer sign-off.
 3. `name` must equal the directory name. Grammar: starts with a lowercase letter, then only lowercase letters, digits, and hyphens; no leading/trailing hyphen, no consecutive hyphens; at most 64 chars.
 4. `description`: at most 1024 chars, third person, states WHAT the skill does and WHEN to load it, trigger words front-loaded, no angle brackets. Never summarize the workflow in it — agents follow the summary and skip the body. Err slightly pushy: agents under-trigger.
@@ -23,29 +23,28 @@ Maintenance skill for this repository. Every change under `skills/` must satisfy
 | Need | Read |
 |---|---|
 | tri-harness standards: discovery paths, frontmatter rules, context budgets, install surfaces, portability rules, unverified items | [standards](references/standards.md) |
+| new skill: should-it-exist gate, scaffolding, the 8-item contract audit, behavioral evals | the `skillify` skill |
 | release, rename, deprecate, rollback mechanics | [release ops](references/release-ops.md) |
 | this skill's own freshness contract | [REFRESH](refresh/REFRESH.md), [sources](refresh/sources.json) |
 | authoritative repo policy | `CONTRIBUTING.md`, `docs/policies/content-versioning.md`, `docs/policies/release-and-rollback.md` at the repo root |
 
 ## Workflow: scaffold a new skill
 
-1. Create `skills/<name>/` with the full per-skill contract: `SKILL.md` (agent entry), `README.md` (repo-side walkthrough, never packaged), `references/`, `tests/` (bun tests, never packaged), `refresh/sources.json` + `refresh/REFRESH.md` (freshness contract), `agents/openai.yaml` (Codex interface metadata); `scripts/` and `assets/` only if the skill needs them.
-2. Write frontmatter and body per operating rules 2–6; the body routes to references, it does not inline them.
-3. Wire it in: add every packaged file to the allowlist in `packages/cli/scripts/sync-skill.mjs` (the build fails loudly on unlisted files); add a row to the root README skills table; add a changeset (a new skill is MINOR).
-4. The installer is multi-skill: every authored skill needs a packaging allowlist entry in packages/cli/scripts/sync-skill.mjs (the build fails loudly on unlisted files).
-5. Seed refresh baselines with the deterministic runner, never by hand — invocation in [REFRESH](refresh/REFRESH.md).
-6. Run the checks in operating rule 8.
+1. Run skillify's `scripts/scaffold-skill.mjs` — it creates the contract tree (`SKILL.md`, `README.md`, `refresh/`, `agents/openai.yaml`, tests and the trigger fixture) and performs the repo wiring itself: the `packages/cli/packaging.json` entry, the root README row, and the changeset (a new skill is MINOR). Fill in the README row description and changeset text it leaves as TODOs; files added after scaffolding go into the skill's `packaging.json` entry by hand (the build fails loudly on unlisted files).
+2. Write frontmatter and body per operating rules 2–6; the body routes to references, it does not inline them. `skillify` owns the full authoring and eval discipline.
+3. Seed refresh baselines with the deterministic runner, never by hand — invocation in [REFRESH](refresh/REFRESH.md).
+4. Run the checks in operating rule 8.
 
 ## Workflow: update or maintain
 
-- **Stable IDs are permanent.** Never renumber or reuse a rule ID; removing or renaming one is a MAJOR content change (`docs/policies/content-versioning.md`). New rules/references are MINOR; weakening a MUST is MAJOR; factual refreshes (pins, URLs, checksums) are PATCH.
+- **Content versioning.** New rules/references and new recorded decisions are MINOR; weakening a normative rule, removing or renaming a skill, or breaking a per-project profile format is MAJOR; factual refreshes (pins, URLs, checksums) are PATCH (`docs/policies/content-versioning.md`).
 - **Tag volatile claims.** Any sentence carrying a vendor version, mechanism name, or numeric budget gets a source marker comment mapping to an ID in that skill's `refresh/sources.json`, and the registry entry's `affected` list must name the reference it lives in. Untagged volatile facts rot silently.
 - **Description budgets.** Stay within 1024 chars and keep triggers in the first sentence: Codex truncates its skill list at 2% of the context window / 8,000 chars, Claude Code truncates a skill's always-loaded listing at 1,536 chars — the tail of a long description is the first thing lost.
-- **Packaged-file changes.** Any add/remove/rename of a packaged file must update the `sync-skill.mjs` allowlist in the same PR.
+- **Packaged-file changes.** Any add/remove/rename of a packaged file must update that skill's `packages/cli/packaging.json` entry in the same PR.
 
 ## Workflow: rename, deprecate, or remove
 
-Full playbook in [release ops](references/release-ops.md). Short form: a rename changes the directory and the frontmatter `name` in the same commit (they must stay equal), updates allowlist + root README table + CHANGELOG, and is MAJOR. Deprecation is announced in README/CHANGELOG before removal. Removal deletes the tree, unwires it, and is MAJOR.
+Full playbook in [release ops](references/release-ops.md). Short form: a rename changes the directory and the frontmatter `name` in the same commit (they must stay equal), updates the packaging.json entry + root README table + CHANGELOG, and is MAJOR. Deprecation is announced in README/CHANGELOG before removal. Removal deletes the tree, unwires it, and is MAJOR.
 
 ## Workflow: release
 

package/skill/skill-maintainer/references/release-ops.md

@@ -43,7 +43,7 @@ Contributors do not bump versions in PRs; releases are maintainer-driven.
 Skill names are consumer-facing identifiers — treat a rename as a stable-ID break:
 
 1. Rename the directory and the frontmatter `name` in the same commit — they must always stay equal.
-2. Update every wiring point in the same PR: the packaging allowlist in `packages/cli/scripts/sync-skill.mjs`, the root README skills table row, and any cross-skill or docs links.
+2. Update every wiring point in the same PR: the skill's entry in `packages/cli/packaging.json`, the root README skills table row, and any cross-skill or docs links.
 3. Changeset: MAJOR. Note the migration in `CHANGELOG.md`: copies installed under the old name are orphaned, and installer operations addressed to the old name stop resolving once the shipped manifest no longer knows it.
 4. Registry source IDs inside `refresh/sources.json` are skill-internal and unaffected, but every `affected` ref must still resolve to a real reference in the renamed tree.
 5. Re-run `node packages/cli/scripts/validate-skill.mjs skills/<new-name>` and the skill's tests — name/directory equality is validated.

package/skill/skill-maintainer/refresh/REFRESH.md

@@ -5,7 +5,7 @@ Instructions for the scheduled refresh agent (and any human running a manual ref
 ## What this skill claims
 
 - **Durable content** (`SKILL.md` workflows and operating rules, `references/release-ops.md`): repo process, derived from `docs/policies/*` — the refresh agent NEVER edits these. If a policy doc changes, that is a normal human PR, not a refresh.
-- **Mechanism-coupled claims**: sentences marked `<!-- source: SOURCE-ID -->` inside `references/standards.md`. These carry the tri-harness standards — discovery paths, frontmatter rules, numeric context budgets, install surfaces. They are the compliance basis of every skill in this repo, so **all standards changes are semantic drift requiring a human-reviewed PR**: the agent may propose edits to marked sentences only, in the same PR as the registry update that evidences the change, and a maintainer must review before merge. The hard-limits table in `SKILL.md` mirrors several marked sentences; update it in the same PR (this is the one sanctioned SKILL.md touch, and only when a mirrored number changed).
+- **Volatile standards claims**: sentences marked `<!-- source: SOURCE-ID -->` inside `references/standards.md`. These carry the tri-harness standards — discovery paths, frontmatter rules, numeric context budgets, install surfaces. They are the compliance basis of every skill in this repo, so **all standards changes are semantic drift requiring a human-reviewed PR**: the agent may propose edits to marked sentences only, in the same PR as the registry update that evidences the change, and a maintainer must review before merge. The hard-limits table in `SKILL.md` mirrors several marked sentences; update it in the same PR (this is the one sanctioned SKILL.md touch, and only when a mirrored number changed).
 - **Volatile layer** (the only file the agent edits freely): `refresh/sources.json` — the source registry and staleness snapshot (checksums, retrieval times).
 
 ## How to refresh

package/skill/skillify/SKILL.md

@@ -5,27 +5,22 @@ description: Repo-local skill factory and auditor for the vegastack-skills monor
 
 # Skillify
 
-Turn a raw workflow into a properly-skilled unit of this monorepo, or audit an existing `skills/<name>/` tree against the full repo contract (CONTRIBUTING.md, "Adding a new skill"). Skillify is repo-only: it creates and scores skills in this repository, not anywhere else. Deep wiring/release mechanics belong to `skill-maintainer`; cross-reference it rather than restating it.
+Turn a raw workflow into a properly-skilled unit of this monorepo, or audit an existing `skills/<name>/` tree against the repo contract (CONTRIBUTING.md, "Adding a new skill"). Skillify is repo-only: it creates and scores skills in this repository, not anywhere else. Deep wiring/release mechanics belong to `skill-maintainer`; cross-reference it rather than restating it.
 
-## The completeness checklist
+## The contract checklist
 
-Score every item pass / fail / N/A. N/A requires a one-line rationale; N/A without one is a fail.
+Score every item pass / fail / N/A. N/A requires a one-line rationale; N/A without one is a fail. Numbering is stable and additive — future items append, existing items never renumber — so other skills can cite "skillify item 6".
 
-1. **SKILL.md spec-compliant** — frontmatter is exactly `name` + `description`; name matches the directory and the grammar (starts with a lowercase letter, `[a-z0-9-]`, no consecutive hyphens, max 64); description max 1024 chars with no angle brackets; body under 500 lines; no harness-specific body syntax. `bun run validate:skill` agrees.
-2. **Description triggers well** — states triggering conditions only (never the workflow), third person, trigger words front-loaded, per [authoring](references/authoring.md); a should/should-not-trigger query set with near-miss negatives exists at `tests/fixtures/trigger-queries.json`.
-3. **README walkthrough** — repo-side `README.md`: install, contents table, behavior contract.
-4. **References routed** — `references/` for on-demand detail with a routing table in SKILL.md; or N/A for a self-contained skill.
-5. **Scripts deterministic** — dependency-free Node under `scripts/`, `--json` for machine output, documented exit codes, atomic writes and symlink refusal for anything mutating; or N/A.
-6. **Assets** — templates/schemas/examples under `assets/`; or N/A.
-7. **Unit tests + fixtures** — `tests/*.test.ts` (bun test) covering every deterministic branch; fixtures under `tests/fixtures/`.
-8. **Consistency test** — a test asserting prose, scripts, templates, and registry agree: relative links resolve, documented flags exist, template inventory matches the scaffolder.
-9. **Behavioral eval evidence** — with-skill vs baseline subagent runs on 2–3 realistic prompts per the [eval playbook](references/eval-playbook.md); summary in the PR body; unresolved gaps in a KNOWN_GAPS section of the skill's README.
-10. **Refresh contract** — `refresh/sources.json` + `refresh/REFRESH.md` tracking every volatile claim; or an explicit evergreen waiver in REFRESH.md stating why nothing in the skill decays.
-11. **Codex metadata** — `agents/openai.yaml`.
-12. **Repo wiring** — sync-skill allowlist entry, root README table row, CHANGELOG entry (`skill-maintainer` owns the detail).
-13. **Green check** — `bun run check` passes.
+1. **SKILL.md spec-compliant** — frontmatter is exactly `name` + `description`; name matches the directory and the grammar (starts with a lowercase letter, `[a-z0-9-]`, no consecutive hyphens, max 64); description max 1024 chars with no angle brackets; body targets 50–150 lines with 300 as the ceiling; no harness-specific body syntax. `bun run validate:skill` agrees — it also verifies every relative link in the skill's prose resolves.
+2. **Description triggers well** — states triggering conditions only (never the workflow), third person, trigger words front-loaded, per [authoring](references/authoring.md); a query set of realistic positives and near-miss negatives exists at `tests/fixtures/trigger-queries.json`, with `ambiguous_with` naming the nearest competing skill where one exists.
+3. **Sharp boundary** — the SKILL.md body names its nearest-neighbor skill and the one-sentence axis of difference (or states it has no neighbor). Two skills answering the same trigger get merged, not shipped.
+4. **References routed** — `references/` holds detail only some invocations need, behind a routing table; SKILL.md keeps the workflow, one excellent example, and the routes. N/A for a self-contained skill.
+5. **Scripts deterministic and tested** — dependency-free Node under `scripts/`, `--json` for machine output, documented exit codes, atomic writes and symlink refusal for anything mutating, dry-run default; unit tests cover every deterministic branch. N/A when the skill ships no scripts — a prose-only skill needs no test theater; its quality bar is item 6.
+6. **Behavioral eval passed** — with-skill vs baseline subagent runs on 2–3 realistic prompts per the [eval playbook](references/eval-playbook.md), at most 3 improve cycles; pass, or ship with a KNOWN_GAPS section in the skill's README.
+7. **Freshness honest** — volatile facts (version pins, model names, numeric limits, dated claims) live in refresh-tracked files, never in SKILL.md; a skill with none states a one-line evergreen waiver in `refresh/REFRESH.md`.
+8. **Wired and green** — README walkthrough and `agents/openai.yaml` exist; packaging entry, root README row, and changeset are in place (the scaffolder performs these); `bun run check` passes.
 
-**Verdict:** all pass → `properly skilled`. At most three misses, none of items 1, 7, or 13 → `close — create: <missing items>`. Otherwise → `needs skillify — run skillify on <target>`. Always report the score as `<passed>/13` plus the verdict.
+**Verdict:** all pass → `properly skilled`. At most two misses, neither item 1 nor item 6 → `close — create: <missing items>`. Otherwise → `needs skillify — run skillify on <target>`. Always report the score as `<passed>/8` plus the verdict.
 
 ## Phase 0 — Should this be a skill?
 
@@ -37,6 +32,8 @@ Before anything else, check:
 
 If any answer is no: it is a script or a doc, not a skill. Stop — do not scaffold, do not write a SKILL.md. Say why and move on.
 
+Then search the existing skills. If one nearly covers the intent, **prefer merging into it** over creating a near-duplicate — a new neighbor that splits an existing trigger family makes both skills trigger worse.
+
 Scope upper bound: **one skill = one capability = one coherent trigger family.** If the target spans distinct intents users would invoke separately ("run the build" / "roll back the deploy" / "notify the team" are three intents), do not build one skill covering them all. Propose the split and ask which target to skillify first.
 
 ## Phase 1 — Audit
@@ -45,30 +42,22 @@ For an existing skill, score the checklist against the actual tree and stop with
 
 ```
 Skill: <name>            Path: skills/<name>/
-Score: <passed>/13       Verdict: <verdict>
+Score: <passed>/8        Verdict: <verdict>
 Missing: <item>: <one-line evidence> ...
 ```
 
-For a new skill the audit is trivially 0/13 — proceed. When the request was only "audit" / "is this complete", deliver the verdict and the shortest path to `properly skilled`; do not start editing unasked.
+For a new skill the audit is trivially 0/8 — proceed. When the request was only "audit" / "is this complete", deliver the verdict and the shortest path to `properly skilled`; do not start editing unasked.
 
 ## Phase 2 — Elicit requirements
 
 Interview before writing (skip questions the conversation already answers):
 
-- **Triggers:** what exact phrases should invoke this? What near-miss requests should NOT? (These become the query set.)
+- **Triggers:** what exact phrases should invoke this? What near-miss requests should NOT? Which existing skill is the nearest neighbor? (These become the query set and the boundary line.)
 - **Output:** what does done look like — files, report shape, side effects?
 - **Edge cases:** empty input, missing config, offline, partial state?
 - **Existing behavior:** is there code/prose to absorb? What did its author correct over time?
 
-Then classify every factual claim the skill will make:
-
-| Class | Meaning | Where it lives |
-|---|---|---|
-| Durable | versionless principle | references prose; refresh never edits |
-| Mechanism-coupled | durable intent through a vendor-named mechanism | marked `<!-- source: SOURCE-ID -->`; edited only with registry evidence |
-| Volatile | version pins, limits, model names, URLs | `refresh/sources.json` entries or refresh-tracked files only |
-
-Every mechanism-coupled or volatile claim needs a registry source — or the skill declares an evergreen waiver. No unclassified claims ship.
+While eliciting, mark every volatile fact the skill will state — version pins, model names, numeric limits, dated claims. Those go to refresh-tracked files (item 7); everything else is plain prose. A skill with no volatile facts takes the one-line evergreen waiver.
 
 ## Phase 3 — Scaffold and write
 
@@ -79,13 +68,12 @@ node <skill-dir>/scripts/scaffold-skill.mjs <name> --dir <repo-root>
 node <skill-dir>/scripts/scaffold-skill.mjs <name> --dir <repo-root> --write
 ```
 
-The scaffolder validates the name grammar, refuses existing directories and symlinks, stages in a temp sibling then renames, and prints the manual wiring steps. Then write, in this order:
+The scaffolder validates the name grammar, refuses existing directories and symlinks, stages in a temp sibling then renames, and performs the repo wiring itself (packaging entry, root README row, changeset) — fill in the README row's TODO description. Then write, in this order:
 
-1. *Description + trigger query set* — engineer the description per [authoring](references/authoring.md); write 8–10 should-trigger and 8–10 near-miss should-not-trigger queries into `tests/fixtures/trigger-queries.json`.
-2. *SKILL.md body* — workflow, one excellent example, routing table. Respect the token budgets in [authoring](references/authoring.md).
+1. *Description + trigger query set* — engineer the description per [authoring](references/authoring.md); write the query set with near-miss negatives into `tests/fixtures/trigger-queries.json`.
+2. *SKILL.md body* — workflow, one excellent example, nearest-neighbor boundary line, routing table. Respect the writing-style rules and token budgets in [authoring](references/authoring.md).
 3. *References* — detail that only some invocations need.
 4. *Scripts* — only for work that is deterministic and repeated (criteria in [authoring](references/authoring.md)).
-5. *Draft tests* — but do not treat them as the quality bar yet; that is Phase 4's job.
 
 ## Phase 4 — Behavioral eval — the quality gate
 
@@ -99,10 +87,9 @@ Iterate at most 3 cycles: eval → apply the top improvements to the skill → r
 
 Now that quality is proven:
 
-1. Finalize unit tests and fixtures locking in the eval-proven behavior; add the consistency test (item 8).
-2. Write `refresh/sources.json` + `refresh/REFRESH.md` from the Phase 2 claim classification — or the evergreen waiver.
-3. Finish `README.md` and `agents/openai.yaml`.
-4. Wire the repo: sync-skill allowlist, root README row, CHANGELOG entry — as printed by the scaffolder; `skill-maintainer` documents each step in depth.
+1. Write unit tests for the deterministic branches of any bundled scripts, plus fixtures. A prose-only skill keeps just its trigger-query fixture.
+2. Write `refresh/sources.json` + `refresh/REFRESH.md` for the volatile facts marked in Phase 2 — or the one-line evergreen waiver.
+3. Finish `README.md` and `agents/openai.yaml`; fill in the wiring TODOs the scaffolder left (README row description, changeset text).
 
 ## Phase 6 — Verify
 
@@ -112,23 +99,24 @@ bun test skills/<name>
 bun run check
 ```
 
-Re-score the checklist and report `<passed>/13` with the verdict. Anything below `properly skilled` ships only with named gaps.
+Re-score the checklist and report `<passed>/8` with the verdict. Anything below `properly skilled` ships only with named gaps.
 
 ## Worked example: skillifying a "release-notes" workflow
 
 ```
-Phase 0: yes — run at every release, ~80 lines of conventions, trigger "draft the release notes"
-Phase 1: 0/13 (new)
+Phase 0: yes — run at every release, ~80 lines of conventions, trigger "draft the release notes";
+  nearest neighbor is skill-maintainer (release wiring) — different axis, proceed
+Phase 1: 0/8 (new)
 Phase 2: triggers "draft/write the release notes", NOT "write a changelog entry for this PR";
-  output = CHANGELOG section + npm summary; claims: changeset flow = durable,
-  npm publish mechanics = mechanism-coupled (source NPM-PUBLISH), CLI version pin = volatile
-Phase 3: scaffold-skill.mjs release-notes --dir . --write; description + 18 trigger queries;
-  body + references/format.md; no scripts (judgment-heavy, N/A with rationale)
+  output = CHANGELOG section + npm summary; volatile: none owned → evergreen waiver
+Phase 3: scaffold-skill.mjs release-notes --dir . --write (wiring done by the scaffolder);
+  description + 10 trigger queries incl. ambiguous_with skill-maintainer; body + references/format.md;
+  no scripts (judgment-heavy, item 5 N/A)
 Phase 4: eval cycle 1 — baseline subagent invents section headings, with-skill misses breaking-change
   callouts → add callout contract to SKILL.md; cycle 2 — with-skill clearly better, baseline still
   wrong shape → pass
-Phase 5: tests lock the section contract; sources.json gets NPM-PUBLISH; wiring done
-Phase 6: bun run check green; 13/13 → properly skilled
+Phase 5: trigger fixture locked; evergreen waiver written; README row description filled in
+Phase 6: bun run check green; 8/8 → properly skilled
 ```
 
 ## Anti-patterns
@@ -141,14 +129,16 @@ Phase 6: bun run check green; 13/13 → properly skilled
 - Version pins or model names in SKILL.md — volatile facts live in refresh-tracked locations.
 - Multi-intent skills spanning unrelated triggers — split them.
 - Two skills answering the same trigger — merge or kill one.
-- Prose and scripts disagreeing about flags or paths — that is what the consistency test catches.
+- Steering by prohibition — a wall of NEVERs drags the forbidden behavior into context and grows forever; state the positive rule once and explain why it matters.
+- Patching every observed agent failure with a new clause — that is sediment; rewrite the existing rule in place instead of appending case law.
+- Unit tests for prose — a test asserting a markdown file contains a phrase proves nothing the eval didn't.
 - Building eval tooling — evals are instructions you run with subagents, not code you write.
 
 ## Routing
 
 | Need | Read |
 |---|---|
-| description engineering, numeric limits, token budgets, script-vs-instructions, claim classes | [authoring](references/authoring.md) |
+| description engineering, writing style, numeric limits, token budgets, script-vs-instructions, volatile facts | [authoring](references/authoring.md) |
 | eval method, pass criteria, trigger-query doctrine, cycle protocol, KNOWN_GAPS, model guidance | [eval playbook](references/eval-playbook.md) |
 | the scaffolded starting points | `assets/templates/` |
 | skillify's own freshness stance | [refresh/REFRESH.md](refresh/REFRESH.md) |

package/skill/skillify/assets/templates/REFRESH.md.template

@@ -4,18 +4,13 @@ Instructions for the scheduled refresh agent (and any human running a manual ref
 
 ## What this skill claims
 
-TODO: classify before shipping (see skillify references/authoring.md):
+TODO: apply the volatile-facts rule (skillify references/authoring.md) before shipping:
 
 - **Durable rules**: versionless principles in this skill's prose. The refresh agent NEVER edits these; if a source change invalidates one, open an issue quoting the evidence.
-- **Mechanism-coupled claims**: sentences marked with a source comment naming a SOURCE-ID from `sources.json`. The agent may propose edits to these marked sentences only, in the same PR as the registry update that evidences the change.
-- **Volatile layer**: `refresh/sources.json` itself (checksums, versions, retrieval times) — the only file the agent edits freely.
+- **Volatile facts**: version pins, model names, numeric vendor limits, URLs, dated claims. Each lives in a refresh-tracked file named here, evidenced by a `sources.json` entry. A sentence leaning on one vendor mechanism may be marked `<!-- source: SOURCE-ID -->`.
 
-## Evergreen waiver
-
-TODO: if this skill has NO mechanism-coupled or volatile claims, replace the sources TODO in `sources.json` with this waiver, filled in: "This skill's content is evergreen: it asserts no version pins, vendor mechanism names, numeric vendor limits, or dated facts. Rationale: ... Revisit if a future edit introduces any." Then delete the refresh steps below. Otherwise delete this section.
+TODO: name the refresh-tracked files and the sections the refresh agent may edit.
 
-## How to refresh
+## Evergreen waiver
 
-1. TODO: deterministic pass (which command, which registry).
-2. TODO: what may be auto-accepted vs what needs human review.
-3. One PR per refresh, evidence-linked; refresh branches touch only `refresh/` metadata.
+TODO: if this skill states no volatile facts, replace everything above with one line — "Evergreen: this skill asserts no version pins, vendor mechanism names, numeric vendor limits, or dated facts. Revisit if a future edit introduces any." — and keep `sources: []`.

package/skill/skillify/assets/templates/SKILL.md.template

@@ -11,6 +11,7 @@ TODO: one-paragraph overview - what this skill guarantees and the single trigger
 
 - TODO: concrete situations and user phrasings
 - TODO: when NOT to use - the nearest adjacent intent and where it goes instead
+- Nearest neighbor: TODO - name the closest existing skill and the one-sentence axis of difference (or state that none exists)
 
 ## Workflow
 

package/skill/skillify/assets/templates/skill.test.ts.template

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test'
-import { existsSync, readFileSync } from 'node:fs'
+import { readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { validateSkill } from '../../../packages/cli/scripts/validate-skill.mjs'
 
@@ -12,29 +12,16 @@ describe('{{name}} contract', () => {
     expect(result.ok).toBe(true)
   })
 
-  test('frontmatter carries only name and description', () => {
-    const content = readFileSync(join(skillRoot, 'SKILL.md'), 'utf8')
-    const frontmatter = /^---\n([\s\S]*?)\n---/.exec(content)
-    expect(frontmatter).not.toBeNull()
-    const keys = (frontmatter as RegExpExecArray)[1]
-      .split('\n')
-      .filter(line => /^[A-Za-z]/.test(line))
-      .map(line => line.split(':')[0])
-    expect(keys.sort()).toEqual(['description', 'name'])
+  test('trigger query fixture is a small hard set with near-miss negatives', () => {
+    const queries = JSON.parse(readFileSync(join(skillRoot, 'tests/fixtures/trigger-queries.json'), 'utf8'))
+    const positives = queries.filter((entry: { should_trigger: boolean }) => entry.should_trigger)
+    const negatives = queries.filter((entry: { should_trigger: boolean }) => !entry.should_trigger)
+    expect(positives.length).toBeGreaterThanOrEqual(5)
+    expect(negatives.length).toBeGreaterThanOrEqual(4)
+    for (const entry of queries) expect(typeof entry.query).toBe('string')
   })
 
-  test('relative markdown links resolve', () => {
-    for (const file of ['SKILL.md', 'README.md']) {
-      const body = readFileSync(join(skillRoot, file), 'utf8')
-      for (const match of body.matchAll(/\]\(([^)#\s]+)\)/g)) {
-        const target = match[1]
-        if (/^[a-z][a-z0-9+.-]*:/.test(target)) continue
-        expect(`${file} -> ${target}: ${existsSync(join(skillRoot, target))}`).toBe(`${file} -> ${target}: true`)
-      }
-    }
-  })
-
-  // TODO: add unit tests for every deterministic branch of scripts/, plus the
-  // consistency test (prose, scripts, templates, and registry agree). Lock in
-  // eval-proven behavior only AFTER the behavioral eval passes (skillify Phase 4).
+  // TODO: if this skill ships scripts/, add unit tests for every deterministic
+  // branch. A prose-only skill needs nothing more here - its quality bar is the
+  // behavioral eval of skillify Phase 4, which runs BEFORE tests lock anything in.
 })

package/skill/skillify/assets/templates/sources.json.template

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
   "retrievalBaseline": "{{date}}",
-  "note": "TODO: add one entry per volatile or mechanism-coupled external claim (see skillify references/authoring.md, claim classification), or record an evergreen waiver in REFRESH.md and keep sources empty.",
+  "note": "TODO: add one entry per volatile external fact this skill states (see skillify references/authoring.md, volatile facts), or record the one-line evergreen waiver in REFRESH.md and keep sources empty.",
   "sources": []
 }

package/skill/skillify/assets/templates/trigger-queries.json.template

@@ -0,0 +1 @@
+[]

package/skill/skillify/references/authoring.md

@@ -12,11 +12,22 @@ The description is the primary triggering mechanism: it is always in context, an
 - **Cover the ways users actually ask.** Exact phrases in quotes, symptoms, file types, adjacent phrasings, casual variants. Include the situations where the skill competes with a neighbor and should win.
 - **Name the boundary.** One clause on what the skill is NOT for prevents over-triggering ("Only for skills inside this repository...").
 - **No angle brackets** — the repo validator rejects them.
+- **No `#` after a space.** The description is an unquoted YAML scalar, and real harness parsers treat ` #` as a comment start — everything after it silently vanishes from the skill listing. Write "issue 12", never "issue #12"; the repo validator rejects it.
 
 Bad: `Helps with skills.` (no triggers, no boundary)
-Bad: `Audits a skill by scoring 13 checklist items, then scaffolds, evals, and wires it.` (workflow summary — the body will be skipped)
+Bad: `Audits a skill by scoring checklist items, then scaffolds, evals, and wires it.` (workflow summary — the body will be skipped)
 Good: `Use when asked to "skillify this", "make this a skill", audit a skill's completeness, or decide whether a workflow should become a skill. Only for skills inside this repository.`
 
+## Writing style
+
+Rules for the prose itself — they exist because agents pay attention (and tokens) for every sentence, and because rule corpora rot in predictable ways:
+
+- **Prompt the positive.** Steering by prohibition drags the forbidden behavior into context and invites a wall of NEVERs that only ever grows. State the rule you want followed, once, with the reason it matters. Reserve negation for genuinely dangerous acts.
+- **Explain why, not ALL-CAPS what.** Modern models have good theory of mind; a rule with its reason generalizes, a bare MUST gets pattern-matched and misapplied. Reaching for caps or bold on every rule is a sign the rule needs a reason, not emphasis.
+- **Hunt no-ops and sediment.** A no-op is an instruction the model already obeys by default — it pays load to say nothing. Sediment is case law: a clause added for one past failure that never gets removed. When a failure exposes a gap, rewrite the existing rule in place; do not append an exception. Prune by deleting whole sentences, not trimming words.
+- **Budget the body.** Target 50–150 lines for a SKILL.md; treat 300 as the ceiling (the spec's 500 is a far bound, not a budget). One great example beats five mediocre ones. Anything only some invocations need goes behind a routed reference.
+- **Name the nearest neighbor.** One sentence in the body stating which existing skill is closest and the axis of difference. It keeps trigger families sharp better than any linter, and forces the merge conversation before a near-duplicate ships.
+
 ## Numeric limits
 
 <!-- mirrored: these numbers are volatile and mirrored from the standards sources tracked by the skill-maintainer registry; on drift, fix them there first, then here. -->
@@ -32,10 +43,11 @@ Good: `Use when asked to "skillify this", "make this a skill", audit a skill's c
 
 ## Trigger query sets
 
-Every skill ships `tests/fixtures/trigger-queries.json`: an array of `{"query": "...", "should_trigger": true|false}`.
+Every skill ships `tests/fixtures/trigger-queries.json`: an array of `{"query": "...", "should_trigger": true|false}`, with an optional `"ambiguous_with": ["skill-name"]` on entries where a neighboring skill competes for the query.
 
-- 8–10 should-trigger: different phrasings of the same intent — formal, casual, typo-ridden; cases that never name the skill but clearly need it; cases where a neighboring skill competes and this one should win.
-- 8–10 should-NOT-trigger: **near-misses only.** Queries sharing keywords or domain with the skill but needing something else — adjacent intents, ambiguous phrasing a naive keyword match would catch. "Write a fibonacci function" as a negative for a PDF skill tests nothing.
+- About 10 queries total: 5–6 should-trigger, 4–5 should-NOT-trigger. A small set of hard queries beats a long set of easy ones.
+- Should-trigger: different phrasings of the same intent — formal, casual, typo-ridden; cases that never name the skill but clearly need it; at least one `ambiguous_with` case this skill should win against its nearest neighbor.
+- Should-NOT-trigger: **near-misses only.** Queries sharing keywords or domain with the skill but needing something else — adjacent intents, ambiguous phrasing a naive keyword match would catch. "Write a fibonacci function" as a negative for a PDF skill tests nothing.
 - Queries must be realistic: concrete detail, file paths, a little backstory — what a user would actually type, not abstract category labels.
 
 The set is both a design artifact (it forces the description to draw a real boundary) and eval input (see the [eval playbook](eval-playbook.md)).
@@ -48,7 +60,7 @@ Three loading levels; spend accordingly:
 2. **SKILL.md body** — loaded on every trigger. Keep the workflow, one excellent example, and a routing table; push everything else down a level. One great example beats five mediocre ones.
 3. **references/ / scripts/ / assets/** — loaded or executed on demand; effectively unlimited, but give each reference a clear routing condition so agents read only what the task needs.
 
-Cross-reference other skills by name (`skill-maintainer`) instead of restating their content. Don't document a script's flags in prose beyond what routing needs — the script's own `--help`/usage error is the source of truth, and the consistency test keeps the two honest.
+Cross-reference other skills by name (`skill-maintainer`) instead of restating their content. Don't document a script's flags in prose beyond what routing needs — the script's own `--help`/usage error is the source of truth.
 
 ## Scripts vs instructions
 
@@ -59,14 +71,8 @@ Cross-reference other skills by name (`skill-maintainer`) instead of restating t
 - Repo conventions for bundled scripts: dependency-free Node (`.mjs`), runnable from the skill dir with plain relative paths, `--json` for machine-readable output, documented exit codes (0 ok / 1 finding-or-refusal / 2 usage), atomic writes (stage then rename), symlink refusal, and an explicit `--write` gate for anything mutating — dry-run is the default.
 - Do NOT script judgment: descriptions, verdicts, review prose. A script that fakes judgment produces confident garbage.
 
-## Claim classification for refresh
-
-Classify every factual claim while writing, not after:
+## Volatile facts and refresh
 
-| Class | Test | Treatment |
-|---|---|---|
-| **Durable** | still true if every vendor renames everything | plain prose; refresh automation never touches it |
-| **Mechanism-coupled** | durable intent expressed through a vendor-named mechanism (an option name, an API shape) | mark the sentence `<!-- source: SOURCE-ID -->`; editable only alongside registry evidence for that source |
-| **Volatile** | version pins, numeric limits, model names, URLs, anything with a date | lives in `refresh/sources.json` entries or other refresh-tracked files — never inline in SKILL.md |
+One rule: **version pins, model names, numeric limits, URLs, and anything with a date live in refresh-tracked files — never inline in SKILL.md.** Everything else is plain prose that refresh automation never touches.
 
-The refresh contract falls out of this table: each distinct SOURCE-ID becomes a registry entry with URLs, checksum, threshold; REFRESH.md states which files the refresh agent may edit (the volatile layer), which sentences it may propose edits to (marked ones), and which it must only flag (durable). A skill with no mechanism-coupled or volatile claims declares an **evergreen waiver** in REFRESH.md — one paragraph stating why nothing decays — and keeps `sources: []`.
+A volatile fact gets a `refresh/sources.json` entry (URL, checksum, threshold) and lives in a section the REFRESH.md names as editable; marking an individual sentence `<!-- source: SOURCE-ID -->` remains available when a durable rule leans on one vendor-named mechanism. A skill with no volatile facts of its own declares an **evergreen waiver** in REFRESH.md — one line stating why nothing decays — and keeps `sources: []`. Facts whose source of truth already lives in another skill's registry are mirrored with a `<!-- mirrored -->` marker, not duplicated as a second registry entry.

package/skill/skillify/refresh/REFRESH.md

@@ -4,7 +4,7 @@ Instructions for the scheduled refresh agent (and any human running a manual ref
 
 ## What this skill claims
 
-- **Durable rules** (SKILL.md, most of `references/`): the phase model, checklist structure, eval-before-tests ordering, description doctrine, claim-classification taxonomy. Versionless; the refresh agent NEVER edits these. If external evidence invalidates one, open an issue quoting the evidence — do not edit.
+- **Durable rules** (SKILL.md, most of `references/`): the phase model, checklist structure, eval-before-tests ordering, description doctrine, the volatile-facts rule. Versionless; the refresh agent NEVER edits these. If external evidence invalidates one, open an issue quoting the evidence — do not edit.
 - **Mirrored volatile claims**: skillify does not track its own external sources. Its two volatile spots are marked in place:
   - the numeric limits and harness listing budgets table in `references/authoring.md` (marked `<!-- mirrored -->`);
   - the model guidance section in `references/eval-playbook.md` (marked `<!-- volatile -->`).

package/skill/skillify/scripts/scaffold-skill.mjs

@@ -4,10 +4,11 @@
 //   node scripts/scaffold-skill.mjs <skill-name> --dir <repo-root> [--write] [--json]
 //
 // Dry-run by default: prints the plan (files that would be created plus the
-// remaining manual wiring steps) and creates nothing. --write stages the tree
-// in a temporary sibling inside skills/ and renames it into place, refusing
-// existing directories and symlinks. Exit codes: 0 ok, 1 refusal or failure,
-// 2 usage error.
+// wiring actions that would be performed) and creates nothing. --write stages
+// the tree in a temporary sibling inside skills/ and renames it into place,
+// refusing existing directories and symlinks, then performs the repo wiring
+// itself: packaging.json entry, root README row, changeset. Exit codes: 0 ok,
+// 1 refusal or failure, 2 usage error.
 import { lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -22,9 +23,14 @@ export const templateFiles = [
   ['sources.json.template', 'refresh/sources.json'],
   ['REFRESH.md.template', 'refresh/REFRESH.md'],
   ['openai.yaml.template', 'agents/openai.yaml'],
+  // Scaffolded empty so the shape test stays red until real queries are written.
+  ['trigger-queries.json.template', 'tests/fixtures/trigger-queries.json'],
   ['skill.test.ts.template', null],
 ]
 
+// The scaffolded files that ship to installers (README and tests never package).
+const defaultPackagedFiles = ['SKILL.md', 'agents/openai.yaml', 'refresh/REFRESH.md', 'refresh/sources.json']
+
 // Full grammar shared by the repo validator and every target harness: starts
 // with a lowercase letter, then lowercase letters/digits/hyphens, no
 // consecutive hyphens, no trailing hyphen, at most 64 characters.
@@ -38,14 +44,6 @@ export function validateName(name) {
   return null
 }
 
-export function wiringSteps(name) {
-  return [
-    `Add skills/${name}/ packaged files to the allowlist in packages/cli/scripts/sync-skill.mjs (the build fails loudly on unlisted files)`,
-    `Add a ${name} row to the Skills table in the root README.md`,
-    `Add a CHANGELOG entry (changeset) introducing ${name}`,
-  ]
-}
-
 async function entryAt(path) {
   try {
     return await lstat(path)
@@ -54,6 +52,66 @@ async function entryAt(path) {
   }
 }
 
+async function writeAtomic(path, body) {
+  const staging = `${path}.scaffold-tmp`
+  await writeFile(staging, body)
+  await rename(staging, path)
+}
+
+// Adds the new skill's entry to packages/cli/packaging.json with the default
+// scaffolded runtime files. Extra authored files added later must be appended
+// there by hand — sync-skill.mjs still fails loudly on anything unlisted.
+async function wirePackaging(repoRoot, name, write) {
+  const path = join(repoRoot, 'packages/cli/packaging.json')
+  if (!(await entryAt(path))?.isFile()) return { step: 'packaging.json entry', status: 'skipped: packages/cli/packaging.json not found' }
+  const packaged = JSON.parse(await readFile(path, 'utf8'))
+  if (name in packaged) return { step: 'packaging.json entry', status: 'skipped: entry already exists' }
+  if (!write) return { step: 'packaging.json entry', status: 'planned' }
+  packaged[name] = defaultPackagedFiles
+  const sorted = Object.fromEntries(Object.keys(packaged).sort().map(key => [key, packaged[key]]))
+  await writeAtomic(path, `${JSON.stringify(sorted, null, 2)}\n`)
+  return { step: 'packaging.json entry', status: 'done' }
+}
+
+// Inserts a row for the new skill at the end of the root README's Skills table.
+async function wireReadme(repoRoot, name, write) {
+  const path = join(repoRoot, 'README.md')
+  if (!(await entryAt(path))?.isFile()) return { step: 'root README row', status: 'skipped: README.md not found' }
+  const body = await readFile(path, 'utf8')
+  if (body.includes(`](skills/${name}/)`)) return { step: 'root README row', status: 'skipped: row already exists' }
+  const lines = body.split('\n')
+  const header = lines.findIndex(line => /^\| *Skill *\|/.test(line))
+  if (header < 0 || !/^\|[ -]*---/.test(lines[header + 1] ?? '')) {
+    return { step: 'root README row', status: 'skipped: Skills table not found' }
+  }
+  let last = header + 1
+  while (lines[last + 1]?.startsWith('|')) last += 1
+  if (!write) return { step: 'root README row', status: 'planned' }
+  const row = `| [${name}](skills/${name}/) | TODO: one-line description | [Walkthrough](skills/${name}/README.md) · [SKILL.md](skills/${name}/SKILL.md) |`
+  lines.splice(last + 1, 0, row)
+  await writeAtomic(path, lines.join('\n'))
+  return { step: 'root README row', status: 'done' }
+}
+
+// Writes the changeset introducing the skill (content versioning: new skill = minor).
+async function wireChangeset(repoRoot, name, write) {
+  const directory = join(repoRoot, '.changeset')
+  if (!(await entryAt(directory))?.isDirectory()) return { step: 'changeset', status: 'skipped: .changeset/ not found' }
+  const path = join(directory, `add-${name}.md`)
+  if (await entryAt(path)) return { step: 'changeset', status: 'skipped: changeset already exists' }
+  if (!write) return { step: 'changeset', status: 'planned' }
+  await writeAtomic(path, `---\n"@vegastack/skills": minor\n---\n\nAdd the ${name} skill.\n`)
+  return { step: 'changeset', status: 'done' }
+}
+
+export async function wireSkill({ name, repoRoot, write = false }) {
+  return [
+    await wirePackaging(repoRoot, name, write),
+    await wireReadme(repoRoot, name, write),
+    await wireChangeset(repoRoot, name, write),
+  ]
+}
+
 export async function scaffoldSkill({ name, dir, write = false, now = new Date() }) {
   const nameError = validateName(name)
   if (nameError) throw new Error(`Invalid skill name ${JSON.stringify(name ?? null)}: ${nameError}`)
@@ -69,8 +127,8 @@ export async function scaffoldSkill({ name, dir, write = false, now = new Date()
   if (await entryAt(target)) throw new Error(`Refusing to scaffold: ${target} already exists`)
 
   const outputs = templateFiles.map(([source, output]) => [source, output ?? `tests/${name}.test.ts`])
-  const plan = { name, target, files: outputs.map(([, output]) => output), wiring: wiringSteps(name), wrote: false }
-  if (!write) return plan
+  const plan = { name, target, files: outputs.map(([, output]) => output), wrote: false }
+  if (!write) return { ...plan, wiring: await wireSkill({ name, repoRoot }) }
 
   const date = now.toISOString().slice(0, 10)
   const staging = await mkdtemp(join(skillsRoot, `.${name}.scaffold-`))
@@ -88,7 +146,7 @@ export async function scaffoldSkill({ name, dir, write = false, now = new Date()
     await rm(staging, { recursive: true, force: true })
     throw error
   }
-  return { ...plan, wrote: true }
+  return { ...plan, wrote: true, wiring: await wireSkill({ name, repoRoot, write: true }) }
 }
 
 function parseArguments(argv) {
@@ -128,8 +186,8 @@ if (invokedDirectly) {
     } else {
       console.log(result.wrote ? `Created ${result.target}` : `Dry run - pass --write to create ${result.target}`)
       for (const file of result.files) console.log(`  ${file}`)
-      console.log('Remaining manual wiring:')
-      for (const step of result.wiring) console.log(`  - ${step}`)
+      console.log('Wiring:')
+      for (const { step, status } of result.wiring) console.log(`  - ${step}: ${status}`)
     }
   } catch (error) {
     console.error(String(error.message ?? error))