scaffold-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

搭建一个生产就绪的TypeScript CLI项目（要求Node 22+），包含ESM模块、双构建（CLI + 库）、自动化发布以及Agent技能定义。

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

文件	读取时机
`references/scaffold-configs.md`	默认：package.json、tsconfig、tsdown、gitignore、license、changeset配置、GitHub Actions的模板
`references/scaffold-source.md`	默认：src/cli.ts、src/index.ts、src/types.ts、AGENTS.md、README.md、skills/SKILL.md的模板
`references/post-scaffold.md`	生成文件后：搭建完成后的命令和验证清单

Scaffold Workflow

搭建流程

Copy this checklist to track progress:

text

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

复制以下清单来跟踪进度：

text

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

步骤1：收集项目信息

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

从用户处收集以下信息（仅询问未提供的内容）：

变量	示例	默认值	使用位置
`{{name}}`	`md-tools`	—（必填）	package.json名称、README标题
`{{description}}`	`CLI tool to convert content to markdown`	—（必填）	package.json、README、SKILL.md
`{{bin}}`	`md`	与 `{{name}}` 相同	package.json的bin字段、CLI示例
`{{repo}}`	`acme/md-tools`	—（必填）	package.json的仓库信息、徽章
`{{author}}`	`Your Name`	—（必填）	package.json、LICENSE
`{{year}}`	`2026`	当前年份	LICENSE

Step 2: Create directory structure

步骤2：创建目录结构

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

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

Step 3: Generate config files

步骤3：生成配置文件

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

加载

references/scaffold-configs.md

。生成所有配置文件，将所有

{{placeholder}}

替换为实际值。

文件：

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

步骤4：生成源代码文件

Load

references/scaffold-source.md

. Generate:

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

加载

references/scaffold-source.md

。生成：

```
src/cli.ts
```
— Commander入口文件
```
src/index.ts
```
— 公开API导出文件
```
src/types.ts
```
— 共享类型定义文件

Step 5: Generate docs and skill

步骤5：生成文档与Agent技能

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

加载

references/scaffold-source.md

。生成：

```
AGENTS.md
```
— 命令、架构、注意事项
```
README.md
```
— 徽章、功能、安装、使用方法、API、许可证
```
skills/{{bin}}/SKILL.md
```
— Agent技能定义

然后创建符号链接：

ln -s AGENTS.md CLAUDE.md

Step 6: Run post-scaffold commands

步骤6：执行搭建完成后的命令

Load

references/post-scaffold.md

. Run the full command sequence in order.

加载

references/post-scaffold.md

。按顺序执行完整的命令序列。

Step 7: Validate scaffold

步骤7：验证搭建结果

Load

references/post-scaffold.md

. Run all validation checks and confirm every item passes.

加载

references/post-scaffold.md

。运行所有验证检查并确认所有项均通过。

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

所有模板使用

{{variable}}

语法。在写入文件前，需进行最终检查以确保没有遗漏任何占位符。

占位符	来源
`{{name}}`	项目名称（短横线命名法）
`{{description}}`	一行项目描述
`{{bin}}`	CLI二进制文件名
`{{repo}}`	GitHub所有者/仓库名
`{{author}}`	作者姓名
`{{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)

运行时：

@clack/prompts

commander

gray-matter

开发环境：

@changesets/cli

@types/node

tsdown

typescript

ultracite

vitest

内置（无需安装）：

node:util

的styleText用于颜色（替代chalk），

@clack/prompts

的spinner用于进度显示（替代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

请勿使用CommonJS — 所有输出必须为ESM，且设置
```
"type": "module"
```
请勿跳过AGENTS.md或
```
skills/
```
目录 — 每个CLI项目都需要Agent相关说明
请勿在搭建过程中创建测试文件 — 让用户为其特定功能添加测试
请勿合并tsdown的双构建 — CLI（包含shebang）和库（包含dts）必须保持分离
请勿直接调用oxlint或oxfmt — 始终使用
```
ultracite fix
```
或
```
ultracite check
```
请勿手动配置git钩子 — ultracite会自动设置lefthook
请勿添加chalk或ora — 使用
```
node:util
```
的styleText实现颜色，使用
```
@clack/prompts
```
的spinner实现进度显示