用途
writing-style-guide 是一个写作风格技能，用于在生成或编辑面向用户的文字时提供统一原则。适用对象包括文档、注释、README、变更日志、提交信息、PR 描述和聊天回复。它明确自身定位为设定写作原则而非执行流程，要求使用者自行判断、保留契约，并让每个词都有价值。
适用范围
技能给出的适用范围包括：编写或编辑注释、文档字符串、README、CHANGELOG 和叙述性文档；编写或编辑提交信息、PR 描述、发布说明和聊天回复。
不适用的情况包括：文本属于内部内容、逐字的工具或日志输出、临时进度文本，或整条回复只是一个简单确认。
如果输出必须匹配某种精确格式，则该格式优先。JSON、协议载荷、解析敏感模板和其他机器可读结构必须保留其要求的结构，不得添加额外文字或 Markdown 围栏；但人类可读的注释和文档字符串仍在适用范围之内。
核心原则
简洁。 写出仍能承载意思的最短版本，删除装饰、空心过渡和装饰性结构。但简洁不等于可以漏掉事实、警告或用户要求的深度。
保留原意。 编辑只改措辞，不改契约。除非用户要求语义变更，否则应保留：事实、范围、受众、术语和重要的顺序；条件、例外、警告、限制和必需操作；情态动词差异——must、should、may、can、required、optional、recommended 是不同义务。一个更通顺但改变了谁必须做什么、规则何时适用、什么是允许的或失败时会发生什么的句子是错误的。
技能强调，明确缺席也是信息。应保留已提供的状态，例如 tests not run、not measured、no rollout plan supplied 或 not provided。在 Testing 部分，应写提供的状态（Not run、Not measured），而不是 Not provided；只有当来源确实没有给出状态时，才使用 Not provided 这类占位。风险与证据部分常常把有限证据与缺失证明并列，例如 parser change only、no production incidents supplied、no benchmarks、no rollout plan，应如实呈现现有证据。
不编造上下文。 不得添加无支持的动机、目标、结果、路线图声明、受众假设、商业价值、实现理由、因果关系、测试、风险降低或用户影响。避免使用 designed to、helps teams、future-ready、seamlessly、makes it easy to scale 等营销说法，除非产物能证明它们。看似显然的解释也需要支持，不得添加 so your account stays safe、to protect your data、to prevent unauthorized access 等安全理由，除非来源说明这就是原因。当被要求把政策、支持或 README 文案写得更温暖时，应通过让现有事实更易读来创造温暖，而不是添加安慰性声明、服务量承诺、可用性暗示、新的支持渠道说明或因果桥接。如果来源不完整，应让缺口可见，或在缺失输入阻碍任务时提出询问，不要把不确定性抹平成一个自信的故事。
按产物选择语言。 优先级为：用户明确指令，包括翻译或本地化请求；现有产物语言；README.ja.md 或 docs/de_de/guide.md 这类文件名区域标记；项目惯例；最后是英语。产物级翻译或本地化契约优先于聊天语言。除非用户明确要求翻译，否则保留文件路径、命令、标识符和规范字符串。聊天回复遵循用户当前的对话语言。
开门见山。 删除 Sure!、Absolutely.、Great question. 之类的开场白，用行动或答案来体现同意。
让产物独立成立。 不要向产物泄漏提示上下文，例如 per plan1.md、the provided text、above、as discussed 这类引用在对话之外会失效。可持久追溯则不同：issue ID、RFC、事件工单、提交 SHA、ADR 短名和审计引用在需要、要求或有助于回滚与审计时应当保留。如果引用在本地文件重命名后仍然成立，它就是引用而非提示泄漏。
匹配读者。 面向真实读者写作，省略其余内容。面向终端用户的 README 写它是什么以及如何开始使用；贡献者文档写搭建和提交；代码注释写签名、命名和类型无法解释的原因。项目自身风格和真实项目需求优先于通用规则。
反模式
技能列出应在看到时立即删除的写法：复述名称的注释，例如在 fn parse_user() 上写 // parse the user；营销词汇如 seamlessly、effortlessly、powerful、leverage、robust、enterprise-grade；无依据的未来声明如 future extensibility、easy to scale later；意义漂移，即更干净但改变义务或失败行为的措辞；凭空编造的上下文，如无支持的动机、意图、理由、影响或收益；模板化回答，如自动生成的 Summary / Testing / Notes、填充式三段结构和宽泛的对比章节；过度归一化，即用通用教科书措辞替换有用的本地术语、顺序、语气或示例；安全表演，即不改变读者行为的通用警告，但真实的安全、安保、数据丢失或合规警告应保留；未被要求的添加，如免责声明、替代方案、路线图说明、附加说明或“值得考虑的事项”；空心过渡语如 It's worth noting that、In conclusion、Ultimately；标点过度习惯，包括同一段中重复使用破折号。
各产物说明
源代码文档。 公共 API 需要意图、契约、不变量和非显然用法；内部代码只需为下一位维护者提供方向。应解释变通方法、性能技巧和微妙契约。不要写仅复述签名的文档注释。
README。 开头写它是什么以及如何开始。除非内容错误或已被明确修改，否则保留现有受众、前置条件、术语和搭建顺序。删除目标读者不需要的章节。
CHANGELOG。 遵循项目风格。每条记录回答“对我这个读者来说发生了什么变化”。没有用户可见影响的内部重构通常应留在提交历史中。不要把内部崩溃路径夸大成宽泛的可靠性声明。
提交信息。 匹配仓库惯例。主题说明提交达成了什么，而不是作者做了什么。正文只解释由 diff、issue 或所提供材料支持的为什么、权衡和评审上下文。没有证据不要声称测试、影响或风险降低。
聊天回复。 先给答案。进度更新保持一两句话。结尾总结在需要时简短，不需要时省略。当用户要求理由、验证、限制、恢复或对比时，再展开深度。简短回答能解决请求时，不要添加仪式性的结尾提议或通用下一步。
共存与自检
该指南用于文字质量，不用于工作流控制。当现有指令或项目惯例定义了特定模板、发布流程、暂存规则或 PR 格式时，应遵循该流程，并把本指南应用于其中的文字。
返回文字前应检查：是否还有任何词、标题、列表、附加说明或总结句可以删除而不损失信息；事实、范围、情态、条件、例外、警告和必需操作是否都保留；是否混入了无支持的理由、结果、路线图声明、受众假设、收益或安全理由；产物是否泄漏了提示上下文而没有独立成立；精确格式输出是否仍然精确。技能说明，其目标不是极简，而是让每个词都有其位置。
限制与暂未提供的信息
资料未提供该技能的安装方式、依赖要求、版本信息、收费或价格、支持平台、作者背景或实际使用效果。使用方式仅从技能内容本身可理解为：在生成或编辑上述面向用户的文字时应用这些原则。