Scaffold CLI

Scaffold a production-ready TypeScript CLI project (Node 22+) with ESM modules, dual-build (CLI + library), automated releases, and an agent skill definition.

Reference Files

File	Read When
`references/scaffold-configs.md`	Default: templates for package.json, tsconfig, tsdown, gitignore, license, changeset config, GitHub Actions
`references/scaffold-source.md`	Default: templates for src/cli.ts, src/index.ts, src/types.ts, AGENTS.md, README.md, skills/SKILL.md
`references/post-scaffold.md`	After generating files: post-scaffold commands and validation checklist

Scaffold Workflow

Copy this checklist to track progress:

Scaffold progress:
- [ ] Step 1: Gather project info
- [ ] Step 2: Create directory structure
- [ ] Step 3: Generate config files
- [ ] Step 4: Generate source files
- [ ] Step 5: Generate docs and skill
- [ ] Step 6: Run post-scaffold commands
- [ ] Step 7: Validate scaffold

Step 1: Gather project info

Collect from the user (ask only what was not provided):

Variable	Example	Default	Used in
`{{name}}`	`md-tools`	— (required)	package.json name, README title
`{{description}}`	`CLI tool to convert content to markdown`	— (required)	package.json, README, SKILL.md
`{{bin}}`	`md`	same as `{{name}}`	package.json bin field, CLI examples
`{{repo}}`	`acme/md-tools`	— (required)	package.json repository, badges
`{{author}}`	`Your Name`	— (required)	package.json, LICENSE
`{{year}}`	`2026`	current year	LICENSE

Step 2: Create directory structure

{{name}}/
  .changeset/
  .github/
    workflows/
  src/
  skills/{{bin}}/

Step 3: Generate config files

Load references/scaffold-configs.md. Generate all config files, replacing every {{placeholder}} with actual values.

Files: package.json, tsconfig.json, tsdown.config.ts, .gitignore, LICENSE.md, .changeset/config.json, .changeset/README.md, .github/workflows/ci.yml, .github/workflows/npm-publish.yml

Step 4: Generate source files

Load references/scaffold-source.md. Generate:

src/cli.ts — Commander entry point
src/index.ts — Public API exports
src/types.ts — Shared type definitions

Step 5: Generate docs and skill

Load references/scaffold-source.md. Generate:

AGENTS.md — Commands, architecture, gotchas
README.md — Badges, features, install, usage, API, license
skills/{{bin}}/SKILL.md — Agent skill definition

Then create symlink: ln -s AGENTS.md CLAUDE.md

Step 6: Run post-scaffold commands

Load references/post-scaffold.md. Run the full command sequence in order.

Step 7: Validate scaffold

Load references/post-scaffold.md. Run all validation checks and confirm every item passes.

Placeholder Reference

All templates use {{variable}} syntax. Do a final sweep to catch any missed placeholders before writing files.

Placeholder	Source
`{{name}}`	Project name (kebab-case)
`{{description}}`	One-line project description
`{{bin}}`	CLI binary name
`{{repo}}`	GitHub owner/repo
`{{author}}`	Author name
`{{year}}`	Current year

Dependencies

Runtime: @clack/prompts, commander, gray-matter

Development: @changesets/cli, @types/node, tsdown, typescript, ultracite, vitest

Built-in (no install needed): node:util styleText for colors (replaces chalk), @clack/prompts spinner for progress (replaces ora)

Anti-patterns

Do not use CommonJS — all output must be ESM with "type": "module"
Do not skip AGENTS.md or skills/ directory — every CLI project needs agent instructions
Do not create test files in the scaffold — let the user add tests for their specific features
Do not merge the dual tsdown builds — CLI (with shebang) and library (with dts) must stay separate
Do not call oxlint or oxfmt directly — always use ultracite fix or ultracite check
Do not configure git hooks manually — ultracite sets up lefthook automatically
Do not add chalk or ora — use node:util styleText for colors and @clack/prompts spinner

scaffold-cli