---
name: clear-technical-writing
description: "撰写、改写和审阅中文技术说明、研究解读、操作文档、提示词及工作汇报，面向本领域初学者，解释细致平实，组织清楚的段落和准确图示，避免黑话、无必要的中英混杂与生硬翻译，并保留事实、条件、术语和证据强度。适合需要让读者独立理解、操作或判断的内容；不用于判断作者身份或追求检测器分数。"
---

# 把技术写清楚

让读者知道发生了什么、为什么、能据此做什么。需要推导就完整推导，需要一句话就直接说明。用词、篇幅和格式都服从这个目的。默认用朴实、平和的文字，面向本领域初学者完整解释；用户明确指定读者或篇幅时，按实际任务调整。详细不等于堆满信息，简洁也不等于跳过必要步骤。

## 先判断这份文字要做什么

动笔前确定读者、用途、已知背景和修改范围。能从上下文判断就继续，不为普通措辞选择反复询问。

| 内容 | 应交代的重点 |
|---|---|
| 给用户的进度与结果 | 已完成的实际动作、还未完成的部分、影响判断的原因或下一步 |
| 技术或研究解读 | 具体问题、输入、处理步骤、输出、证据与适用条件 |
| 操作说明 | 前提、动作、正常结果、失败后怎样继续 |
| 参数或接口参考 | 名称、含义、类型、默认值、边界及必要示例 |
| 设计说明或计划 | 问题、选择理由、代价、替代方案，以及实现与计划的界线 |
| 提示词或执行规则 | 对象、任务、可用材料、输出协议、真实限制和失败处理 |

同一文件可以有不同用途，按章节分别处理，不套用一种口吻改完整个文件。

## 面向初学者的成稿标准

读者可以不熟悉本领域，但不应被当作不能理解复杂问题的人。先说明具体任务、必要背景和涉及的对象，再解释步骤、原因、结果与限制。知识缺口用定义、衔接和有依据的例子补上，不能用“显然”“众所周知”“简单来说”略过推理。

先完整组织内容，再决定段落。一个完整意思独立成段；前提、操作、结果、例外或风险承担不同作用时，让它们在结构上有明显区分。几个紧密相连的句子保留为同一段，不能把一句一句换行当作层次。复杂条件可以分组列出，但必须保留它们之间的“同时满足”“任选其一”和先后关系。

中文正文采用自然、常用的中文。没有必要时不用英文动作、混合短语或临时缩写；正式名称、代码、字段和命令保持精确，在第一次需要理解时解释中文含义。读者需要的是对象的作用，而不只是英文后面附一个生硬译名。翻译拿不准时回到定义，不自造听起来高深的新词。

长文和全项目文档整理时，读取 [面向初学者的文档](references/beginner-documentation.md)。图表、插图或双语说明涉及本次交付时，读取 [图示与双语文档](references/diagrams-and-bilingual.md)。这两份参考规定解释深度、段落、语言与视觉检查方法，不授予改动事实或协议的权限。

## 写作时保住这些东西

1. **原意和证据。** 保留事实主体、数值、单位、范围、顺序、比较对象、归因、否定、条件和确定程度。“可能相关”不能写成“导致”，“计划支持”不能写成“已经支持”。
2. **用户的范围。** 润色不自动包括摘要、删减论点、补充资料、改代码或扩大发布。需要纠正事实时，先依据真实来源区分语言问题与事实问题。
3. **精确的技术身份。** 术语、变量、接口、命令、路径和协议字段不随意改名。引文、代码、公式、表格数据、元数据及链接目标默认保护；需要改动时，单独核对范围与依赖。
4. **真实状态。** 完成修改、通过检查、保存、提交、发布和上线是不同状态。按已经取得的证据汇报，不提前宣布后续阶段完成。

这些要求优先于语言自然、篇幅和风格偏好。已有明确项目规则时，在项目允许的范围内编辑；本 skill 不授予额外请求、费用、权限或发布资格。

## 用具体信息替换黑话

遇到“赋能、打通、闭环、抓手、全面提升”等表达，核对它是否说清：谁做什么、作用于什么、在什么条件下、有什么结果或依据。已有信息就直接写出来；没有信息就收窄或删除空泛效果，必要时说明缺口。把“赋能”换成“助力”并没有恢复信息。

专业词不等于黑话。“闭环控制”“矩阵分解”有明确技术含义，保留并解释。首次出现的重要术语先用当前场景说明其作用，再给名称；后文统一称呼。不要用近义词轮换同一对象，也不要用口语近似词抹掉技术区别。

删除不增加信息的开场、赞美、预告、假想敌和结尾升华。保留确有作用的因果、转折和顺序词。改主动句时，施事者必须已知；不能补造“系统”或“研究人员”充当主语。

## 按内容组织解释

段首先交代本段要回答的问题或判断，再展开原因、过程和证据。相邻句子要接得上：指代明确，步骤之间说明传递什么，结果能回应前面的比较问题。

解释机制时，说明输入如何经过各步变成输出，组件各自负责什么，为什么需要组合。涉及公式时说明符号、运算、成立条件和用途；涉及数字时交代指标定义、单位、比较条件，以及变大还是变小更好。

篇幅由信息和读者需要决定。不要为“简洁”删掉理由、限制、必要例子或推导；也不要补充与当前问题无关的背景。长短句自然变化，不设中文或英文的句长配额，不故意制造错字、碎句、口头禅或不连贯。

并列项目用列表，执行顺序用编号，对象共享属性时用表格，连续论证用段落。标题概括真实内容，不让每句话都变成带粗体标签的清单。空行分开标题、段落、列表、表格、代码和图片；表格中的长段解释移到表前后，保留比较所需的简明属性。标点和格式按语言、文体及已有规范选择，不能靠单个词或符号判断“AI 味”。

## 根据任务选择工作方式

- **新写内容：** 先组织材料和论证，再写句子；新增例子明确区分真实记录、来源内容和教学假设。
- **润色已有内容：** 先记下不能丢的主张和限定，再解决具体表达问题。已经通顺的部分可以不改。
- **研究或技术长文：** 按需读取 [技术解释](references/technical-explanations.md)，核对机制、比较、公式、图表与归因。
- **文档、提示词或规则审计：** 按需读取 [编辑与审计](references/editing-and-auditing.md)，先查真实实现与文件身份，再决定改哪里、怎样验证。
- **需要校准取舍或例子：** 读取 [例子与方法来源](references/examples-and-sources.md)。这些来源用于编辑判断，不是叠加执行的禁词表。

交付前对照来源检查是否新增、漏掉或强化了信息，再连着读相邻段落。检查列表、标题或句式调整是否改变顺序和范围。只复查受本次改动影响的部分；新发现、真实失败或项目要求需要时再扩大检查。

## 交付与停止

按用户要的形式交付。只要终稿就给终稿；要求诊断就给具体位置、问题及修法；修改文件后简述改动与实际验证，不默认贴出草稿、自评分或整套编辑过程。

有多个问题时，先完成当前约定范围的审查，再集中修正；复审发现问题就继续处理。完成的依据是信息准确、读者能理解、所需检查通过。配图还须在实际显示尺寸下看过，双语版本还须对照检查功能、命令、限制、数字和状态一致。不要为了检测器分数、禁词命中数或变化幅度反复重写，也不要把有限抽查说成完整审查。