new-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

New Project

新项目

Plan and safely bootstrap modern software projects from typed presets and capability preferences.

基于类型化预设和功能偏好，规划并安全启动现代化软件项目。

Dispatch

命令调度

`$ARGUMENTS`	Action
Empty	Gallery: show modes, presets, preference categories, examples; do not edit
`prefs` , `prefs list` , `catalog`	Preferences: list capability categories and defaults
`prefs validate`	Preferences: validate capability and preset catalogs
`prefs add <id>`	Preferences: explain the safe preference addition workflow
`preset list`	Presets: show curated presets and tradeoffs
`plan <name-or-path>`	Plan: read-only blueprint for a new or existing target
`init <name>` , `new <name>`	Init: new target setup after preflight, blueprint, and approval
`bootstrap <path>` , `init-existing <path>`	Bootstrap Existing: non-destructive missing-file setup
`audit <path>`	Audit: read-only scaffold and convention health report
`repair <path>`	Repair: approved additive repair based on audit findings
`doctor <path>`	Doctor: validate toolchain/config health without changing files
`docs <path>`	Docs: classify docs-lite, docs-themed, docs-interactive, or docs-product
`docs-lite <path>` , `starlight <path>`	Docs Lite: Astro Starlight static docs profile
`docs-themed <path>`	Docs Themed: Starlight plus CSS/Tailwind brand layer
`docs-interactive <path>`	Docs Interactive: Starlight plus React islands
`docs-product <path>` , `fumadocs <path>`	Docs Product: Next.js plus Fumadocs advanced docs profile
`ai <path>` , `agents <path>`	AI Instructions: AGENTS, nested AGENTS, Claude Code, OpenCode, Codex planning
`github <path>`	GitHub: CI, templates, release workflow planning
`python <name>` , `uv <name>`	Init/Plan: Python-focused preset
`node <name>` , `web <name>` , `next <name>`	Init/Plan: Node/web preset
`data <name>`	Init/Plan: Supabase, SQLite, DuckDB, notebooks preset
`aws <name>` , `agentcore <name>`	Plan: Bedrock/AgentCore planning; provider mutation is opt-in
`monorepo <name>` , `nx <name>`	Init/Plan: monorepo preset
`full <name>` , `max-free <name>`	Plan: comprehensive blueprint; apply module-by-module only
Natural language new repo/bootstrap request	Auto-classify, then ask only high-impact missing questions
Product feature request	Refuse or redirect to implementation skills
Agent or MCP server request	Refuse or redirect to `agent-conventions` or `mcp-creator`
Destructive or force request	Stop, explain risk, require file-by-file approval

`$ARGUMENTS`	操作说明
空值	展示库：显示模式、预设、偏好类别及示例；不进行编辑操作
`prefs` , `prefs list` , `catalog`	偏好设置：列出功能类别及默认值
`prefs validate`	偏好设置：验证功能与预设目录的有效性
`prefs add <id>`	偏好设置：说明安全的偏好添加流程
`preset list`	预设：展示精选预设方案及其权衡要点
`plan <name-or-path>`	规划：为新目标或现有目标生成只读蓝图
`init <name>` , `new <name>`	初始化：在预检、蓝图确认及审批完成后，完成新目标的搭建
`bootstrap <path>` , `init-existing <path>`	现有项目启动：为现有项目无损添加缺失文件
`audit <path>`	审计：生成只读的脚手架与规范健康报告
`repair <path>`	修复：基于审计结果，执行已获批的增量修复操作
`doctor <path>`	诊断：验证工具链/配置健康状态，不修改文件
`docs <path>`	文档：将文档分类为轻量文档、主题文档、交互式文档或产品级文档
`docs-lite <path>` , `starlight <path>`	轻量文档：Astro Starlight静态文档配置
`docs-themed <path>`	主题文档：Starlight + CSS/Tailwind品牌层配置
`docs-interactive <path>`	交互式文档：Starlight + React islands配置
`docs-product <path>` , `fumadocs <path>`	产品级文档：Next.js + Fumadocs高级文档配置
`ai <path>` , `agents <path>`	AI指令：AGENTS、嵌套AGENTS、Claude Code、OpenCode、Codex规划
`github <path>`	GitHub：CI、模板、发布流程规划
`python <name>` , `uv <name>`	初始化/规划：Python专属预设
`node <name>` , `web <name>` , `next <name>`	初始化/规划：Node/Web预设
`data <name>`	初始化/规划：Supabase、SQLite、DuckDB、笔记本预设
`aws <name>` , `agentcore <name>`	规划：Bedrock/AgentCore规划；提供商变更为可选操作
`monorepo <name>` , `nx <name>`	初始化/规划：单体仓库预设
`full <name>` , `max-free <name>`	规划：全面蓝图；仅支持逐个模块应用
自然语言描述的新仓库/启动请求	自动分类，仅询问高影响的缺失信息
产品功能请求	拒绝请求或重定向至实现类技能
Agent或MCP服务器请求	拒绝请求或重定向至 `agent-conventions` 或 `mcp-creator`
破坏性或强制请求	终止操作，说明风险，要求逐文件审批

