tech-doc-style-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.

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

Installation

Via npx (Recommended)

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

# Non-interactive, global install to Codex
npx -y skills add https://github.com/Fenng/tech-doc-style-chinese -a codex -g

Pin a specific release

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

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"

Running the Lint Script

# Lint everything
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.

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

Core Rules Reference

Typography & Spacing

Add a space between Chinese and English/numbers in visible body text:

# Wrong
支持JSON格式和XML格式

# Correct
支持 JSON 格式和 XML 格式

# Wrong
版本号为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.

Quotation Marks

Use corner brackets 「」 for visible Chinese body text, not curly quotes:

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

# Correct
这是一个「示例」说明

Avoid Direct Address

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

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

Status Word Translation

Avoid mechanical translation of English HTTP/API status terms:

English	Wrong	Correct
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)

Wrong	Correct
阀值	阈值
登陆	登录
布署	部署
配制	配置
起用	启用
反回	返回
回朔	回溯
标示	标识
帐户	账户
帐号	账号
截止	截至

Term Casing (Lint Enforces)

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

# Correct
ID  HTTP  URL  JSON  API  AI  JavaScript  HTML5  LLM  AIGC  RAG

Content Type Guidelines

Landing Pages & First Screens

# Wrong — vague, marketing-heavy
我们致力于打造业界领先的、赋能开发者的一站式 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

API & Parameter Docs

## 请求参数

| 参数名    | 类型   | 必填 | 说明                          |
|-----------|--------|------|-------------------------------|
| user_id   | string | 是   | 用户唯一标识，长度 8–32 位    |
| page      | int    | 否   | 页码，从 1 开始，默认为 1     |
| page_size | int    | 否   | 每页条数，范围 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

Error Code Docs

## 错误码说明

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

FAQ Pages

# Wrong — repeats the question
Q: 如何重置密码？
A: 重置密码的方法如下……

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

Changelogs

## v2.3.0 — 2024-03-15

### 新增
- 支持通过 API 批量导入用户，单次上限 1000 条

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

### 变更
- `GET /v1/users` 返回结构新增 `created_at` 字段

Button & UI Copy

# Wrong — abstract, duplicates surrounding heading
立即体验  了解更多  点击查看

# Correct — names the next action
开始免费试用  查看接口文档  下载 SDK

Project-Level Overrides

Keep the core skill generic. Put project-specific conventions in references/Project-Overrides.md:

# Project Overrides for [Your Project]

## 版本展示约定
版本号格式统一为 `vMAJOR.MINOR.PATCH`，不加「版本」二字。

## 术语表
- 「工作流」：指 Workflow 功能模块，不用「流程」
- 「智能体」：指 Agent，不用「代理」

## 文档结构偏好
- 每个功能页必须包含「适用场景」和「限制说明」两节

Then invoke both in your agent task:

Use $tech-doc-style-chinese and references/Project-Overrides.md to rewrite this Chinese technical copy.

Invoking the Skill

After installation, reference it explicitly in your task:

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.

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:

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:

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.