该技能把项目文档视为人类理解与自动化 AI 执行之间的接口,目标不是产出冗长报告,而是以可快速阅读、无需猜测即可执行的形式保存项目状态。
用途:当用户要求记录、保存、整理、更新或维护项目文档时使用,包括计划文档、待办文档、临时记录等。
核心流程:先确定文档根目录,再对内容分类,创建或更新对应文档,以简洁、事实化、可读的叙事风格书写;写入后重读全文并执行写后检查(可读性、结构一致性、必需模块完整性、证据、结论与下一步);除非用户选择跳过,随后按 references/post-write-polish.md 执行通俗化润色。涉及可复用命令时更新 常用命令.txt,命令写为单行,且不对命令行做润色。
文档根目录:优先使用用户指定路径;未指定则用 <project-root>/docs,<project-root> 尽量解析为当前仓库根目录,无仓库时用当前工作目录。需保证目录包含 plan/、todo/、experiment/、knowhow/、roadmap/ 与 常用命令.txt,缺失时创建,不重命名已有目录。
分类规则:plan/ 放实施计划、任务拆解、技术方案、迁移方案、执行前风险分析等面向未来的内容;todo/ 放轻量、持续演进的待办队列与未决状态,如临时想法、需跟进风险、下一步行动、开放问题;experiment/ 放证据与结果,如实验设置、指标、基准结果、消融对比、回归记录、数据表与结论;knowhow/ 放可复用知识,如调试配方、坑与根因、运维流程、环境约定、部署经验;roadmap/ 放较长周期方向,如里程碑、阶段计划、长期优先级、版本策略。
命名与更新:Markdown 文档使用 YYYYMMDD_简短标题.md,日期与标题用下划线连接,标题简短可描述,例如 20260429_端侧内存优化方案.md,日期取环境当前日期或用户指定日期。新内容优先新建带日期文档;仅当用户明确要求更新某文档、内容为既有活文档的延续、或同主题同日记录的修正扩展时,才更新已有文档,并保留其结构做最小改动。todo 文档属于活文档,同主题优先更新而非每件小事新建。
待办项建议字段:状态(open/doing/blocked/done/dropped/promoted)、来源、内容、下一步、风险处理(影响、触发条件、缓解措施)。未完成项靠前,完成项移入已处理区并标注日期,被提升到其他文档时标记 promoted 并指明去向。
写作风格:去 AI 腔,按“背景—张力或问题—行动—证据—结论—下一步”叙事组织;多用直接标题、短段落、事实结论、代码格式的命令与路径、指标对比表格、决策与下一步要点,每段一个观点。避免“本文旨在”“综上所述”等填充式开头、空泛夸赞、无数据论断、混杂设置与结论的长段、无解释的原始日志堆砌。
各类型质量要求:实验文档需自包含且可对比,写清触发背景、实验问题与假设、对比范围、数据集与环境、命令与提交、指标口径(单位、方向、局限)、结果总览表与分场景结论、跨场景分析、边界与复现入口、下一步;Calibration 类多场景对比如 Ceres/Kalibr 可按背景、对比范围、指标术语表、总览表、分场景结构、跨场景分析、局限与下一步组织;含历史诊断记录时在开头加阅读导引,标注过时结论。knowhow 文档写触发场景、现象、原因、处理方法、验证、适用条件、陷阱与边界、相关命令文件。plan 文档把模糊转为可执行路径,含背景、目标、范围、方案、执行路径表、风险、检查点、下一步。roadmap 说明方向而非仅列里程碑,每个里程碑可验证。
技术书籍模式:写作或重写论文式章节、教科书小节、长技术解释,涉及推导密集的标定、机器人、状态估计、优化或由代码推导的数学,公式/雅可比/残差/坐标系/实现与理论桥接,或把零散笔记整理成连贯章节时,先读 references/technical-book-writer.md;普通计划、待办、实验、路线图、命令或短经验更新不加载该参考。
写后审查:任何 Markdown 文档创建或更新后,须以编辑视角重读全文,检查可读性、结构一致性、模块完整性、证据、指标清晰度、时效性标注、可扫描性、可行动性;不合格则修改并重读相关段落。之后执行最终通俗化润色,按 references/post-write-polish.md 将各文档类型路由到对应 shuorenhua 层级与范围;用户表示不需要润色、不要润色、跳过润色、按原流程、保持原样时不执行该遍,仅完成写后审查。两遍均为内部过程,除非用户要求对比,只交付最终文档。
模板:技能提供 plan、todo、experiment、knowhow、roadmap 模板,可灵活使用,仅保留有价值的部分。
常用命令.txt:只放可复制粘贴的命令,每条命令占一个物理行,不使用 \ 续行,不跨行换行;按中文注释分组,每组前加简短中文说明;避免重复,除非是有意义变体;替换已有命令时保留分组只更新相关行。需要具体命令组或文档更新范式时读 references/examples.md,日常更新不加载。
写完后最终回复:只报告有用事实,如创建或更新的文件、所选分类、相关关键命令或结果、跳过或未决事项,保持简短,除非用户要求否则不粘贴整篇文档。
限制:资料未提供该技能的安装方式、收费情况或平台要求;具体执行依赖 SKILL.md 与 references 目录中的参考文件,相关细节暂未提供。