Operating Flow

操作流程

Classify the request as new project, existing repo bootstrap, audit, repair, preferences, docs, AI instructions, GitHub, cloud/data, or refusal.
Read
```
references/intake-and-routing.md
```
for ambiguous or natural-language requests.
Run read-only preflight before any mutating mode.
Resolve presets and capabilities from
```
data/
```
, not from ad hoc prose.
Produce a blueprint with files, commands, skipped existing files, risks, approvals, and validation.
Apply only after explicit approval, one module at a time.
Run validation and summarize created, skipped, and deferred work.

将请求分类为新项目、现有仓库启动、审计、修复、偏好设置、文档、AI指令、GitHub、云/数据或拒绝处理。
若请求模糊或为自然语言输入，阅读
```
references/intake-and-routing.md
```
。
在执行任何修改操作前，先运行只读预检。
从
```
data/
```
目录解析预设与功能，而非临时文本。
生成包含文件、命令、跳过的现有文件、风险、审批项及验证内容的蓝图。
仅在获得明确审批后，逐个模块应用变更。
执行验证并总结已创建、已跳过及已延迟的工作内容。

Pattern Implementation

模式实现

Classification-Gating

分类管控

Classify every request before acting: new project, existing bootstrap, audit, repair, preferences, docs, AI instructions, GitHub, cloud/data, or refusal. Ambiguous requests stay read-only until the missing choice is resolved.

在执行操作前对所有请求进行分类：新项目、现有项目启动、审计、修复、偏好设置、文档、AI指令、GitHub、云/数据或拒绝处理。模糊请求保持只读状态，直至明确缺失选项。

Progressive-Disclosure

渐进式披露

Keep

SKILL.md

as the routing contract. Load references for domain detail, data files for preferences, scripts for deterministic checks, and templates only for report rendering.

将

SKILL.md

作为路由契约。加载参考文件获取领域细节，加载数据文件获取偏好设置，加载脚本执行确定性检查，仅在生成报告时使用模板。

Scaling-Strategy

扩展策略

Add future stacks as capabilities and presets first. Change the dispatch table only when a new top-level mode is needed.

新增技术栈时，先将其作为功能与预设添加。仅当需要新增顶层模式时，才修改命令调度表。

Canonical Vocabulary

标准术语

Use these canonical terms exactly.

Term	Meaning
Preset	Curated setup bundle, such as `minimal` , `python-api` , `docs-lite` , or `monorepo`
Capability	Atomic setup feature, such as `python.uv` , `docs.starlight` , or `github.actions-ci`
Blueprint	Read-only project setup plan with files, commands, risks, approvals, and checks
Apply step	One approved mutation unit from a blueprint
External side effect	Cloud, deploy, release, DNS, account, or provider mutation

严格使用以下标准术语。

术语	含义
Preset	精选的搭建包，例如 `minimal` 、 `python-api` 、 `docs-lite` 或 `monorepo`
Capability	原子化搭建功能，例如 `python.uv` 、 `docs.starlight` 或 `github.actions-ci`
Blueprint	只读的项目搭建规划，包含文件、命令、风险、审批项及检查内容
Apply step	蓝图中单个已获批的修改单元
External side effect	云服务、部署、发布、DNS、账户或提供商变更操作

Reference File Index

参考文件索引

