agentleFS
ggbdpqggbdpq/agent-skills/skills/.curated/tech-writer/SKILL.md

tech-writer

Skill1 starsChanged 5 months agoMITView on GitHub

技术文档终稿化与工程留痕。Use when translating or polishing technical Markdown, writing README, docs index, development log, bug retrospective, handoff guide, change explanation, rollback note, deployment notes, testing report, audit note, developer-facing code logic notes, business-facing feature docs, or when the user wants clear Chinese documentation with paths, commands, fields, rules, boundaries, and verification.

9 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

Tech Writer

使用定位

用于技术文档翻译、终稿化、README、交接说明、Bug 复盘、开发记录、部署联调、测试评估、验收审计、代码逻辑梳理和业务说明。目标是写出程序员愿意保存和复用的文档。

写作前先收事实

文档类型先读
模块交接源码入口、dev/README.md、PRD、接口、测试、Bug、项目总结
服务交接README.md、docs/README.md、package scripts、部署、测试、审计、开发记录
Bug 复盘问题表现、触发条件、排查路径、根因、修复、验证、预防
变更说明改动文件、变更意图、影响范围、未改事项、回滚方式
README启动命令、运行前置、核心能力、目录、验证命令、常见坑
代码逻辑梳理页面入口、组件、service、接口、字段、按钮、弹窗、跳转、关键判断
业务说明页面展示、用户操作、业务规则、校验含义、适用场景、常见问题

当前 README、package.json 和源码优先。历史文档只能作为经验来源。

文档模式选择

先判断读者,再决定保留哪些细节:

模式读者可保留必须避免
代码逻辑梳理开发者、接手模块的人文件路径、字段名、接口、按钮条件、关键判断、跳转参数大段代码、props 罗列、无意义实现细节
业务说明业务、新人、产品、运营页面能做什么、操作流程、业务规则、校验原因、常见问题代码块、函数名、接口结构、技术栈堆砌

代码逻辑梳理要帮助开发者快速接手模块。业务说明要让没有代码背景的人理解功能价值和规则原因。

常用结构

Bug 复盘

章节内容
问题表现用户或页面看到什么
触发条件环境、数据、入口、操作
排查路径commit、文件、测试、接口
根因分析直接原因和边界误判
修复方案最小改动点
验证方式命令和人工验收
预防建议后续如何避免

开发记录

章节内容
创建内容新增或修改了哪些文件
开发内容实现了什么能力
踩坑记录真实失败、误判和边界
验证记录失败测试、修复后命令、结果

交接文档

章节内容
核心结论入口、边界、缓存、组件职责
目录结构ASCII 目录图和文件职责
主流程初始化、查询、提交、状态操作
数据流service、hook、utils、store、components
字段和字典状态、服务类型、组织类型、后端事件
验证命令轻量测试和人工检查点
自检清单修改前先查哪些表和文件

代码逻辑梳理

章节内容
页面展示筛选、列表、详情、弹窗、抽屉、按钮和字段顺序
操作行为点击后跳转、请求接口、二次确认、刷新、回跳和提示
接口说明method、url、入参、出参、字段含义和分页结构
关键判断权限、状态、枚举、展示条件、禁用条件和异常分支
自检清单字段文案是否准确,场景是否拆开,枚举是否完整,行为是否追到真实接口或路由

写法要求:

  1. 按页面和逻辑分章,先整体后细节。
  2. 字段要尽量保留页面文案、接口字段名和中文含义。
  3. 列表字段按界面顺序写,按钮先写是否展示,再写点击后发生什么。
  4. 弹窗要写标题、关键文案、字段、动态文案来源和提交结果。
  5. 允许写少量关键条件,例如 status == 1,但不贴大段代码。
  6. service 梳理以接口为纲,写清 method、url、入参、出参和业务含义。

业务说明

章节内容
业务背景这个页面或模块解决什么问题,为什么需要它
核心功能用户能完成哪些事情,每个功能的业务定位
页面流程用户从进入页面到查询、操作、保存、查看结果的路径
关键业务规则状态、权限、校验、限制、特殊模式和失败提示的业务意义
快速记忆卡片重要概念到一句话解释
常见问题新人、业务或运营最容易问的问题

写法要求:

  1. 全部使用中文业务语言。
  2. 不写代码块、函数名、接口结构、文件路径或技术栈堆砌。
  3. 每个模块先用一句话说明解决什么问题。
  4. 解释为什么要做,再解释用户怎么用。
  5. 错误、边界和校验只用业务语言描述。

翻译硬约束

  • 代码块内容逐字不变,只翻译纯注释行。
  • 占位符、变量、标签、锚点、URL、文件路径保持一致。
  • YAML frontmatter 只翻 value,不翻 key,不改顺序。
  • HTML 标签数量和配对关系保持不变。
  • 不为文风改写事实边界或章节结构。

终稿流程

  1. 先判模式:翻译、终稿、工程留痕或交接。
  2. 收结构,删除重复标题和空洞过渡。
  3. 补事实路径、命令上下文和预期结果。
  4. 把字典、状态、字段映射优先表格化。
  5. 对未覆盖风险写明原因。
  6. 去掉 AI 腔、营销感、武断断言和元叙述。
  7. 保持输出能直接保存为 Markdown。

需要更细规则时再读取:

  • references/self-check-list.md
  • references/error-fix-table.md
  • references/structure-templates.md
  • references/anti-patterns.md
  • references/formatting-rules.md
  • references/quality-checklist.md

文风标准

  • 先给结论,再给证据和步骤。
  • 每段都要有信息增量。
  • 每个命令说明用途和预期结果。
  • 每个表格前说明表格用途。
  • 少用口号和抽象词,多写路径、文件、命令、接口、状态。
  • 不写无法核验的断言。

输出要求

按用户需要使用:

  1. 结论摘要
  2. 修改文件清单
  3. 改动目的
  4. 可执行步骤
  5. 验收方式
  6. 未改事项

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.