本项目是一份面向中文技术文档、产品文案与界面文案的写作 Skill,支持撰写、改写、校对和审阅。

这份 Skill 的目标很明确:中文技术写作应更克制、更准确、更易读。 不追求宣传感，也不试图把所有内容都写成统一模板，而是聚焦几类高频问题：

• 中文技术文案容易空泛、重复、宣传化
• 中文与英文、数字混合排版时可读性差
• 常见英文状态词和错误词容易被机械直译
• 文档首页、解决方案页、接口说明页、FAQ 的信息密度和结构经常失衡
• 操作说明中的术语、条件和动作不够明确，容易造成理解或执行偏差

如果需要一套适合中文技术文档的基础写作规范,这份 Skill 可以直接拿来使用,或是作为参考。

适用场景

本 Skill 适合以下内容:

• 文档首页、落地页、首屏文案
• 接口文档、参数说明、错误码说明、更新日志
• 操作手册、安装与部署步骤、多步骤 API 调用流程
• 故障排查、运维 Runbook、安全说明
• 产品能力介绍、解决方案页、能力说明页
• 界面文案、按钮文案、导航标签、提示信息

文档中的以下内容保持原样，不应用文案改写和排版替换：

• 代码字面量
• JSON 键名
• URL
• API 路径
• 数据库字段名
• 其他机器可读标识符

核心规则概览

这份 Skill 主要覆盖以下规则:

• 改写时保留事实、限制、条件和确定程度
• 中文引号统一使用直角引号 「」
• 默认避免不必要的直接称呼，允许项目语气覆盖
• 在可见正文中处理中文与英文、数字之间的留白
• 中文段落在源文件中保持一段一行，不做硬换行
• 避免机械直译 Success、Invalid、Bad Request 等英文状态词
• 避免高频互联网黑话,如 赋能、抓手、闭环、打通
• 对操作、排查和运维文档应用受控中文技术写作方法

完整规范请阅读：

• SKILL.md
• 公开说明稿

借鉴 STE 的技术写作方法

本项目的受控中文技术写作模块借鉴 ASD-STE100(Simplified Technical English,简称 STE)的受控语言思路,通过一致的术语、明确的动作和清晰的逻辑顺序,减少技术说明中的歧义。

模块将可迁移的方法适配到中文写作中：

• 同一概念使用同一首选术语，不为避免重复而轮换同义词。
• 一个步骤包含一个主要动作，多个有先后顺序的动作拆成编号步骤。
• 执行前必须知道的条件和风险警告放在动作之前。
• 明确执行者、操作对象和预期结果，区分人工操作与系统自动行为。
• 保留原文事实、限制、例外和确定程度，不为简化表达而补造信息。

这些方法主要用于操作手册、安装与部署、故障排查、运维文档、安全说明和多步骤 API 流程。

Chinese Tech Doc Style

本项目是一份面向中文技术文档、产品文案与界面文案的写作 Skill，支持撰写、改写、校对和审阅。

这份 Skill 的目标很明确：中文技术写作应更克制、更准确、更易读。不追求宣传感，也不试图把所有内容都写成统一模板，而是聚焦几类高频问题：

• 中文技术文案容易空泛、重复、宣传化
• 中文与英文、数字混合排版时可读性差
• 常见英文状态词和错误词容易被机械直译
• 文档首页、解决方案页、接口说明页、FAQ 的信息密度和结构经常失衡
• 操作说明中的术语、条件和动作不够明确，容易造成理解或执行偏差

如果需要一套适合中文技术文档的基础写作规范，这份 Skill 可以直接拿来使用，或是作为参考。

适用场景

本 Skill 适合以下内容：

• 文档首页、落地页、首屏文案
• 接口文档、参数说明、错误码说明、更新日志
• 操作手册、安装与部署步骤、多步骤 API 调用流程
• 故障排查、运维 Runbook、安全说明
• 产品能力介绍、解决方案页、能力说明页
• 界面文案、按钮文案、导航标签、提示信息

文档中的以下内容保持原样，不应用文案改写和排版替换：