File	Purpose	Read When
`references/workflow.md`	End-to-end safe setup flow	Mutating modes
`references/capability-model.md`	Capability schema and conflict semantics	Preference/catalog work
`references/presets.md`	Presets and tradeoffs	Preset selection
`references/preference-catalog.md`	Human-readable preference list	`prefs` , planning
`references/adding-preferences.md`	Future preference extension workflow	`prefs add` , maintenance
`references/intake-and-routing.md`	Classification and ambiguity handling	Natural language inputs
`references/scaffold-profiles.md`	Artifact matrices by preset	Blueprinting
`references/python-uv.md`	uv, uvx, pyproject, Python packages	Python profiles
`references/node-pnpm-npm.md`	pnpm, npm/npx, TypeScript, Next, Astro, Nx, Changesets	Node profiles
`references/docs-starlight-react.md`	Starlight docs-lite/themed/interactive guidance	Docs light modes
`references/docs-fumadocs.md`	Fumadocs docs-product guidance	Docs product mode
`references/design-system.md`	DESIGN.md and anti-slop design guidance	Web/docs/design profiles
`references/data-platforms.md`	Supabase, SQLite, DuckDB, Kaggle, Colab	Data/notebook profiles
`references/ai-apps.md`	Pydantic AI, LangGraph, Vercel AI SDK, Bedrock, AgentCore	AI app profiles
`references/github-ci-release.md`	Actions, releases, least-privilege CI	GitHub mode
`references/cloud-deploy-dns.md`	Vercel, Cloudflare DNS, AWS deploy gates	Cloud modes
`references/precommit-quality-gates.md`	pre-commit and CI mirroring	Quality gates
`references/conventional-commits-release.md`	Conventional Commits, Changesets, releases	Release profile
`references/ai-agent-instructions.md`	AGENTS, nested AGENTS, Claude Code, OpenCode, Codex	AI instruction mode
`references/openspec-governance.md`	OpenSpec setup and generated artifact policy	OpenSpec profile
`references/security-supply-chain.md`	Secrets, package generators, Docker, CI, supply chain	Risky modes
`references/validation-and-repair.md`	Audit, doctor, repair workflow	Audit/repair/doctor
`references/artifact-templates.md`	Skeletons and template guidance	Artifact generation

文件	用途	读取时机
`references/workflow.md`	端到端安全搭建流程	修改模式时
`references/capability-model.md`	功能 schema 及冲突语义	偏好设置/目录操作时
`references/presets.md`	预设方案及其权衡要点	选择预设时
`references/preference-catalog.md`	人类可读的偏好列表	`prefs` 命令、规划时
`references/adding-preferences.md`	未来偏好扩展流程	`prefs add` 命令、维护时
`references/intake-and-routing.md`	分类及模糊请求处理	自然语言输入时
`references/scaffold-profiles.md`	按预设分类的产物矩阵	生成蓝图时
`references/python-uv.md`	uv、uvx、pyproject、Python包相关内容	Python配置时
`references/node-pnpm-npm.md`	pnpm、npm/npx、TypeScript、Next、Astro、Nx、Changesets相关内容	Node配置时
`references/docs-starlight-react.md`	Starlight轻量/主题/交互式文档指南	轻量文档模式时
`references/docs-fumadocs.md`	Fumadocs产品级文档指南	产品级文档模式时
`references/design-system.md`	DESIGN.md及防冗余设计指南	Web/文档/设计配置时
`references/data-platforms.md`	Supabase、SQLite、DuckDB、Kaggle、Colab相关内容	数据/笔记本配置时
`references/ai-apps.md`	Pydantic AI、LangGraph、Vercel AI SDK、Bedrock、AgentCore相关内容	AI应用配置时
`references/github-ci-release.md`	Actions、发布、最小权限CI相关内容	GitHub模式时
`references/cloud-deploy-dns.md`	Vercel、Cloudflare DNS、AWS部署门禁相关内容	云模式时
`references/precommit-quality-gates.md`	pre-commit及CI镜像相关内容	质量门禁配置时
`references/conventional-commits-release.md`	Conventional Commits、Changesets、发布相关内容	发布配置时
`references/ai-agent-instructions.md`	AGENTS、嵌套AGENTS、Claude Code、OpenCode、Codex相关内容	AI指令模式时
`references/openspec-governance.md`	OpenSpec搭建及生成产物策略	OpenCode配置时
`references/security-supply-chain.md`	密钥、包生成器、Docker、CI、供应链相关内容	高风险模式时
`references/validation-and-repair.md`	审计、诊断、修复流程	审计/修复/诊断时
`references/artifact-templates.md`	骨架及模板指南	产物生成时

Script Index

脚本索引

Script	Purpose
`scripts/preferences.py`	List, validate, resolve, merge, and explain preferences
`scripts/preflight.py`	Read-only project detection and risk flags
`scripts/blueprint.py`	Build a JSON blueprint from request, preset, and capabilities
`scripts/validate_catalog.py`	Validate schemas, dependencies, conflicts, templates, and references
`scripts/validate_plan.py`	Validate blueprint safety before apply
`scripts/version_check.py`	Query package/version facts for selected packages
`scripts/doctor.py`	Verify existing scaffold health without mutations
`scripts/render_report.py`	Render report data for HTML templates

Scripts use

argparse

, JSON stdout, diagnostics on stderr, and

--help

. They must not read secret files.

脚本	用途
`scripts/preferences.py`	列出、验证、解析、合并及说明偏好设置
`scripts/preflight.py`	只读的项目检测及风险标记
`scripts/blueprint.py`	根据请求、预设及功能构建JSON蓝图
`scripts/validate_catalog.py`	验证schema、依赖、冲突、模板及参考文件的有效性
`scripts/validate_plan.py`	在应用前验证蓝图的安全性
`scripts/version_check.py`	查询所选包的版本信息
`scripts/doctor.py`	验证现有脚手架健康状态，不执行修改操作
`scripts/render_report.py`	为HTML模板渲染报告数据

