bootstrap-project-documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Bootstrap Project Documentation

技能：项目文档初始化搭建

Purpose

用途

Bootstrap or adapt project documentation using the project-documentation-template structure. Two modes: Initialize (empty project—copy templates and fill placeholders) and Adjust (non-empty—use template as target, propose renames/moves/merges, apply in-place after confirmation). Supports repeatable runs; avoids empty dirs and template files unless requested; enforces strict kebab-case naming. Both modes follow conventions from the template's

llms.txt

and

AGENTS.md

使用project-documentation-template结构初始化或适配项目文档，支持两种模式：初始化（空项目——复制模板并填充占位符）和调整（非空项目——以模板为目标，提议重命名/移动/合并操作，经确认后就地执行变更）。支持重复运行；除非明确要求，否则不会生成空目录和模板文件；严格执行kebab-case命名规范。两种模式均遵循模板中

llms.txt

和

AGENTS.md

约定的规则。

Core Objective

核心目标

Primary Goal: Produce structured lifecycle documentation aligned with the enterprise template through mode-appropriate bootstrapping or adaptation.

Success Criteria (ALL must be met):

✅ Mode selected correctly: Initialize for empty projects, Adjust for non-empty projects (or user override applied)
✅ Template structure applied: Documentation follows project-documentation-template conventions for selected scale
✅ Placeholders filled: All
```
[...]
```
placeholders replaced with project-specific content (or explicitly marked for later)
✅ Naming conventions enforced: All paths use strict kebab-case; ADR files follow
```
YYYYMMDD-slug-title.md
```
format
✅ User confirmation obtained: In Adjust mode, changes applied only after user approval of recommendation list

Acceptance Test: Can a developer navigate the documentation structure and find lifecycle documents without consulting the template repository?

首要目标：通过适配对应模式的初始化或适配流程，生成符合企业模板规范的结构化生命周期文档。

成功标准（必须全部满足）：

✅ 模式选择正确：空项目使用初始化模式，非空项目使用调整模式（或用户指定覆盖默认规则）
✅ 模板结构落地：文档符合对应规模的project-documentation-template约定
✅ 占位符填充完成：所有
```
[...]
```
占位符已替换为项目特定内容（或明确标记为后续补充）
✅ 命名规范落地：所有路径严格遵循kebab-case；ADR文件遵循
```
YYYYMMDD-slug-title.md
```
格式
✅ 获得用户确认：调整模式下，所有变更仅在用户批准推荐列表后执行

验收测试：开发人员无需查阅模板仓库，即可通过文档结构导航找到所需的生命周期文档？

Scope Boundaries

边界范围

This skill handles:

Documentation structure bootstrapping (Initialize mode)
Documentation structure adaptation (Adjust mode)
Placeholder filling and validation
Path naming standardization (kebab-case)
ADR generation and indexing

This skill does NOT handle:

README generation (use
```
generate-standard-readme
```
)
AGENTS.md entry creation (use
```
write-agents-entry
```
)
Skill-specific documentation (use
```
refine-skill-design
```
)
Content writing beyond template placeholders (user provides domain content)

Handoff point: When documentation structure is established and placeholders filled, hand off to content authoring or project-specific documentation workflows.

本技能可处理：

文档结构初始化（初始化模式）
文档结构适配（调整模式）
占位符填充与校验
路径命名标准化（kebab-case）
ADR生成与索引更新

本技能不处理：

README生成（使用
```
generate-standard-readme
```
）
AGENTS.md条目创建（使用
```
write-agents-entry
```
）
技能专属文档（使用
```
refine-skill-design
```
）
模板占位符之外的内容编写（由用户提供领域内容）

交接节点：当文档结构搭建完成且占位符填充完毕后，交接给内容创作或项目专属文档工作流。

Use Cases

适用场景

Empty project: Initialize a full docs skeleton by copying template subsets and filling placeholders for small/medium/large projects.
Non-empty project: Use the template as target reference; analyze existing docs, propose renames/moves/merges to align structure and naming; apply in-place changes after user confirmation. Do not create empty dirs or template files unless requested. Can be run repeatedly.
Shared workflows: Generate Architecture Decision Records (ADR), update version information across docs, validate placeholders and links.
Iterative runs: Run the skill repeatedly to progressively organize and refine docs; each run builds on the current state without requiring a full reinit.

When to use: When a project needs structured lifecycle documentation aligned with the enterprise template, or when existing docs should be aligned with that structure.

