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