create-template

name

create-template

description

Create a new project template under templates/ in the quicktests repo. Use when the user asks to create, add, or scaffold a new template — e.g. "make a template for X", "add a canvas template", "new quicktests template". Copies the default CLAUDE.md (comment-length rules, docs/ layout, post-plan audit) and the standard TypeScript/tsgo + esbuild + eslint + jest + prettier + nwjs toolchain into templates/<name>/. Accepts an optional default prompt to save as the template's prompt.md.

Creating a quicktests template

A template is a complete, runnable project skeleton in templates/<name>/. Users stamp it into a working copy with pnpm use-template <name> <instance-name>, which copies the folder to instances/<instance-name> and runs pnpm install there.

Two things must be true of every template: it carries a CLAUDE.md, and pnpm check passes in a freshly stamped instance.

A template may also carry a default prompt — the task an agent is meant to be given when working in an instance of it. It lives in templates/<name>/prompt.md and is optional; a template without one is perfectly valid.

Where the pieces live

• assets/CLAUDE.md (next to this file) is the single source of truth for the default CLAUDE.md. Copy it verbatim. If a rule in it needs to change, change it here so every future template inherits the change — do not edit the copy in one template.
• templates/basic/ is the reference toolchain. Copy its config and script files as the starting point rather than writing esbuild/jest/eslint config from scratch.

Steps

1. Confirm the name and the point of the template. The name becomes the directory and the default package.json name, so keep it lowercase-kebab. Ask what the template is for if it isn't obvious — that determines what gets added on top of basic.

2. Copy the reference toolchain. From the repo root:

   templates/basic/{package.json,tsconfig.json,eslint.config.mjs,jest.config.mjs}
   templates/basic/{.prettierrc.json,.prettierignore,.gitignore}
   templates/basic/scripts/{config.mjs,dev.mjs,build.mjs,shell.mjs}
   templates/basic/scripts/{nwbin.mjs,profile.mjs,devlock.mjs,pid.mjs}
   templates/basic/.npmrc                    (nwjs flavour + shared download cache)
   templates/basic/docs/                     (keep the plans/ research/ debugging/ tree)
   

   Copy scripts/ as a set. shell.mjs imports the other four, and the nwjs isolation rules in the CLAUDE.md you are about to copy describe behaviour those files implement — take one without the rest and the document starts lying.

   Set name in the copied package.json to the template name. Leave the scripts alone unless the template genuinely needs different ones.

3. Copy assets/CLAUDE.md to templates/<name>/CLAUDE.md, unchanged.

4. Append a template-specific section to that CLAUDE.md — and only that. It covers what makes this template different: extra dependencies, extra directories, conventions that don't apply elsewhere. Everything general already lives in the copied part.

5. Write the skeleton — and only the skeleton. public/index.html, src/main.ts, and whatever the template is actually demonstrating. Include at least one jest test — a template whose test command has nothing to run is a template that silently stops being checked. Respect the comment rules in the CLAUDE.md you just copied; the template's own source is the first example anyone reads.

   A template with a default prompt implements none of that prompt. The prompt is the task a future agent is given; anything already built is a task already done, and the run stops testing what it was set up to test. That covers the whole domain, not just the finished feature — no game loop for a game prompt, no grid or entity types, no "scaffolding they'll need anyway", however obvious the shape looks from here. If in doubt, copy basic's counter demo across unchanged as the placeholder and let the prompt do the rest. Guessing at the foundation is the same mistake as building the feature, only harder to notice.

   What the template does carry beyond basic is toolchain: a dependency the task genuinely requires, a directory the conventions need, a config change. Those are inputs to the work, not the work.

6. Add a short templates/<name>/README.md — one paragraph on what the template is for and the command to stamp it.

7. Write the default prompt, if one was given. If the invocation supplied prompt text — as the skill's arguments, or anywhere in the request ("…with the prompt: build a spirograph") — save it to templates/<name>/prompt.md.

   Save it verbatim. It is the input to a future run, not documentation of one. Do not rewrite it, expand it, correct its grammar, split it into steps, or wrap it in headings and preamble. Editing a prompt changes the thing being tested. The only additions allowed are a trailing newline and, if the text is not already a markdown document, nothing else.

   If no prompt was given, do not create the file — not an empty one, not a placeholder, not a TODO. An absent prompt.md says "this template has no default task"; a stub says "someone meant to write one", which is a different and untrue claim. Do not invent a prompt to fill the gap, and do not ask for one unprompted; templates without a default task are ordinary.

8. Verify before declaring done:

   pnpm use-template <name> tmp-verify
   cd instances/tmp-verify && pnpm check
   

   Then delete instances/tmp-verify. If pnpm check fails, fix the template, not the instance — the instance is a throwaway.

   Confirm the copied CLAUDE.md is still the asset verbatim, with nothing but the appendix added:

   diff .claude/skills/create-template/assets/CLAUDE.md templates/<name>/CLAUDE.md
   

   Every line must be a >. A < line means the asset moved on and this template did not.

   If you wrote a prompt.md, confirm the stamped instance has it and that its bytes match what the user supplied.

   If the template changed anything under scripts/, run the repo's own pnpm test from the root as well. It stamps two instances and runs their nwjs shells side by side, which is the only thing that catches a shared port or a shared chromium profile.

Things that go wrong

• Editing the template's CLAUDE.md instead of assets/CLAUDE.md. Fixes to the shared rules must land in the asset or they don't propagate.
• Leaving existing templates behind when the asset changes. The copies do not update themselves. After editing assets/CLAUDE.md, re-run the diff above against every templates/*/CLAUDE.md, not just the one being worked on.
• Tidying up the default prompt. prompt.md is test input. Rewording it, structuring it, or fixing its grammar quietly changes what the template tests. Copy it across untouched.
• Starting the prompt's work while making the template. "Create a puzzle fighter game" is a task to hand over, not a spec to build against, and a template shipping a board, a game loop, or a piece type has answered the questions the run existed to ask. The tell is easy to miss because the code looks like scaffolding: if a module would be pointless in a template that had a different prompt.md, it belongs to the prompt, not the template.
• Hardcoding the dev-server port. It is defined once in scripts/config.mjs; the nwjs manifest is generated from it.
• Adding a UI framework by reflex. Templates are deliberately framework-free unless the user asks for one, and then only that template gets it.
• Installing dependencies inside templates/<name>/. Templates stay uninstalled; use-template runs the install in the instance. (node_modules is excluded from the copy anyway, so an accidental install is wasted work rather than a broken instance.)