脚本使用

argparse

、JSON标准输出、标准错误输出诊断信息，并支持

--help

。脚本不得读取机密文件。

Safety Gates

安全门禁

Preflight first for scaffold, bootstrap, repair, docs, AI, GitHub, cloud, or apply modes.
Blueprint before mutation or package install.
Skip existing files by default; overwrite requires file-by-file approval.
Preserve detected package managers unless migration is approved.
Never ask users to paste secrets into chat, and never read secret files.
Generate
```
.env.example
```
or
```
.env.template
```
, not real credentials.
Cloud, deploy, release, DNS, Docker, and account mutations require explicit provider-specific approval.
GitHub Actions default to
```
permissions: contents: read
```
; add only narrow permissions.
Docker Compose templates must avoid privileged mode, host networking, Docker socket mounts, broad host mounts, root services, and public DB binds by default.
Generated AI instructions must not bypass approvals, disable credential guards, auto-deploy, or ignore higher-priority instructions.

在脚手架、启动、修复、文档、AI、GitHub、云或应用模式下，先执行预检。
在执行修改或安装包前，先生成蓝图。
默认跳过现有文件；覆盖操作需要逐文件审批。
保留检测到的包管理器，除非迁移操作已获批。
绝不要要求用户在聊天中粘贴机密信息，也不要读取机密文件。
生成
```
.env.example
```
或
```
.env.template
```
，而非真实凭证。
云服务、部署、发布、DNS、Docker及账户变更操作需要明确的提供商专属审批。
GitHub Actions默认设置为
```
permissions: contents: read
```
；仅添加必要的窄权限。
Docker Compose模板默认禁止特权模式、主机网络、Docker套接字挂载、宽泛主机挂载、root服务及公共数据库绑定。
生成的AI指令不得绕过审批、禁用凭证防护、自动部署或忽略更高优先级的指令。

Critical Rules

关键规则

Use the capability catalog for stack selection; do not hardcode preferences only in prose.
Distinguish
```
uvx
```
one-off tools from
```
uv run
```
project commands.
Prefer
```
pnpm
```
for new Node projects, but preserve detected npm/yarn/bun unless migration is approved.
Prefer Starlight for lightweight docs; use Fumadocs only when product/API/docs-heavy requirements justify it.
Make Tailwind v4 and shadcn/ui opt-in outside web/product profiles; add only needed shadcn components.
Never claim
```
latest
```
without live registry or official-doc evidence gathered during the run.
Do not create agents or MCP servers; redirect those requests.
Do not create branches, worktrees, commits, pushes, releases, or PRs unless explicitly requested.
Mirror local quality gates in GitHub Actions or document why CI was deferred.
Include mobile-first responsive UI requirements in web/docs/design profiles.
Update evals when dispatch modes, presets, capabilities, or safety gates change.
Keep this body under 500 lines; move details to references.

使用功能目录选择技术栈；不要仅在文本中硬编码偏好设置。
区分
```
uvx
```
一次性工具与
```
uv run
```
项目命令。
新项目优先使用
```
pnpm
```
，但保留检测到的npm/yarn/bun，除非迁移操作已获批。
轻量文档优先使用Starlight；仅当产品/API/文档需求较重时，才使用Fumadocs。
在Web/产品配置外，Tailwind v4和shadcn/ui为可选功能；仅添加必要的shadcn组件。
若无运行时从注册表或官方文档获取的证据，不要声称使用
```
latest
```
版本。
不要创建Agent或MCP服务器；将此类请求重定向。
除非明确请求，否则不要创建分支、工作区、提交、推送、发布或PR。
在GitHub Actions中镜像本地质量门禁，或记录CI延迟的原因。
在Web/文档/设计配置中包含移动端优先的响应式UI要求。
当命令调度模式、预设、功能或安全门禁变更时，更新评估内容。
保持本文档在500行以内；将细节移至参考文件。

Validation Contract

验证契约

Before declaring changes to this skill complete, run:

bash

python skills/new-project/scripts/check.py
uv run pytest tests/test_new_project.py
uv run python skills/new-project/scripts/preflight.py --path . --format json

After changing skill definitions, public descriptions, references, or eval behavior, invoke

docs-steward

if available.

在宣布本技能的变更完成前，运行以下命令：

bash

python skills/new-project/scripts/check.py
uv run pytest tests/test_new_project.py
uv run python skills/new-project/scripts/preflight.py --path . --format json

在修改技能定义、公开描述、参考文件或评估行为后，若

docs-steward

可用，调用该工具。