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>). |
"@rheged-studio" |
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: @rheged-studio/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
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.
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
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.
Verify the gate is green. The skeleton is built to pass, but confirm:
pnpm validate:skills && pnpm test
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.
1---2name: scaffold-new-skill3description: Generate a spec-compliant new-skill skeleton under skills/<name>/ for the agent-skills repo, so new bundles start consistent and stop drifting. Use when asked to scaffold / create / bootstrap / start a new skill, add a new skill bundle, or generate the boilerplate for a skill. Writes a SKILL.md, a package.json (@rheged-studio/skill-<name>, private, version 0.1.0), a config.json + config.example.json with identical key sets, an entry script wired to the standard --help / --dry-run / --self-test dispatch idiom, a vitest test stub, and a README — all passing the same pnpm validate:skills gate. Has a --dry-run preview and refuses to clobber an existing bundle.4license: MIT5---67# scaffold-new-skill89A meta-skill that generates a spec-compliant skeleton for a new `skills/<name>/`10bundle. Every artefact it writes satisfies the same rules `pnpm validate:skills`11enforces (ADR-0001, A-364), so a freshly scaffolded skill is valid the moment it12lands — the boilerplate can no longer drift away from the contract by hand.1314## Configuration1516Two defaults live in [`config.json`](config.json) beside this file:1718| Key | Meaning | Default |19| --- | --- | --- |20| `scope` | The npm scope used in the generated `package.json` name (`<scope>/skill-<name>`). | `"@rheged-studio"` |21| `author` | The default author string stamped into the generated `SKILL.md` `metadata.author` and `package.json`. | `"Rob Easthope"` |2223A neutral [`config.example.json`](config.example.json) ships alongside as a24template; its key set is identical to `config.json`. Override the author per run25with `--author="…"`.2627## What it generates2829Given a kebab-case `--name=<name>`, the generator writes:3031- `skills/<name>/SKILL.md` — frontmatter with `name: <name>`,32 `metadata.version: 0.1.0`, and `metadata.author`, plus a `## Process` /33 `## Scripts` body skeleton with `TODO` placeholders.34- `skills/<name>/package.json` — `name: @rheged-studio/skill-<name>`,35 `private: true`, `version: 0.1.0`, and `repository.directory: "skills/<name>"`.36- `skills/<name>/config.json` + `skills/<name>/config.example.json` — generated37 from one template object, so their **key sets are identical by construction**38 (parity, not a thing to keep in sync by hand).39- `skills/<name>/scripts/<name>.mjs` — a zero-dependency entry script pre-wired40 to the standard `--help` / `--dry-run` / `--self-test` dispatch idiom (A-462),41 with a pure `run()` export and a `isCliEntry()` guard.42- `skills/<name>/README.md` — an install + usage skeleton.43- `tests/skills/<name>/<name>.test.ts` — a vitest stub that imports the entry44 script's `run()` export. It lands in the repo's `tests/` tree (already covered45 by the root vitest glob), so the new skill's tests run with **no config change**.4647## Process48491. **Pick a name.** Lower-case kebab-case (`[a-z0-9-]`, no leading/trailing or50 consecutive hyphens, ≤64 chars), matching the directory the bundle will live51 in. The generator rejects anything else before writing.522. **Preview first.** Run a `--dry-run` to list exactly what would be written and53 confirm the name and paths:5455 ```bash56 node skills/scaffold-new-skill/scripts/scaffold.mjs --name=<name> --dry-run57 ```58593. **Generate.** Drop `--dry-run` to write the skeleton. The generator refuses to60 overwrite a `skills/<name>/` that already exists with content, so an61 accidental re-run can't clobber real work:6263 ```bash64 node skills/scaffold-new-skill/scripts/scaffold.mjs --name=<name>65 ```6667 Pass `--author="…"` to override the default author for this skill.684. **Verify the gate is green.** The skeleton is built to pass, but confirm:6970 ```bash71 pnpm validate:skills && pnpm test72 ```73745. **Fill in the `TODO`s.** Replace the placeholder `description`, body, config75 keys, entry-script logic, and the test stub with the real skill. Bump the76 version in lockstep (`package.json` `version` + `SKILL.md` `metadata.version`)77 as the skill grows, per the repo's by-hand skill-versioning rule.7879## Scripts8081The bundled [`scripts/scaffold.mjs`](scripts/scaffold.mjs) is a zero-dependency82Node generator. It supports the standard dispatch flags:8384- `--help` (alias `-h`) — print usage.85- `--dry-run` — print the files it would write, create nothing.86- `--self-test` — run built-in offline assertions (name validation, that the87 generated skeleton passes the `validate-skills` rules, config/example key88 parity, that the dry-run path writes nothing, a real write, and the89 clobber-refusal guard) against a temp directory. No network, no writes outside90 the temp dir.
rheged-studio