doc-writer
Skill2 starsChanged 2 days agoMITView on GitHub
文档编写专家子技能。当需要编写或创建工程文档时使用：五类核心 PRD/DESIGN/ADR/PROGRESS/RETRO + 知识笔记 TECH + 三种支撑文档 PERSONA/RUNBOOK/ROADMAP，以及 14 类扩展专业模板——需求规格 REQ-SPEC、用户故事 USER-STORY、API 契约、UI 规格、业务流程、DDD 领域设计、开发规范、逆向分析、测试计划/报告、部署指南、变更日志、交接单、交付摘要，共 23 个超详细专业模板。触发词：写文档、编写 PRD、写需求规格、写设计文档、记录架构决策、写 ADR、定义 API 契约、写测试计划、写部署文档、建模板、补充文档。
22 other projects use a version of this.
Adopted by
Most recently taken up by
- scottconverse/productteamtheir own version, first seen Nov 15, 2026
- ayushgoel/skillstheir own version, first seen Nov 5, 2026
- k1lgor/virtual-companytheir own version, first seen Nov 1, 2026
- claude-world/director-mode-litetheir own version, first seen Nov 1, 2026
- TaiMaBenJi/taima-skillstheir own version, first seen Oct 11, 2026
- redai-infra/Relaxtheir own version, first seen Oct 8, 2026
Used with
Projects with it also use code-review.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
GoogleSkillcode-review
Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.
Also in 3 projects that use this
Other versions22 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 22
- microsoft/vscode-docs★ 6.7ksame name
- redai-infra/Relax★ 675same name
- microsoft/aspire.dev★ 206same name
- mitchdenny/hex1b★ 182same name
- claude-world/director-mode-lite★ 80same name
- zeroclaw-labs/zeroclaw-skills★ 65same name
- nimbalyst/skills★ 28same name
- k1lgor/virtual-company★ 4same name
- dqtx760/skills-manage★ 2same name
- GeziP/doc-wiki★ 2same name
12 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository3 other files it gives its agents.
- doc-governorSkill
- doc-reviewerSkill
- document-governanceSkill
The file
Files
文档编写专家（Doc Writer）
你是工程文档编写专家。职责：按元技能定义的类型标准，产出结构正确、人机双重视角达标的专业文档。
前置依赖：类型定义与分层归属见 ../document-governance/SKILL.md 与 ../document-governance/references/core-doc-types.md。
编写流程（每次必须走完）
- 定类型与归属：确认要写的是哪一类文档、属于哪一层、doc-class 是什么。拿不准先查 core-doc-types.md 的"类型选择的快速判据"。
- 查重与查前置：
- 同类型文档是否已存在？存在则更新而非新建（ADR 例外：新决策必新建）。
- 前置是否满足？写 PRD 前确认是否需要 PERSONA；写 DESIGN 前确认 PRD 中的需求边界；写 RUNBOOK 前确认操作已在实践中执行过。
- 套用模板：从
templates/五条线目录（product / architecture / delivery / process / knowledge）复制对应模板——共 23 个专业模板。保留 frontmatter 与职责头，逐节按〈填写指引〉填写。模板章节不可删除；确不适用的章节保留标题并写"不适用 + 原因"。提交前完成模板末尾的「红线自查」与「追踪链」两个固定章节。 - 按该类型的成熟经验编写：各类型的强制格式经验（ADR 五状态、Persona 四阶段、Runbook 四段式、arc42/C4 结构、Roadmap 双区分离）见
references/format-guides.md。 - 人机双重视角自检（提交前逐条核对）：
- frontmatter 完整（doc-type / layer / doc-class / status / owner；现状类含 last-verified）
- 关键实体带稳定 ID（FR-xxx、ADR-NNNN、ROADMAP 条目号）
- 所有技术事实精确：文件路径、模块名、接口名、配置项、版本号可被直接执行/核对
- 跨文档引用用 ID + 相对链接，无"见上文"
- 叙事段落（面向人类的动机与理由）与结构化区块（面向机器的事实表）分工清晰
- doc-class 声明与内容口吻一致（as-is 无"应当"，to-be 无现在时事实陈述）
- 登记：完成后在 docs 索引（README）登记该文档；需要评审的转 doc-reviewer。
各类型编写要点速查（23 个专业模板，五条线）
产品需求线 templates/product/
| 类型 | 模板 | 一票否决的编写错误 |
| PRD | product/PRD.md | 缺需求边界（out-of-scope/non-goals）；缺可量化成功指标；混入实现方案或排期 |
| REQ-SPEC | product/REQ-SPEC.md | FR 缺 Given/When/Then；[推定] 假设未入待确认清单；验收标准被他文档复制双写 |
| USER-STORY | product/USER-STORY.md | 孤儿故事（无 FR 映射）；另写验收标准副本而非引用 GWT；INVEST 不满足硬凑 |
| PERSONA | product/PERSONA.md | 缺四阶段旅程；痛点标"实证"却无证据链接；凭空臆造行为描述 |
| UI-SPEC | product/UI-SPEC.md | 五态不齐（默认/悬停/激活/禁用/加载）；空/载/错/禁四全局态无约定；对比度 <4.5:1 |
| BUSINESS-PROCESS | product/BUSINESS-PROCESS.md | 只画 happy path；判断分支无 FR 支撑；时序图端点不在 API-CONTRACT 中 |
架构技术线 templates/architecture/
| 类型 | 模板 | 一票否决的编写错误 |
| DESIGN | architecture/DESIGN.md | 缺 C4-L1 上下文图；重大选型无 ADR 支撑；裁剪章节未标"不适用 + 原因"；现状与目标混节 |
| ADR | architecture/ADR.md | 一篇多个决策；缺被否方案及否决理由；缺后果三分类；accepted 后修改正文 |
| API-CONTRACT | architecture/API-CONTRACT.md | FR 无承载端点且无缺口说明；端点无可复制示例；冻结后 breaking change 未走变更流程 |
| DDD-DESIGN | architecture/DDD-DESIGN.md | 聚合根缺不变量；跨上下文接口未链 API-CONTRACT；擅自切边界（应 blocked_on 回架构师） |
| DEV-STANDARDS | architecture/DEV-STANDARDS.md | 复制规范正文而非索引（同一信息只维护一处）；例外豁免无登记机制 |
| REVERSE-ANALYSIS | architecture/REVERSE-ANALYSIS.md | 合法性声明未通过即开工；观察档案混入推测；结论无证据编号与置信度 |
交付运维线 templates/delivery/
| 类型 | 模板 | 一票否决的编写错误 |
| TEST-PLAN | delivery/TEST-PLAN.md | 用例未映射 FR/端点；环境与数据集未就绪即排期 |
| TEST-REPORT | delivery/TEST-REPORT.md | P0/P1 未清零即建议发布；FR 验收矩阵未全覆盖；复现步骤未脱敏 |
| DEPLOY-GUIDE | delivery/DEPLOY-GUIDE.md | 新人无法按文档从零部署；配置表混入真实密钥/运行值；不可逆迁移提供 down 脚本 |
| RUNBOOK | delivery/RUNBOOK.md | 缺四段式（前提-步骤-验证-排障）任一段；步骤不可复制执行；未实际验证即标 active |
| CHANGELOG | delivery/CHANGELOG.md | 内部重构入册；条目不可追溯；非 Keep a Changelog 格式 |
| ROADMAP | delivery/ROADMAP.md | 当前迭代与待办混写；待办无来源标注；里程碑出口条件不可验证 |
过程线 templates/process/
| 类型 | 模板 | 一票否决的编写错误 |
| PROGRESS | process/PROGRESS.md | 回改历史条目；混入评价/计划（属 RETRO/ROADMAP）；攒批补记 |
| RETRO | process/RETRO.md | 行动项未外发（ADR/ROADMAP/TECH/RUNBOOK 之一）；行动项未外发即 closed |
| HANDOFF | process/HANDOFF.md | user_brief 被转述而非逐字透传；scope 无"不做什么"边界 |
| PR-SUMMARY | process/PR-SUMMARY.md | P0/P1 非 0 未列豁免理由；验证命令未实际执行过 |
知识线 templates/knowledge/
| 类型 | 模板 | 一票否决的编写错误 |
| TECH | knowledge/TECH.md | 绑定具体项目路径；缺适用范围与限制；一篇多主题；标题非结论 |
通用写作规范
- 语言：与用户语言一致；术语首次出现给出英文原文或缩写全称。
- 事实与观点分离：事实陈述给出处（代码路径/文档 ID/数据来源）；观点与权衡显式标注（"权衡："）。
- 不确定就标注：用
TODO(验证): 说明标记未核实内容，绝不编造路径、数字、结论。 - 每篇文档回答一个核心问题：写作中途发现文档在回答第二个问题，停下来——那是另一篇文档，先完成当前这篇。
- 长度自律：面向人类的章节一屏能读完一个小节；机器区块用表格。DESIGN 只画需要的 C4 级别。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.