publication-ready-docs
Skill9 starsChanged 3 days agoMITView on GitHub
撰写和修订正式工程技术文档(技术方案、详细设计、实施计划、README、API 文档、运行手册)。先查证源码与既有设计,删除冗余和过程性内容,保留必要的规则、改动对象、关键代码和配置。
In this repository17 other files it gives its agents.
- brief-outputSkill
- google-go-styleSkill
- insight-collectorSkill
- insights-reportSkill
- json-canvasSkill
- md2wechatSkill
- note-creatorSkill
- obsidian-basesSkill
- obsidian-markdownSkill
- peleSkill
- portpilot-assistantSkill
- publication-ready-docs-jevSkill
- readme-maintainerSkill
- sync-to-githubSkill
- tech-articleSkill
- wechat2mdSkill
- wechat-archiverSkill
The file
Files
Publication Ready Docs
工程文档让读者能独立理解、实施、运行和验证。先查证事实,再确定本次必要内容,先删后改,最后核对语义。
内容范围
- 详细设计 / 技术方案:目标、规则、改动对象、职责、接口契约、状态流转、关键代码和配置。
- 运行手册:前置条件、操作步骤、回滚和恢复。
- 测试与审计:验证场景、预期结果、实测结果;审计、复盘和 ADR 保留必要权衡。
按文档类型和任务取舍章节,按真实主题合并零碎小节,标题层级统一。部署、测试或审查证据按需写入。
工作流程
- 查证来源:核对源码、规范、表结构、配置与既有详设。简述复用机制与本次差异。需要定位时标注模块、文件、类、函数或配置项。
- 确定内容:列出读者需要的事实、规则、改动对象、关键代码和配置。先用可用工具查源码、规范、配置和已有查询结果;需要用户协助时,在会话给出具体查询项或 SQL,取得结果后写入正文。影响方案成立的外部业务条件保留,并在会话确认。
- 区分状态:分别写清现有行为、拟设计方案和已实施结果。
- 先删再润色:删除后读者仍能完成任务的内容直接删去。保留内容简写为规则和条件。清理过程记录、自我评价、空泛承诺、重复定义、模板空章节和无新增信息的提醒。
- 去重:一个事实只定义一次。字段位数、枚举和约束写在表格时,正文只写表格未覆盖的类型和解析规则。同步检查正文、表格单元格、括注和代码注释。仅清理文字和注释时,代码执行语句保持原样;方案调整时,同步修改代码和契约。
- 核对并同步:核对语义、边界、职责、数值和未决条件。仅审查时交付审查结果;获得授权后,基于最新版本局部修改正文、表格、代码和前提条件,改后回读,沿用项目约定的模板,保留既有图表资源。交付前按参考复核。
写作规则
- 短句、主动语态、一句一个要点。术语首次出现时定义,全篇用同一叫法。条件写在动作前。命令、路径、表名和字段名用代码格式。
- 规则写清主体、条件、动作和结果。必要边界用正面具体指令表达,例如“只更新
A表的B字段”。 - 字段禁填、长度、枚举含义、事务边界、失败后果、兼容性和数据写入范围保留一次。
- 引用外部规范时保留其条件、建议强度和例外。规范已有定义时直接引用或链接。项目补充只写已确认的差异和新增约定。其余比较、提醒和复述删去。
- 直接陈述规则和条件,删除包装语、防御性对照和过强语气。
详细设计检查项
- 源码位置写完整
文件:行号。同一文件再次引用时才可省略文件名。 - 分开写现有行为、本次改动、不改动对象。已确认的结论写进正文,从待确认移除。
- 效果和取数写具体名称与取值,例如“活跃门店数”“默认
0.95”。不用比喻替代指标,不写没有测量依据的性能结论。 - 不用自造词和非常用缩写。沿用工程和业务里已有的叫法,例如“判定条件”不写“判定式”;必须自造时在首次出现处定义。
- 代码改动按文件分节:位置、关键代码、触发条件、未改动部分。代码已表达的步骤不再用文字复述。
- 测试用例写具体输入值和预期结果,不用“任意”“不涉及”占位。
- 沿用项目模板的章节名和编号。模板中无内容的章节整节删除。
参考
- 常见坏味道:成稿后逐项复核。
- 转换示例:处理目录说明、包装语、来源提醒、配置值、重复定义或事务边界时对照。
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.

