scaffold-cli（scaffold CLI 命令行）

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

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):

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.

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