空项目：根据项目规模（小/中/大）复制对应模板子集、填充占位符，生成完整的文档骨架。
非空项目：以模板为参考基准，分析现有文档，提议重命名/移动/合并操作以对齐结构和命名规范，经用户确认后就地执行变更。除非明确要求，否则不会创建空目录或模板文件，支持重复运行。
共享工作流：生成架构决策记录（ADR）、更新全文档的版本信息、校验占位符和链接。
迭代运行：可重复运行技能逐步组织和优化文档，每次运行基于当前状态执行，无需完整重新初始化。

适用时机：当项目需要符合企业模板规范的结构化生命周期文档，或现有文档需要对齐该结构时使用。

Behavior

运行逻辑

Mode Selection

模式选择

First determine the execution mode. User override takes precedence; otherwise:

Mode	Trigger	Behavior
Initialize	No `docs/` or `docs/` empty	Copy subset, fill placeholders, create `VERSION` , output docs skeleton
Adjust	`docs/` has ≥1 valid document	Scan, compare, output recommendation list; apply after user confirmation

Detection rules:

No
```
docs/
```
or
```
docs/
```
is empty → Initialize
```
docs/
```
exists and has ≥1 valid
```
.md
```
file → Adjust
User explicitly specifies
```
--mode=initialize
```
or
```
--mode=adjust
```
→ use that mode

首先确定执行模式，用户指定的模式优先级最高，否则按以下规则判断：

模式	触发条件	运行逻辑
初始化	无 `docs/` 目录或 `docs/` 为空	复制对应模板子集、填充占位符、创建 `VERSION` 文件、输出文档骨架
调整	`docs/` 目录下存在至少1份有效文档	扫描、对比、输出推荐变更列表；经用户确认后执行变更

检测规则：

无
```
docs/
```
目录或
```
docs/
```
为空 → 初始化模式
```
docs/
```
目录存在且包含至少1份有效
```
.md
```
文件 → 调整模式
用户明确指定
```
--mode=initialize
```
或
```
--mode=adjust
```
→ 按用户指定模式运行

Initialize Mode Steps

初始化模式步骤

Determine project scale: small, medium, or large (from user or context).
Select the document subset from the template by scale:
- Small: Project Overview, Development Guide, User Guide
- Medium: + Architecture, Design, Requirements & Planning
- Large: + Process Management, Operations Guide, Compliance, Community & Contributing
Fetch templates from
```
TEMPLATE_BASE_URL
```
(see Appendix) or use a local clone.
Copy only selected docs to the project
```
docs/
```
. Do not create empty directories or placeholder files unless the user explicitly requests them.
Fill placeholders with project metadata (name, dates, tech stack) and prompt for missing critical data.
Create a
```
VERSION
```
file (e.g.
```
1.0.0
```
) unless the user explicitly requests no new files.
Validate: no unreplaced placeholders, links valid, tables aligned.

确定项目规模：小、中、大（从用户输入或上下文推断）。
根据规模从模板中选择对应文档子集：
- 小型项目：项目概览、开发指南、用户指南
- 中型项目：新增架构、设计、需求与规划模块
- 大型项目：新增流程管理、运维指南、合规、社区与贡献模块
从
```
TEMPLATE_BASE_URL
```
（见附录）拉取模板，或使用本地克隆的模板。
仅将选中的文档复制到项目
```
docs/
```
目录下，除非用户明确要求，否则不创建空目录或占位符文件。
用项目元数据（名称、日期、技术栈）填充占位符，缺失的关键信息提示用户补充。
除非用户明确要求不生成新文件，否则创建
```
VERSION
```
文件（例如
```
1.0.0
```
）。
校验：无未替换的占位符、链接有效、表格对齐。

Adjust Mode Steps

调整模式步骤

Use project-documentation-template as the target reference for structure, conventions, and file/directory names.
Scan existing docs under
```
docs/
```
(structure, placeholders, links, versions).
Compare to the template and identify gaps:
- Structure and path mismatches (nonstandard dir/file names)
- Documents alignable to template (rename, move, or merge)
- Unfilled placeholders, broken links, version inconsistencies
Produce a recommendation list and present it to the user; ask for confirmation before applying.
After confirmation, apply changes in-place to existing files. Do not create empty directories or add template files unless the user explicitly requests them.
The skill is idempotent: it can be run repeatedly to iteratively organize and refine docs.

