by luoling8192
中文内部技术写作的 agent skill，约束设计文档 / 评审稿 / postmortem / 分享稿场景的语气、句法、结构
# Add to your Claude Code skills
git clone https://github.com/luoling8192/technical-writingGuides for using ai agents skills like technical-writing.
Use this skill when the writing target is an internal技术方案、评审稿、架构说明、分享文稿，重点在于把背景、猜想、证据、抽象、实现影响面讲清楚。
这类写作更接近技术汇报，不是宣传稿，也不该写成散文。语气要平稳，判断要有来路，段落要能顺着问题往下读。
When not to use
先接住读者，再往下解释。
常见写法是作者替读者抢先下判断，像 很清楚、说明了、显然、真正。这里更适合换成三步：
如果要给出更强的判断，至少满足下面任一条件：
这些 bad case 往往有同一种共性：
遇到这类句子，默认处理方式不是“换个更文雅的说法”，而是：
写长文时，优先用这条主线：
背景 -> 拆解现状 -> 提出猜想 -> 分节解答 -> 回指前文 -> 影响面 -> 可观测性 / eval -> 收束
如果文章围绕一个系统展开，可以把每一节都写成“在回答前面哪个问题”。这样读者会知道当前段落在解决什么，而不是只看到一串观点。
更具体一点，常见结构会是：
如果某一节表面上在讲模块，实际目的是在替另一个概念安家，可以优先用这种结构：
中文内部技术写作的 agent skill。约束设计文档、评审稿、postmortem、分享稿等场景的语气、句法、结构，让产出贴近技术汇报，避开营销稿和散文气质。
不适用：UI 文案、产品营销稿、面向外部用户的帮助文档、机械 API reference。
通过 skills.sh 一行装，自动检测当前 agent 并写入对应目录：
npx skills add luoling8192/technical-writing
支持 Claude Code、Cursor、Codex、GitHub Copilot、Windsurf、Gemini、Cline、AMP 等主流 agent runtime。装完在对应 agent 里用 Skill 工具调用 technical-writing 即可，也可以在项目的 CLAUDE.md / AGENTS.md 里把它列为常用 skill。
如果不想用 skills.sh，可以直接 clone 后软链接：
git clone https://github.com/luoling8192/technical-writing.git ~/repos/technical-writing
mkdir -p ~/.claude/skills
ln -s ~/repos/technical-writing ~/.claude/skills/technical-writing
OpenAI Codex 用户可参考 agents/openai.yaml，按 Codex 文档注册到本地。
— 和英文连字符 - 做分句「」1. 2. 3. 4.完整规则、改写示例、Few-Shot 修正案例见 SKILL.md。
灵感和反馈来自 @nekomeowww。
MIT
No comments yet. Be the first to share your thoughts!
mindmap如果要给 leader 或评审一个放在最开头的 TL;DR，优先用三段结构：
这个 TL;DR 只保留三类信息：
不要在 TL;DR 里复述整篇目录，也不要解释作者接下来会怎么写。
中文语气以自然、平实、技术同伴之间的说明为主。
「」Agent Runtime、Context Engine、Agent Signal、Event流通性、筛选、聚合、命中，不要临时拼接近义词聊到这里、继续往下看、这条方向很值得继续推开、先把这件事单独拿出来说、最后可以用一句话收住；如果一句话只是在主持文章，不承载信息，就直接删掉很现实、很重、很轻、很顺；改成具体约束、具体风险、具体影响下面这类句型要主动收一层：
不是……而是……不在……而在……为什么？原因其实很直接这条路径已经很清楚了说明了一件事自然会真正更稳妥的写法通常是：
也许你会先想到……把视线收回到今天的代码里，会先看到几组比较稳定的规律顺着这些模块往回看，可以归纳出……前面提到的猜想，在这里开始有了一个更具体的回答先把判断放轻一些，后面再结合代码或指标继续说明遇到段落里的关键问题句，可以适度用 **...** 强调，但只留给真正的主问题，不要把普通判断句全部加粗。
下面这些词在中文技术文档里几乎都是「让句子看起来有信息，但读完不知道发生了什么」。看到先停一下，能换成具体动作 / 对象 / 约束就换掉。
原则：不是逐词替换，而是逐句重写。原句里如果只有黑话词承载信息，整句通常没信息。删掉看论证少不少东西，少了再补具体的，没少就让它消失。
生态 / 生态位 / 产品生态 → 列出具体依赖关系、用户类型或集成方赋能 / 赋能用户 → 让用户能 X / 把 X 能力开放给 Y闭环 / 形成闭环 → X 之后 Y 也接进去了 / 现在能从 A 走到 B 再回到 A抓手 / 核心抓手 → 我们能改的那一个变量是 X心智 / 用户心智 / 心智模型 → 用户在第一次看到 X 时会怎么想 / 怎么操作链路打通 / 打通 → A 现在能调用 B / A 写入的数据 B 也能读到沉淀 / 沉淀经验 / 沉淀方法论 → 记录到 docs/X / 整理成 skill / runbook落地 / 落地能力 / 落地场景 → 在 A 模块实现 / 在 B 业务用上心力 / 认知负担 → 需要记住 X 个步骤 / 上手要先理解 Y收口 / 统一收口 → 所有 X 都走 Y 一个入口加持 / AI 加持 → 加了 X 之后能 Y / 在 X 步用了 LLM底座 / 底层逻辑 → 基础设施层是 X / 这件事成立的前提是 Y很值得 / 非常值得 → 给具体理由：值得在哪个维度上极致 / 极致体验 → 改成具体指标：延迟降到多少、步骤减到几步丝滑 / 顺畅 → 改成具体约束：哪步原本卡，现在跳过了深度集成 / 深度对接 → 改成集成点的具体范围一站式 → 在 A 入口能完成 B / C / D颠覆 / 重塑 → 默认不用；真要用得有 before / after 对比写代码和架构时，避免直接把实现细节翻译成抽象结论。
推荐顺序：
代码 / issue / trace / metric -> 宏观规律 -> 抽象归纳 -> 设计判断
例如，不要直接写：
当前代码里，这条路径已经很清楚了。
更适合写成：
把视线收回到今天的代码里，会看到几组比较稳定的宏观规律。顺着这些模块往回看，可以先归纳出一个较稳定的结构。前面提到的几层能力，也因此开始有了几种更适合继续承接的实现位置。
很多技术分歧来自“作者默认读者已经接受了自己的前提”。这里更适合先猜测读者可能会怎么想，再把误会拆开。
常用句法：
也许你会先想到 Workflow，像是……顺着这个方向想下去，会发现我们更关心的是……这样理解，会更贴近这次设计的边界适合接一个 quote：
一个复杂任务如何按预定义节点顺序执行
然后再转入你真正要讨论的问题：
聊天过程中持续冒出的离散事实，怎样在不阻塞主链路的情况下，被解释成值得处理的反馈信号
下面这些例子比抽象规则更重要。写作时如果遇到类似句式，优先按这个方式改。
real / realize / reality 直接翻进中文原句：
一旦把信号层接到多 adapter 上，粒度问题会马上变得很现实。
问题：
现实 在这里不是合适的表语粒度问题，谓语是 变得，搭配不成立改写：
可以预见的是，Agent Signal 集成进入 adapter 之后，信号控制会很重要。
为什么这样改：
集成进入 adapter 之后信号控制会很重要原句：
这样的组合很顺。
问题：
很顺 只有情绪，没有信息改写：
这种组合更接近实际分工。
或者：
这种组合能把主回答链路和高频判断链路拆开。
为什么这样改：
原句：
它值得认真看的地方，不在宣传语，而在它把一组运行时机制组织得很完整。
问题：
不在……而在…… 容易写出说教感改写：
更值得认真拆开的，是它把一组运行时机制组织得比较完整。
为什么这样改：
原句：
聊到这里，memory 相关模型也该放进来一起看了。
问题：
改写：
memory 相关模型也需要放进来一起讨论。
为什么这样改：
同类句子也直接删掉，不做“温和改写”：
原句：
先把「压缩」这件事单独拿出来说。
问题：
处理：
直接删除，让下一句作为段落开头
原句：
这张图想说明的事情很简单。
问题：
处理：
直接删除，下一句直接解释图里的结构关系
原句：
接下来进入这一节真正关心的问题：
问题：
处理：
直接删除，或者把下一句改成完整的问题句
原句：
最后可以用一句更轻一点的话结束：
问题：
处理：
直接删除，让引文或结论直接出现
原句：
第一，入口很多，但 agent 请求最终还是会被收束到 runtime。 第二，context engine 已经承担了消息整理…… 第三，runtime 自己已经天然拥有一组执行边界…… 第四，外围模块已经把不少有价值的信息散落出来了……
问题：
改写：
为什么这样改：
原句：
第一组命题靠近转化率。不同 source 类型进入系统之后，有多少被 dedupe 掉，有多少在 cooldown 里停住，有多少被 policy 接住，最后又有多少真的升级成 Agent Signal。
问题：
转化率、dedupe 掉、停住、接住、升级 混了多套词改写：
- 计算流通性。 不同 source 类型进入系统之后：
- 有多少被 dedupe 筛选
- 有多少进入 cooldown 聚合
- 有多少被 policy 命中
- 最后又有多少升级成 Agent Signal
为什么这样改：
流通性筛选 / 聚合 / 命中 / 升级原句：
从 agent 入口到语义信号层…… 后面直接开始解释 runtime、context engine、adapter……
问题：
改写结构：
这一节表面上在讲 Agent Runtime，真正要回答的是 Agent Signal 应该放在哪里。mindmap 收住周边模块1. 2. 3. 4. 论据，把概念安到现有系统上为什么这样改：
原句结构：
当前系统已经具备了大量可利用的信息来源…… 我们的猜想是…… 基于这个判断，我们的决策是……
问题：
基于这个判断，我们的决策是 也带一点主持口吻更合适的结构：
第一段：先讲外部启发或上游项目带来的变化 第二段：再讲 Chat、Bot、Responses API、Eval、Memory 等输入已经存在，系统接下来要整理的是长期信号 第三段：直接提出新模块设计，例如 Agent Signal，以及 Redis / Upstash / useWorkflow 这类架构决策
例子：
上游某个项目让大家看到了另一种 Agent 形态…… 当前系统也已经具备了足够多的输入和状态来源…… 这里提出一个新的模块设计：Agent Signal……
为什么这样改：
原句：
这样的组合很顺。
原句：
这条路径很清楚。
原句：
这会马上变得很现实。
问题：
顺、清楚、现实 都是作者感受，不是技术判断改写方向：
先写条件 再写对象 最后写判断
例如：
可以预见的是，Agent Signal 集成进入 adapter 之后，信号控制会很重要。
原句：
散落出来了
原句：
收拢出来
原句：
往一层里收
原句：
延展下去
原句：
停在 action skipped
原句：
落在 failed
问题：
改写方向：
提供了整理出来集中到同一层处理继续追加后续处理最终生成了 action skipped最终生成了 failed不要为了“像文章”而硬把所有东西写成整段 prose。内容本来就是 list-shaped 时，直接列出来更清楚。
适合列出来的内容：
如果一组判断本身带有论证顺序，优先直接写成 1. 2. 3. 4.，不要把它们散落成几段并列 prose。
适合用 quote 的内容：
适合用箭头的内容：
source -> signal -> actionbackground -> hypothesis -> answerobserve -> infer -> route -> write back只谈抽象很容易飘。只谈代码又会失去设计视角。内部技术文档通常需要两层一起出现：
写实现层时，尽量把模块面摊开：
如果一段在说“改造”或“补充实现”，优先给出可扫描的块，例如：
可能涉及到的补充实现：
- memory layer CRUD 拓展
- signal orchestration 从 inline 转向异步消费
- tracing 压缩与聚合策略
- developer center 的链路展示与命题聚合
面向内部评审、leader、前线开发时，语气以「一起拆问题」为主。
先、可以、暂时、顺着这个观察交稿前，逐项扫一遍：
不是……而是…… 一类对立句法很清楚 / 说明了 / 显然 / 真正 这种抢结论的词「」收到草稿时，先做三件事：
背景 -> 猜想 -> 解答 -> 回指 重排结构，再改句子如果需要给出改写建议，优先直接改成可用的句子，不要只做抽象点评。