• 代码字面量
• JSON 键名
• URL
• API 路径
• 数据库字段名
• 其他机器可读标识符

核心规则概览

这份 Skill 主要覆盖以下规则：

• 改写时保留事实、限制、条件和确定程度
• 中文引号统一使用直角引号 「」
• 默认避免不必要的直接称呼，允许项目语气覆盖
• 在可见正文中处理中文与英文、数字之间的留白
• 中文段落在源文件中保持一段一行，不做硬换行
• 避免机械直译 Success、Invalid、Bad Request 等英文状态词
• 避免高频互联网黑话，如 赋能、抓手、闭环、打通
• 对操作、排查和运维文档应用受控中文技术写作方法

完整规范请阅读：

• SKILL.md
• 公开说明稿

借鉴 STE 的技术写作方法

本项目的受控中文技术写作模块借鉴 ASD-STE100（Simplified Technical English，简称 STE）的受控语言思路，通过一致的术语、明确的动作和清晰的逻辑顺序，减少技术说明中的歧义。

模块将可迁移的方法适配到中文写作中：

• 同一概念使用同一首选术语，不为避免重复而轮换同义词。
• 一个步骤包含一个主要动作，多个有先后顺序的动作拆成编号步骤。
• 执行前必须知道的条件和风险警告放在动作之前。
• 明确执行者、操作对象和预期结果，区分人工操作与系统自动行为。
• 保留原文事实、限制、例外和确定程度，不为简化表达而补造信息。

这些方法主要用于操作手册、安装与部署、故障排查、运维文档、安全说明和多步骤 API 流程。概念说明和产品介绍可选择性采用术语一致、指代明确等规则，不把品牌文案、叙事文本、固定引用或短按钮文案机械改成操作步骤。

STE 面向英文技术文档，其受控词典、词性、时态和句长规则不能直接套用于中文。本项目不是该标准的中文版本，也不承诺输出符合该标准；自动检查结果不代表 STE 合规。标准背景见 ASD-STE100 官方说明。

仓库结构

tech-doc-style-chinese/
├── SKILL.md
├── NoCode-Skill.md
├── README.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── api-status-copy.md
│   ├── controlled-technical-chinese.md
│   ├── project-overrides-example.md
│   └── terminology-and-typography.md
├── scripts/
│   ├── lint_copy_rules.py
│   └── unwrap_md_paragraphs.py
└── tests/
    ├── test_lint_copy_rules.py
    ├── test_skill_structure.py
    └── test_unwrap_md_paragraphs.py

各文件的作用：

• SKILL.md：正式技能入口，供 Codex、Claude Code 等 Agent 使用
• NoCode-Skill.md：对外说明稿，适合公开阅读和分享
• README.md：GitHub 仓库首页说明
• agents/openai.yaml：技能展示元数据
• references/：按任务读取的详细规则和项目覆盖模板
• scripts/lint_copy_rules.py：轻量检查器
• scripts/unwrap_md_paragraphs.py：展开段落硬换行的工具
• tests/：检查器、技能结构和硬换行工具的回归测试

如何在 Codex 中使用

使用 npx 安装（推荐）

如果本机有 Node.js 环境，可直接用 npx skills 安装：

# 直接安装
npx skills add https://github.com/Fenng/tech-doc-style-chinese

如需无交互并明确安装到全局 Codex，可使用：

npx -y skills add https://github.com/Fenng/tech-doc-style-chinese -a codex -g

参数说明：

• -a codex 表示安装到 Codex agent
• -g 表示全局安装（用户级），不加则安装到当前项目范围
• -y 表示跳过交互确认，便于自动化执行

安装后建议重启 Codex，以确保新 Skill 被加载。

按 Release 安装（推荐）

固定版本安装，便于团队复现：

CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME/skills"

git clone --depth 1 --branch  \
  https://github.com/Fenng/tech-doc-style-chinese.git \
  "$CODEX_HOME/skills/tech-doc-style-chinese"

`` 可替换为已发布版本，例如 v0.1.0.2.4。