以project-documentation-template作为结构、规范、文件/目录命名的目标参考。
扫描
```
docs/
```
下的现有文档（结构、占位符、链接、版本）。
与模板对比识别差距：
- 结构和路径不匹配（非标准目录/文件名）
- 可对齐到模板的文档（重命名、移动或合并）
- 未填充的占位符、无效链接、版本不一致
生成推荐变更列表提交给用户，申请确认后再执行变更。
确认后对现有文件就地执行变更，除非用户明确要求，否则不创建空目录或添加模板文件。
本技能是幂等的：可重复运行以迭代组织和优化文档。

Conventions (from llms.txt)

通用规范（来自llms.txt）

Placeholders:

[description]

[option1/option2]

YYYY-MM-DD

[number]

Tables: Preserve column alignment;
```
*
```
marks required fields
Version: Use SemVer; update version history at document bottom on changes
References: Internal
```
[Name](relative/path)
```
; external
```
number
```
Dates:
```
YYYY-MM-DD
```

占位符：

[description]

、

[option1/option2]

、

YYYY-MM-DD

、

[number]

表格：保留列对齐；
```
*
```
标记必填字段
版本：使用SemVer规范；变更时更新文档底部的版本历史
引用：内部链接使用
```
[名称](相对路径)
```
；外部链接使用
```
数字
```
标记
日期：使用
```
YYYY-MM-DD
```
格式

File and directory naming (strict)

文件和目录命名规则（严格执行）

Directories:

kebab-case

only (e.g.

project-overview

development-guide

process-management

)

Files:

kebab-case

with

.md

extension (e.g.

goals-and-vision.md

versioning-standards.md

)

ADR files:

YYYYMMDD-slug-title.md

(e.g.

20250225-process-management-strategy.md

)

No spaces, underscores, or PascalCase; lowercase letters, digits, hyphens only.

目录：仅使用

kebab-case

格式（例如

project-overview

、

development-guide

、

process-management

）

文件：

kebab-case

格式加

.md

后缀（例如

goals-and-vision.md

、

versioning-standards.md

）

ADR文件：

YYYYMMDD-slug-title.md

格式（例如

20250225-process-management-strategy.md

）

不允许使用空格、下划线或PascalCase，仅可使用小写字母、数字和连字符。

Input & Output

输入与输出

Input

输入

Project metadata: Name, description, tech stack
Scale: small | medium | large (optional; infer from context if absent)
Mode override (optional):
```
initialize
```
|
```
adjust
```

项目元数据：名称、描述、技术栈
规模：small | medium | large（可选，未提供时从上下文推断）
模式覆盖（可选）：
```
initialize
```
|
```
adjust
```

Output

输出

Initialize: Filled docs under
```
docs/
```
,
```
VERSION
```
, and a short summary of created files
Adjust: A recommendation list (markdown or structured), then—after confirmation—the applied changes and summary

初始化模式：
```
docs/
```
下填充完成的文档、
```
VERSION
```
文件、创建文件的简短摘要
调整模式：推荐变更列表（markdown或结构化格式），确认后输出已执行变更和摘要

Restrictions

约束规则

Hard Boundaries

硬性边界

Replace all placeholders before finalizing documents; do not leave
```
[description]
```
etc. in final output unless explicitly deferred.
Do not add or keep broken internal links; verify relative paths.
Use consistent dates (
```
YYYY-MM-DD
```
) and SemVer for versions.
In Adjust mode, do not apply changes without user confirmation.
Do not remove structural elements (sections, tables) from templates without user approval.
Do not create empty directories or add template files unless the user explicitly requests them.
Use strict file and directory naming (kebab-case, ADR format
```
YYYYMMDD-title.md
```
) when creating or renaming paths.

最终交付文档前替换所有占位符，除非明确标记为延期补充，否则最终输出中不得保留
```
[description]
```
等占位符。
不得添加或保留无效内部链接，校验相对路径有效性。
使用统一的日期格式（
```
YYYY-MM-DD
```
）和SemVer版本规范。
调整模式下，未获得用户确认不得执行任何变更。
未经用户批准不得移除模板中的结构元素（章节、表格）。
除非用户明确要求，否则不得创建空目录或添加模板文件。
创建或重命名路径时严格遵循文件和目录命名规范（kebab-case，ADR使用
```
YYYYMMDD-title.md
```
格式）。

Skill Boundaries (Avoid Overlap)

技能边界（避免功能重叠）

Do NOT do these (other skills handle them):

README generation: Creating or updating README.md files → Use
```
generate-standard-readme
```
AGENTS.md entry creation: Writing or updating AGENTS.md files → Use
```
write-agents-entry
```
Skill documentation: Creating or refining SKILL.md files → Use
```
refine-skill-design
```
Content authoring: Writing domain-specific content beyond template placeholders → User provides content

