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
- stacklok/mecatltheir own version, first seen Oct 8, 2026
- linuxfoundation/insightstheir own version, first seen Oct 8, 2026
- christiangalsterer/documentation-plugintheir own version, first seen Oct 6, 2026
- stacklok/modeliththeir own version, first seen Jul 26, 2026
- sidneydiaraujo/claude-dev-plugintheir own version, first seen Jul 9, 2026
- aiunlocked1412/claude-skill-unlocktheir own version, first seen Apr 16, 2026
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 9
- stacklok/mecatl★ 312same name
- linuxfoundation/insights★ 292same name
- stacklok/modelith★ 48same name
- glincker/claude-code-marketplace★ 37same name
- aiunlocked1412/claude-skill-unlock★ 18same name
- benjaminwestern/google-engineer-skills★ 6same name
- christiangalsterer/documentation-plugin★ 1same name
- sidneydiaraujo/claude-dev-plugin★ 0same name
- sungkhum/agent-skills-pack★ 0same name
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 repository4 other files it gives its agents.
- .cursor/rules/Cursor沙盒执行手册.mdCursor rule
- .cursor/rules/Git推送指南整合.mdCursor rule
- mentor-meSkill
- minimal-diff-fixSkill
The file
Files
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、入参、出参、字段含义和分页结构 |
| 关键判断 | 权限、状态、枚举、展示条件、禁用条件和异常分支 |
| 自检清单 | 字段文案是否准确,场景是否拆开,枚举是否完整,行为是否追到真实接口或路由 |
写法要求:
- 按页面和逻辑分章,先整体后细节。
- 字段要尽量保留页面文案、接口字段名和中文含义。
- 列表字段按界面顺序写,按钮先写是否展示,再写点击后发生什么。
- 弹窗要写标题、关键文案、字段、动态文案来源和提交结果。
- 允许写少量关键条件,例如
status == 1,但不贴大段代码。 - service 梳理以接口为纲,写清 method、url、入参、出参和业务含义。
业务说明
| 章节 | 内容 |
| 业务背景 | 这个页面或模块解决什么问题,为什么需要它 |
| 核心功能 | 用户能完成哪些事情,每个功能的业务定位 |
| 页面流程 | 用户从进入页面到查询、操作、保存、查看结果的路径 |
| 关键业务规则 | 状态、权限、校验、限制、特殊模式和失败提示的业务意义 |
| 快速记忆卡片 | 重要概念到一句话解释 |
| 常见问题 | 新人、业务或运营最容易问的问题 |
写法要求:
- 全部使用中文业务语言。
- 不写代码块、函数名、接口结构、文件路径或技术栈堆砌。
- 每个模块先用一句话说明解决什么问题。
- 解释为什么要做,再解释用户怎么用。
- 错误、边界和校验只用业务语言描述。
翻译硬约束
- 代码块内容逐字不变,只翻译纯注释行。
- 占位符、变量、标签、锚点、URL、文件路径保持一致。
- YAML frontmatter 只翻 value,不翻 key,不改顺序。
- HTML 标签数量和配对关系保持不变。
- 不为文风改写事实边界或章节结构。
终稿流程
- 先判模式:翻译、终稿、工程留痕或交接。
- 收结构,删除重复标题和空洞过渡。
- 补事实路径、命令上下文和预期结果。
- 把字典、状态、字段映射优先表格化。
- 对未覆盖风险写明原因。
- 去掉 AI 腔、营销感、武断断言和元叙述。
- 保持输出能直接保存为 Markdown。
需要更细规则时再读取:
references/self-check-list.mdreferences/error-fix-table.mdreferences/structure-templates.mdreferences/anti-patterns.mdreferences/formatting-rules.mdreferences/quality-checklist.md
文风标准
- 先给结论,再给证据和步骤。
- 每段都要有信息增量。
- 每个命令说明用途和预期结果。
- 每个表格前说明表格用途。
- 少用口号和抽象词,多写路径、文件、命令、接口、状态。
- 不写无法核验的断言。
输出要求
按用户需要使用:
- 结论摘要
- 修改文件清单
- 改动目的
- 可执行步骤
- 验收方式
- 未改事项
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.

