用途
本技能用于在基于 Basilic 的仓库中撰写、编辑和审阅技术文档,覆盖 Docu MDX、README 以及根目录产品 Markdown(如 PRODUCT.md、ARCHITECTURE.md、DESIGN.md)。目标读者是开发者与编码智能体,要求每个章节都易于扫描、检索和直接执行,不依赖未说明的上下文。
主要能力
- 撰写面向任务的技术文档,每页聚焦一个主要任务。
- 编辑与审阅现有文档,保持作者原有含义、细微差别与不确定性,做最小有效修改。
- 对照来源核实每一条声明,确保准确。
- 统一语气与用词:以“你”称呼读者,步骤使用祈使动词,主动语态、现在时、具体名词,美式英语并使用牛津逗号;命名运行时 eve 时使用小写。
- 禁用填充与夸张词(easy、simple、quick、just、obviously、utilize、facilitate、leverage、robust、seamless、促销性形容词、反问句、诱导互动内容),并禁用 AI 痕迹(总结式过渡、断续片段、数据表式动词、无先行词的开头、模板式结尾、为显得像人而制造的细节)。
- 支持三种文档模式:Docu MDX、README、根产品 Markdown。
使用方式
写作前先阅读所在仓库的 AGENTS.md,了解文档分层、公开一句话介绍、能力名称、禁用文案以及 DESIGN.md 的位置。.cursor/rules/ 中的 Glob 规则优先于本技能。若不确定应更新哪一层(MDX、README 还是规则),使用 /w-docs,不要在本技能中重复其路由表。
来源核实顺序:
- 仓库中拥有该行为的源码、公开类型与测试;
- 最近 README 中提到的 CLI 帮助与包脚本;
- AGENTS.md 指定文档层中已有的 MDX 或 Markdown;
- ADR 与架构页面——在合并行为匹配之前仅视为提案意图;
- Issue 与用户报告——用于了解读者问题,不作为产品事实依据。
若某条声明无法核实,应省略或注明缺失的负责人。完成稿中不得保留 [VERIFY]。不得将提案行为记录为已发布行为。
方法步骤:
- 明确该篇文档的唯一任务与读者的任务。
- 找到已拥有该主题的页面,优先扩展而非新建页面。
- 列提纲:结果 → 前置条件 → 顺利路径 → 替代方案 → 失败情况 → 相关链接。
- 起草与核实声明同步进行。
- 自编辑以利于检索:关键陈述中重复完整名词,把关键事实放在本地而非仅藏在链接后。
- 多轮审阅:目的与结构、准确性、完整性、风格与检索、diff 纪律(不做顺手重写)。
三种模式的具体要求:
- Docu MDX(当仓库有 apps/docu/content/docs/ 时):使用 title 与 description frontmatter;导航变化时更新文件夹 meta.json;从相关枢纽页加入正文链接(避免孤立页面);路由移动时在 doc 应用配置中设置永久重定向;仅在邻近页面已使用时才使用 MDX 组件。准备发布文档变更时,以 pnpm --filter @repo/docu checktypes 收尾。
- README(**/README.md):遵循 .cursor/rules/base/readme.mdc——根 README 负责产品故事,应用与包保持精简并链接到技术文档。
- 根产品 Markdown(如 PRODUCT.md、ARCHITECTURE.md,以及 AGENTS.md 指定的 DESIGN.md):使用相同语气;能力名称与该仓库架构来源一致;仅当 AGENTS.md 说明上游托管文档覆盖本地项目文档时,才以上游为准。
适用场景
适用于在 Basilic 系仓库中新增或更新 Docu MDX 页面、README、根产品 Markdown;也适用于审阅已有技术文档的准确性、结构与检索性。
限制
- 绝不虚构标志、端点、默认值、示例、指标或用户反应。
- 绝不将单个支持线程直接变成新页面,除非先确定属于文档范围还是产品范围。
- 当某个章节或交叉链接即可弥补缺口时,绝不重复编写宽泛指南。
- 绝不为了叙事方便而违背所在仓库的公开一句话介绍、禁用文案或能力名称。
- 支持证据只能说明存在困惑;行为由实现与测试确立。
本技能不负责:/w-docs(决定修补哪一层)、/w-api-docs(OpenAPI 与生成客户端)、/w-deslop(分支上的代码 slop)、/w-architecture(ADR 与边界规划)、个人或营销语气目录(如 gabo)。