When to stop and hand off:

User says "structure is ready" or "placeholders filled" → Documentation structure complete, hand off to content authoring
User asks "how do I write the content?" → Structure complete, hand off to domain experts or content workflows
User asks "can you generate the README?" → Hand off to
```
generate-standard-readme
```
User asks "can you create AGENTS.md?" → Hand off to
```
write-agents-entry
```

请勿执行以下操作（由其他技能负责）：

README生成：创建或更新README.md文件 → 使用
```
generate-standard-readme
```
AGENTS.md条目创建：编写或更新AGENTS.md文件 → 使用
```
write-agents-entry
```
技能文档：创建或优化SKILL.md文件 → 使用
```
refine-skill-design
```
内容创作：编写模板占位符之外的领域专属内容 → 由用户提供内容

停止运行并交接的触发条件：

用户表示「结构已就绪」或「占位符已填充」→ 文档结构完成，交接给内容创作流程
用户询问「我该怎么编写内容？」→ 结构完成，交接给领域专家或内容工作流
用户询问「你能生成README吗？」→ 交接给
```
generate-standard-readme
```
技能
用户询问「你能创建AGENTS.md吗？」→ 交接给
```
write-agents-entry
```
技能

Self-Check

自检清单

Core Success Criteria (ALL must be met)

核心成功标准（必须全部满足）

Mode selected correctly: Initialize for empty projects, Adjust for non-empty projects (or user override applied)
Template structure applied: Documentation follows project-documentation-template conventions for selected scale
Placeholders filled: All
```
[...]
```
placeholders replaced with project-specific content (or explicitly marked for later)
Naming conventions enforced: All paths use strict kebab-case; ADR files follow
```
YYYYMMDD-slug-title.md
```
format
User confirmation obtained: In Adjust mode, changes applied only after user approval of recommendation list

模式选择正确：空项目使用初始化模式，非空项目使用调整模式（或用户指定覆盖默认规则）
模板结构落地：文档符合对应规模的project-documentation-template约定
占位符填充完成：所有
```
[...]
```
占位符已替换为项目特定内容（或明确标记为后续补充）
命名规范落地：所有路径严格遵循kebab-case；ADR文件遵循
```
YYYYMMDD-slug-title.md
```
格式
获得用户确认：调整模式下，所有变更仅在用户批准推荐列表后执行

Process Quality Checks

流程质量校验

Links validated: Do internal links resolve and do external links point to valid resources?
Version consistency: Is the version consistent across
```
VERSION
```
and affected documents?
Tables aligned: Is Markdown table alignment preserved?
No extra dirs/files: Were empty dirs and template files avoided unless user requested them?

链接校验：内部链接可正常跳转，外部链接指向有效资源？
版本一致性：
```
VERSION
```
文件和关联文档的版本信息是否一致？
表格对齐：Markdown表格对齐格式是否保留？
无多余目录/文件：除非用户要求，否则未生成空目录和模板文件？

Acceptance Test

验收测试

Can a developer navigate the documentation structure and find lifecycle documents without consulting the template repository?

If NO: Documentation structure is incomplete or unclear. Return to mode-specific steps.

If YES: Documentation structure is complete. Proceed to handoff.

开发人员无需查阅模板仓库，即可通过文档结构导航找到所需的生命周期文档？

如果答案为否：文档结构不完整或不清晰，返回对应模式的执行步骤重新调整。

如果答案为是：文档结构完整，进入交接流程。

Examples

示例

Example 1: Initialize (Empty Project, Small Scale)

示例1：初始化（空项目，小型规模）

Context: New repo

my-service

, no

docs/

directory.

Steps: Agent selects Initialize; scale = small. Copies Project Overview, Development Guide, User Guide from template. Fills project name, dates, placeholder descriptions. Creates

VERSION

1.0.0

. Outputs a summary of created files.

Output snippet:

docs/project-overview/goals-and-vision.md

docs/development-guide/...

docs/user-guide/...

VERSION

. All placeholders filled with project-specific content.

上下文：新仓库

my-service

，无

docs/

目录。

步骤：Agent选择初始化模式；规模=小型。从模板复制项目概览、开发指南、用户指南，填充项目名称、日期、占位符描述，创建

VERSION

文件为

1.0.0

，输出创建文件的摘要。

输出片段：

docs/project-overview/goals-and-vision.md

、

docs/development-guide/...

、

