scaffold-new-skill

scaffold-new-skill

A meta-skill that generates a spec-compliant skeleton for a new skills/<name>/ bundle. Every artefact it writes satisfies the same rules pnpm validate:skills enforces (ADR-0001, A-364), so a freshly scaffolded skill is valid the moment it lands — the boilerplate can no longer drift away from the contract by hand.

Configuration

Two defaults live in config.json beside this file:

Key	Meaning	Default
scope	The npm scope used in the generated package.json name (<scope>/skill-<name>).	"@acme-skunkworks"
author	The default author string stamped into the generated SKILL.md metadata.author and package.json.	"Rob Easthope"

A neutral config.example.json ships alongside as a template; its key set is identical to config.json. Override the author per run with --author="…".

What it generates

Given a kebab-case --name=<name>, the generator writes:

• skills/<name>/SKILL.md — frontmatter with name: <name>, metadata.version: 0.1.0, and metadata.author, plus a ## Process / ## Scripts body skeleton with TODO placeholders.
• skills/<name>/package.json — name: @acme-skunkworks/skill-<name>, private: true, version: 0.1.0, and repository.directory: "skills/<name>".
• skills/<name>/config.json + skills/<name>/config.example.json — generated from one template object, so their key sets are identical by construction (parity, not a thing to keep in sync by hand).
• skills/<name>/scripts/<name>.mjs — a zero-dependency entry script pre-wired to the standard --help / --dry-run / --self-test dispatch idiom (A-462), with a pure run() export and a isCliEntry() guard.
• skills/<name>/README.md — an install + usage skeleton.
• tests/skills/<name>/<name>.test.ts — a vitest stub that imports the entry script's run() export. It lands in the repo's tests/ tree (already covered by the root vitest glob), so the new skill's tests run with no config change.

Process

1. Pick a name. Lower-case kebab-case ([a-z0-9-], no leading/trailing or consecutive hyphens, ≤64 chars), matching the directory the bundle will live in. The generator rejects anything else before writing.

2. Preview first. Run a --dry-run to list exactly what would be written and confirm the name and paths:

   node skills/scaffold-new-skill/scripts/scaffold.mjs --name=<name> --dry-run
   

3. Generate. Drop --dry-run to write the skeleton. The generator refuses to overwrite a skills/<name>/ that already exists with content, so an accidental re-run can't clobber real work:

   node skills/scaffold-new-skill/scripts/scaffold.mjs --name=<name>
   

   Pass --author="…" to override the default author for this skill.

4. Verify the gate is green. The skeleton is built to pass, but confirm:

   pnpm validate:skills && pnpm test
   

5. Fill in the TODOs. Replace the placeholder description, body, config keys, entry-script logic, and the test stub with the real skill. Bump the version in lockstep (package.json version + SKILL.md metadata.version) as the skill grows, per the repo's by-hand skill-versioning rule.

Scripts

The bundled scripts/scaffold.mjs is a zero-dependency Node generator. It supports the standard dispatch flags:

• --help (alias -h) — print usage.
• --dry-run — print the files it would write, create nothing.
• --self-test — run built-in offline assertions (name validation, that the generated skeleton passes the validate-skills rules, config/example key parity, that the dry-run path writes nothing, a real write, and the clobber-refusal guard) against a temp directory. No network, no writes outside the temp dir.