Back to Details

tech-doc-style-chinese

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Chinese Tech Doc Style

中文技术文档写作规范

Skill by ara.so — Daily 2026 Skills collection.
A reusable writing skill for Chinese technical documentation, product copy, and UI text. Enforces clarity, correct typography, proper spacing between CJK and Latin characters, and avoids common translation pitfalls and internet buzzwords.
由 ara.so 开发的技能 —— 属于 Daily 2026 Skills 合集。
这是一款可复用的中文技术文档、产品文案及UI文本写作技能，确保内容清晰、排版规范，正确处理中日韩文字与拉丁字符间的间距，同时规避常见翻译误区和网络噱头词汇。

What This Project Does

项目功能

This skill provides opinionated, practical rules for writing Chinese technical content:
  • Typography: Correct spacing between Chinese, English, and numbers; use of corner brackets 
    「」
    instead of curly quotes
  • Tone: No direct address (
    你
    /
    您
    /
    同学
    ), no marketing fluff, no buzzwords (
    赋能
    /
    抓手
    /
    闭环
    )
  • Translation: Avoid mechanical translation of English status words (
    Success
    → 
    已完成
    , not 
    成功
    )
  • Structure: Information density rules for landing pages, API docs, FAQs, changelogs
  • Linting: Built-in zero-dependency Python script to catch violations automatically
本技能为中文技术内容写作提供了实用且明确的规则：
  • 排版规范：中文、英文与数字之间需正确添加空格；使用直角引号 
    「」
    而非弯引号
  • 语气风格：避免直接称呼（
    你
    /
    您
    /
    同学
    ），不使用营销话术及噱头词汇（
    赋能
    /
    抓手
    /
    闭环
    ）
  • 翻译原则：避免对英文状态词进行机械翻译（
    Success
    → 
    已完成
    ，而非
    成功
    ）
  • 结构要求：针对落地页、API文档、FAQ、更新日志制定信息密度规则
  • 自动检查：内置零依赖Python脚本，可自动检测违规内容

Installation

安装方式

Via npx (Recommended)

通过 npx 安装（推荐）

bash
undefined
bash
undefined

Interactive install

交互式安装

npx skills add https://github.com/Fenng/tech-doc-style-chinese
npx skills add https://github.com/Fenng/tech-doc-style-chinese

Non-interactive, global install to Codex

非交互式全局安装至 Codex

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

Pin a specific release

固定特定版本

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

git clone --depth 1 --branch v0.1.0.2.4 \
  https://github.com/Fenng/tech-doc-style-chinese.git \
  "$CODEX_HOME/skills/tech-doc-style-chinese"
bash
CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME/skills"

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

Local / development install

本地/开发环境安装