docs/user-guide/...

、

VERSION

，所有占位符已填充为项目专属内容。

Example 2: Adjust (Non-Empty Project)

示例2：调整（非空项目）

Context: Repo has

docs/

with

project_overview/goals.md

(nonstandard paths). Some placeholders unfilled.

Steps: Agent selects Adjust. Uses project-documentation-template as target. Produces recommendation list:

Rename

project_overview/

→

project-overview/

goals.md

→

goals-and-vision.md

(kebab-case, match template)

Unfilled placeholders in

goals-and-vision.md

[project description]

[target date]

Broken link:
```
../architecture/tech-stack.md
```
(path does not exist)

Agent presents the list and asks: "Apply these changes? (Y/n)". User confirms. Agent renames dirs/files, fixes placeholders and links in-place. No new empty dirs or template files created.

上下文：仓库

docs/

目录下存在

project_overview/goals.md

（非标准路径），部分占位符未填充。

步骤：Agent选择调整模式，以project-documentation-template为目标参考，生成推荐变更列表：

重命名

project_overview/

→

project-overview/

、

goals.md

→

goals-and-vision.md

（kebab-case格式，对齐模板）

goals-and-vision.md

中未填充的占位符：

[project description]

、

[target date]

无效链接：
```
../architecture/tech-stack.md
```
（路径不存在）

Agent展示列表并询问：「是否应用这些变更？(Y/n)」，用户确认后，Agent就地重命名目录/文件，修复占位符和链接，未创建新的空目录或模板文件。

Example 3: Common Workflow—Generate ADR

示例3：通用工作流——生成ADR

Context: Any project; user needs an Architecture Decision Record.

Steps: Agent fetches

docs/process-management/decisions/ADR-TEMPLATE.md

from template. Determines next ADR number (e.g. ADR-001). Fills context, options, rationale, consequences with user input. Saves as

docs/process-management/decisions/YYYYMMDD-decision-title.md

(kebab-case slug) and updates the decision index if present.

上下文：任意项目，用户需要生成架构决策记录。

步骤：Agent从模板拉取

docs/process-management/decisions/ADR-TEMPLATE.md

，确定下一个ADR编号（例如ADR-001），根据用户输入填充上下文、可选方案、决策依据、影响，保存为

docs/process-management/decisions/YYYYMMDD-decision-title.md

（kebab-case短标题），如果存在决策索引则同步更新。

Appendix: Output Contract

附录：输出约定

Initialize Mode

初始化模式

Deliverable	Required
`docs/` with selected template files only (no empty dirs)	Yes
`VERSION` file	Yes (unless user explicitly requests no new files)
All placeholders replaced (or marked for later)	Yes
Version history table at document bottom	Per template

交付物	是否必填
仅包含选中模板文件的 `docs/` 目录（无空目录）	是
`VERSION` 文件	是（除非用户明确要求不生成新文件）
所有占位符已替换（或标记为后续补充）	是
文档底部的版本历史表格	遵循模板要求

Adjust Mode Recommendation List Format

调整模式推荐列表格式

Section	Content
Target reference	project-documentation-template
Path/naming issues	Current path → recommended path (kebab-case, template alignment)
Alignable documents	Existing docs that can be renamed/moved/merged to match template
Unfilled placeholders	File path + placeholder text
Broken/outdated links	File path + link
Version issues	Conflicts or missing version refs

板块	内容
目标参考	project-documentation-template
路径/命名问题	当前路径 → 推荐路径（kebab-case，对齐模板）
可对齐文档	可通过重命名/移动/合并匹配模板的现有文档
未填充占位符	文件路径 + 占位符内容
无效/过期链接	文件路径 + 链接
版本问题	冲突或缺失的版本引用

Template Source

模板来源

TEMPLATE_BASE_URL (canonical):

https://raw.githubusercontent.com/nesnilnehc/project-documentation-template/main/

Key files:
```
llms.txt
```
,
```
AGENTS.md
```
,
```
README.md
```
,
```
docs/
```
If fetch fails (network unavailable): prompt the user to provide a local clone path or retry later; do not proceed with stale or missing templates.

TEMPLATE_BASE_URL（官方地址）：

https://raw.githubusercontent.com/nesnilnehc/project-documentation-template/main/

关键文件：
```
llms.txt
```
、
```
AGENTS.md
```
、
```
README.md
```
、
```
docs/
```
如果拉取失败（网络不可用）：提示用户提供本地克隆路径或稍后重试，不得使用过期或缺失的模板继续运行。