用途
tl-docs-create 用于从零开始为任意代码库创建文档，提供 SSOT 驱动的生成方式、写作标准和模板。
适用场景包括：
- 用户提出“create documentation”“generate README”“create AGENTS.md”“start CHANGELOG”“document this codebase”等需求
- 启动需要文档的新项目
- 为尚未编写文档的代码库补充文档
- 创建 docs 文件夹结构
如需审计已有文档，应使用 tl-docs-audit。
主要能力
该技能可产出以下成果：
- 文档树：README、AGENTS.md、CHANGELOG、docs/ 文件夹、API 参考
- 用于持续文档维护的 Cursor 规则（可选）
- 根据项目和受众确定所需文档类型的决策
使用方式
配置发现
创建文档前，通过结构化问题收集用户意图。完整问题模式见 references/configuration.md。
问题流程概要：
- 轻量扫描——检查是否已有 docs/、README.md、AGENTS.md、CHANGELOG.md
- 是否已有文档？——若发现已有文档，建议改用 tl-docs-audit；否则继续
- 受众——贡献者 / 用户 / 运维人员 / 未来的自己 / 混合
- 范围——最小 / 标准 / 全面 / 极其详尽
- 文档类型——README / AGENTS.md / CHANGELOG / docs/ / API 参考 / 规则
- 规则——是否为文档维护创建 Cursor 规则？是 / 挑选 / 否
阶段 1：评估
在编写前先探索代码库，理解后再记录。
步骤 1：深入探索代码库
- 梳理目录组织和入口点
- 从 package.json、Gemfile、go.mod 等识别框架/语言
- 阅读部署配置、CI 配置、Docker 文件
- 检查数据库类型、迁移、种子数据
- 记录关键依赖和脚本
步骤 2：检测项目类型
| 类型 | 指标 | 文档重点 |
|---|---|---|
| Monorepo | pnpm-workspace.yaml、nx.json、多个 package.json | 各包 README、根概览 |
| Frontend | React/Vue/Angular 依赖、vite.config、next.config | 组件文档、部署 |
| Backend | Express/Fastify/Rails、API 路由 | API 参考、数据库模式 |
| Library | package.json 中的 main/exports、无应用代码 | API 文档、示例、变更日志 |
| CLI | bin 字段、commander/yargs 依赖 | 用法、选项、示例 |
步骤 3：识别受众
若上下文不明确，通过 AskQuestion 询问。受众影响语气、深度和文档类型。
阶段 2：文档类型选择
根据评估和用户回答，确定要创建的产物。
| 文档类型 | 何时需要 | 模板 |
|---|---|---|
| README.md | 始终 | templates/readme-project.md |
| AGENTS.md | AI 辅助开发 | templates/agents-md.md |
| CHANGELOG.md | 有版本发布 | templates/changelog.md |
| docs/ 文件夹 | 全面范围 | templates/readme-root.md |
| API 参考 | 后端/库项目 | templates/api-reference.md |
| 文档查看器 UI | 需要管理界面 | 见 tl-docs-viewer 技能 |
阶段 3：标准
应用 references/writing-standards.md 中的写作标准。
快速参考：
| 规则 | 说明 |
|---|---|
| 以“你”称呼 | 不用“我们”或被动语态 |
| 不用拉丁缩写 | 用“for example”而非“e.g.” |
| 序列逗号 | 始终使用牛津逗号 |
| 标题后加概述 | 每个标题都需要引导段落 |
| 简洁 | 开发者不阅读；多余文字等于信息损失 |
| 不指责 | 用“Input is invalid”而非“You provided wrong input” |
| 不做假设 | 避免“simply”和“just” |
阶段 4：执行
使用 references/templates/ 中的模板创建或更新文档。
每种文档类型：
- 加载相应模板
- 填入代码库特定内容
- 应用写作标准
- 在适用处添加来源归属
- 若用户选择创建规则，则创建 Cursor 规则
来源归属：
对于生成的文档（脚本、环境变量），添加页脚：
Source: path/to/source-file.ts
最后更新：
对于需要新鲜度跟踪的文档：
Last Updated: 2026-03-17
阶段 5：验证
完成前验证文档质量。
检查清单：
- 所有选定的文档类型已创建
- 已应用写作标准（对照 references/writing-standards.md）
- 内部链接已验证（相对路径存在）
- 无孤立文档（所有文档可从 README 或索引到达）
- Last Updated 日期为当前
验证命令（如可用）：
- pnpm lint 或项目的 lint 命令
- 若配置了链接检查器则运行
- agentskills validate 用于技能特定验证
自文档化
尽可能从代码生成文档。见 references/self-documentation.md。
脚本文档：
解析脚本头部以生成文档：
- 用法、选项、示例
- 环境变量
- 先决条件、相关内容
- 退出码、故障排除
环境变量：
从配置生成表格：
| 变量 | 服务 | 说明 | 示例 |
|---|---|---|---|
| DATABASE_URL | api | PostgreSQL 连接 | postgresql://... |
文档规则
可选地为持续维护创建 Cursor 规则。见 references/doc-rules.md。
可用规则：
- readme-sync.mdc——功能变更时更新 README
- changelog-commits.mdc——从约定式提交生成 CHANGELOG
- api-doc-sync.mdc——同步 API 文档与代码变更
- agents-md-maintain.mdc——保持 AGENTS.md 最新
- doc-style.mdc——强制执行文档风格
- last-updated.mdc——跟踪 Last Updated 日期
- link-check.mdc——验证内部文档链接
参考
技能参考：
| 文件 | 用途 |
|---|---|
| references/configuration.md | AskQuestion 流程和分支逻辑 |
| references/writing-standards.md | 语气、语调、格式规则 |
| references/self-documentation.md | SSOT 生成模式 |
| references/doc-types.md | README、AGENTS.md、CHANGELOG、API 模式 |
| references/docs-viewer.md | 指向 tl-docs-viewer-create 技能的参考 |
| references/doc-rules.md | 用于文档维护的 Cursor 规则 |
第一方文档：
- Keep a Changelog——CHANGELOG 格式标准
- MADR——Markdown 架构决策记录
- Diátaxis——文档框架（教程/操作指南/参考/解释）
- Conventional Commits——提交信息约定
- Write the Docs——文档社区风格指南
文档工具：
- TypeDoc——TypeScript API 文档生成器
- JSDoc——JavaScript 文档生成器
- OpenAPI——REST API 规范
相关技能：
- tl-docs-audit——审计文档覆盖、发现缺口、生成同步报告
- tl-docs-viewer-create——用于浏览 docs/ 文件夹的 React 管理界面
适用场景
- 新项目启动时需要建立文档体系
- 已有代码库但缺少文档，需要从零补充
- 需要生成 README、AGENTS.md、CHANGELOG、API 参考等标准文档
- 需要建立 docs/ 文件夹结构
- 需要为文档持续维护创建 Cursor 规则
限制
- 若已有文档，该技能建议改用 tl-docs-audit 进行审计，而非直接创建
- 文档查看器 UI 需参考 tl-docs-viewer 技能，本技能不直接提供
- 具体模板内容、写作标准细节、配置问题模式等需查阅对应 references 文件
- 关于收费、价格、平台支持等具体信息暂未提供