bash
CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME/skills/tech-doc-style-chinese"
cp -R ./* "$CODEX_HOME/skills/tech-doc-style-chinese/"
bash
CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME/skills/tech-doc-style-chinese"
cp -R ./* "$CODEX_HOME/skills/tech-doc-style-chinese/"

Verify

验证安装

test -f "$CODEX_HOME/skills/tech-doc-style-chinese/SKILL.md" && echo "installed"
undefined
test -f "$CODEX_HOME/skills/tech-doc-style-chinese/SKILL.md" && echo "installed"
undefined

Running the Lint Script

运行检查脚本

bash
undefined
bash
undefined

Lint everything

检查所有内容

python scripts/lint_copy_rules.py
python scripts/lint_copy_rules.py

Lint specific files or directories

检查特定文件或目录

python scripts/lint_copy_rules.py SKILL.md NoCode-Skill.md references/

CI runs automatically on `pull_request` and pushes to `main` via `.github/workflows/skill-lint.yml`.
python scripts/lint_copy_rules.py SKILL.md NoCode-Skill.md references/

通过 `.github/workflows/skill-lint.yml`，CI会在`pull_request`和推送至`main`分支时自动运行检查。

Repository Structure

仓库结构

tech-doc-style-chinese/
├── SKILL.md                        # Skill entry point for Codex
├── NoCode-Skill.md                 # Human-readable spec (share this)
├── README.md
├── agents/
│   └── openai.yaml                 # Skill metadata
└── references/
    └── Project-Overrides.md        # Per-project customization example
tech-doc-style-chinese/
├── SKILL.md                        # Codex 技能入口文件
├── NoCode-Skill.md                 # 可读规范说明（可分享此文件）
├── README.md
├── agents/
│   └── openai.yaml                 # 技能元数据
└── references/
    └── Project-Overrides.md        # 项目自定义规则示例

Core Rules Reference

核心规则参考

Typography & Spacing

排版与间距

Add a space between Chinese and English/numbers in visible body text:
undefined
可见正文内容中，中文与英文/数字之间需添加空格：
undefined

Wrong

错误示例

支持JSON格式和XML格式
支持JSON格式和XML格式

Correct

正确示例

支持 JSON 格式和 XML 格式
undefined
支持 JSON 格式和 XML 格式
undefined

Wrong

错误示例

版本号为1.2.3，发布于2024年
版本号为1.2.3，发布于2024年

Correct

正确示例

版本号为 1.2.3，发布于 2024 年

**Exception**: Do NOT apply spacing rules to code literals, JSON keys, URLs, API paths, database field names, or any machine-readable identifiers.
版本号为 1.2.3，发布于 2024 年

**例外情况**：代码字面量、JSON键、URL、API路径、数据库字段名或任何机器可读标识符，无需应用间距规则。

Quotation Marks

引号使用

Use corner brackets 
「」
for visible Chinese body text, not curly quotes:
undefined
可见中文正文需使用直角引号 
「」
，而非弯引号：
undefined

Wrong

错误示例

这是一个"示例"说明
这是一个"示例"说明

Correct

正确示例

这是一个「示例」说明
undefined
这是一个「示例」说明
undefined

Avoid Direct Address

避免直接称呼

undefined
undefined

Wrong

错误示例

您可以通过以下步骤完成配置。 你好同学，欢迎使用本产品。
您可以通过以下步骤完成配置。 你好同学，欢迎使用本产品。

Correct

正确示例

通过以下步骤完成配置。 欢迎使用本产品。
undefined
通过以下步骤完成配置。 欢迎使用本产品。
undefined

Status Word Translation

状态词翻译

Avoid mechanical translation of English HTTP/API status terms:
EnglishWrongCorrect
Success成功请求已完成 / 操作成功
Invalid无效的参数格式不正确
Bad Request坏请求请求参数有误
Forbidden被禁止的无访问权限
Not Found没有找到资源不存在
避免对英文HTTP/API状态词进行机械翻译：
英文错误译法正确译法
Success成功请求已完成 / 操作成功
Invalid无效的参数格式不正确
Bad Request坏请求请求参数有误
Forbidden被禁止的无访问权限
Not Found没有找到资源不存在

Banned Buzzwords

禁用噱头词汇

The linter flags these terms as errors in visible body text:
赋能  抓手  闭环  打通  沉淀  赋能  链路  颗粒度
生态  矩阵  倒逼  落地  变现  复盘  对齐  拉齐
检查脚本会将以下词汇标记为可见正文的错误：
赋能  抓手  闭环  打通  沉淀  赋能  链路  颗粒度
生态  矩阵  倒逼  落地  变现  复盘  对齐  拉齐

Common Chinese Typos (Lint Catches These)

常见中文错别字（检查脚本可识别）

WrongCorrect
阀值阈值
登陆登录
布署部署
配制配置
起用启用
反回返回
回朔回溯
标示标识
帐户账户
帐号账号
截止截至
错误写法正确写法
阀值阈值
登陆登录
布署部署
配制配置
起用启用
反回返回
回朔回溯
标示标识
帐户账户
帐号账号
截止截至

Term Casing (Lint Enforces)

术语大小写规范（检查脚本强制执行）

undefined
undefined

Wrong

错误示例

id http url json api ai JS Js H5 llm aigc rag
id http url json api ai JS Js H5 llm aigc rag

Correct

正确示例

ID HTTP URL JSON API AI JavaScript HTML5 LLM AIGC RAG
undefined
ID HTTP URL JSON API AI JavaScript HTML5 LLM AIGC RAG
undefined

Content Type Guidelines

内容类型指南

Landing Pages & First Screens

落地页与首屏内容

undefined
undefined

Wrong — vague, marketing-heavy

错误示例 — 模糊、营销话术过重

我们致力于打造业界领先的、赋能开发者的一站式 AI 平台解决方案。
我们致力于打造业界领先的、赋能开发者的一站式 AI 平台解决方案。

Correct — concrete, scannable

正确示例 — 具体、易扫描

支持 REST 和 GraphQL 接口，5 分钟完成接入，每月免费额度 100 万次调用。

- Lead with what the product does, not what it "empowers"
- Put concrete numbers (latency, limits, pricing) above the fold
- One primary CTA per screen; button text must name the next action
支持 REST 和 GraphQL 接口，5 分钟完成接入，每月免费额度 100 万次调用。

- 优先说明产品功能，而非“赋能”类表述
- 将具体数据（延迟、限制、定价）放在首屏可见区域
- 每屏仅保留一个主要行动按钮，按钮文案需明确下一步操作

API & Parameter Docs

API与参数文档

markdown
undefined
markdown
undefined

请求参数

请求参数

参数名类型必填说明
user_idstring是用户唯一标识，长度 8–32 位
pageint否页码，从 1 开始，默认为 1
page_sizeint否每页条数，范围 1–100，默认 20

Rules:
- State type, whether required, default value, and constraints explicitly
- Use `是` / `否` for required, not `required` / `optional`
- Error codes must explain cause AND recovery action
参数名类型必填说明
user_idstring是用户唯一标识，长度 8–32 位
pageint否页码，从 1 开始，默认为 1
page_sizeint否每页条数，范围 1–100，默认 20

规则：
- 明确说明类型、是否必填、默认值及约束条件
- 使用`是`/`否`表示必填状态，而非`required`/`optional`
- 错误码需同时说明原因及解决方法

Error Code Docs

错误码文档

markdown
undefined
markdown
undefined

错误码说明

错误码说明

错误码说明处理建议
40001缺少必填参数 
user_id
检查请求体是否包含 
user_id
字段
40301当前账号无访问该资源的权限联系管理员确认角色权限配置
50001服务端处理超时稍后重试，如持续出现请提交工单
undefined
错误码说明处理建议
40001缺少必填参数 
user_id
检查请求体是否包含 
user_id
字段
40301当前账号无访问该资源的权限联系管理员确认角色权限配置
50001服务端处理超时稍后重试，如持续出现请提交工单
undefined

FAQ Pages

FAQ页面

undefined
undefined

Wrong — repeats the question

错误示例 — 重复问题内容

Q: 如何重置密码？ A: 重置密码的方法如下……
Q: 如何重置密码？ A: 重置密码的方法如下……

Correct — answers immediately

正确示例 — 直接给出答案

Q: 如何重置密码？ A: 进入「账号设置」→「安全」→「修改密码」，输入手机验证码后设置新密码。
undefined
Q: 如何重置密码？ A: 进入「账号设置」→「安全」→「修改密码」，输入手机验证码后设置新密码。
undefined

Changelogs

更新日志

markdown
undefined
markdown
undefined

v2.3.0 — 2024-03-15

v2.3.0 — 2024-03-15

新增

新增

  • 支持通过 API 批量导入用户，单次上限 1000 条
  • 支持通过 API 批量导入用户，单次上限 1000 条

修复

修复

  • 修复在 Safari 16 下登录页闪烁的问题
  • 修复在 Safari 16 下登录页闪烁的问题

变更

变更

  • GET /v1/users
    返回结构新增 
    created_at
    字段
undefined
  • GET /v1/users
    返回结构新增 
    created_at
    字段
undefined

Button & UI Copy

按钮与UI文案

undefined
undefined

Wrong — abstract, duplicates surrounding heading

错误示例 — 抽象、重复标题内容

立即体验 了解更多 点击查看
立即体验 了解更多 点击查看

Correct — names the next action

正确示例 — 明确下一步操作

开始免费试用 查看接口文档 下载 SDK
undefined
开始免费试用 查看接口文档 下载 SDK
undefined

Project-Level Overrides

项目级自定义规则

Keep the core skill generic. Put project-specific conventions in 
references/Project-Overrides.md
:
markdown
undefined
保持核心技能通用性，将项目特定约定放在 
references/Project-Overrides.md
中：
markdown
undefined

Project Overrides for [Your Project]

[你的项目] 自定义规则

版本展示约定

版本展示约定

版本号格式统一为 
vMAJOR.MINOR.PATCH
，不加「版本」二字。
版本号格式统一为 
vMAJOR.MINOR.PATCH
，不加「版本」二字。

术语表

术语表

  • 「工作流」：指 Workflow 功能模块，不用「流程」
  • 「智能体」：指 Agent，不用「代理」
  • 「工作流」：指 Workflow 功能模块，不用「流程」
  • 「智能体」：指 Agent，不用「代理」

文档结构偏好

文档结构偏好

  • 每个功能页必须包含「适用场景」和「限制说明」两节

Then invoke both in your agent task:

```text
Use $tech-doc-style-chinese and references/Project-Overrides.md to rewrite this Chinese technical copy.
  • 每个功能页必须包含「适用场景」和「限制说明」两节

随后在Agent任务中同时引用核心规则与自定义规则：

```text
使用 $tech-doc-style-chinese 和 references/Project-Overrides.md 重写此中文技术文案。

Invoking the Skill

调用技能

After installation, reference it explicitly in your task:
text
Use $tech-doc-style-chinese to rewrite this Chinese technical copy.
Use $tech-doc-style-chinese to clean up this API error code table.
Use $tech-doc-style-chinese to optimize this landing page copy.
Use $tech-doc-style-chinese to review the FAQ section for style violations.
安装完成后，在任务中明确引用该技能：
text
使用 $tech-doc-style-chinese 重写此中文技术文案。
使用 $tech-doc-style-chinese 整理此API错误码表格。
使用 $tech-doc-style-chinese 优化此落地页文案。
使用 $tech-doc-style-chinese 检查FAQ部分的风格违规问题。

Troubleshooting

故障排查

Lint script reports false positives on code blocks The script targets visible body text. Wrap code samples in fenced blocks (
```
); the linter skips content inside them.
Spacing rules applied to URLs or JSON keys These are explicitly out of scope. If the linter flags them, they are likely outside a code block — move them inside one.
Skill not loading after install Restart Codex after installation. Verify with:
bash
test -f "$CODEX_HOME/skills/tech-doc-style-chinese/SKILL.md" && echo "OK"
Team members get different lint results Pin to a release tag to ensure everyone runs the same version:
bash
git clone --depth 1 --branch v0.1.0.2.4 \
  https://github.com/Fenng/tech-doc-style-chinese.git \
  "$CODEX_HOME/skills/tech-doc-style-chinese"
检查脚本误判代码块内容 脚本针对可见正文内容检查，将代码示例放在围栏代码块（
```
）中，检查器会跳过其中内容。
间距规则应用到URL或JSON键 这些内容明确不在检查范围内。如果检查器标记了它们，说明它们可能不在代码块中，请将其移入代码块。
安装后技能无法加载 安装完成后重启Codex。通过以下命令验证：
bash
test -f "$CODEX_HOME/skills/tech-doc-style-chinese/SKILL.md" && echo "OK"
团队成员检查结果不一致 固定到特定版本标签，确保所有人使用相同版本：
bash
git clone --depth 1 --branch v0.1.0.2.4 \
  https://github.com/Fenng/tech-doc-style-chinese.git \
  "$CODEX_HOME/skills/tech-doc-style-chinese"

License

许可证

MIT — see LICENSE.
MIT — 详见 LICENSE。