Chinese Documentation
Invoke explicitly when you need agent-written Chinese technical docs to follow 中文文案排版指北-style spacing, punctuation, and mixed CN–EN typography.
Overview
Chinese Documentation is an agent skill for the Build phase that applies Chinese technical typography and mixed CN–EN spacing rules when you explicitly invoke /chinese-documentation.
Install
npx skills add https://github.com/jnmetacode/superpowers-zh --skill chinese-documentationWhat is this skill?
- 中英文、中文与数字、数字与单位之间的空格规则（含 °C、% 等例外）
- 全角标点、括号、引号（直角/弯引号）与半角技术内容的区分
- 技术文档统一半角阿拉伯数字与版本号写法
- 链接前后空格与中文语境排版一致性
- 仅响应用户显式 /chinese-documentation，不根据上下文自动触发
- References 中文文案排版指北 (Chinese copywriting guidelines) as the editorial standard
- Explicit-only invocation: do not auto-trigger from context
Adoption & trust: 565 installs on skills.sh; 4.9k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Chinese docs look unprofessional—English and numbers stick to characters, punctuation is half-width, and readers notice instant 机翻感.
Who is it for?
Builders shipping Chinese READMEs, 接口文档, or bilingual product docs who want one explicit formatting pass from the agent.
Skip if: Automatic rewriting of every chat turn, pure English-only docs, or substantive technical editing when you have not invoked /chinese-documentation.
When should I use this skill?
仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。
What do I get? / Deliverables
Copy and markdown follow consistent 中英文空格、全角标点、术语与链接格式 so Chinese technical documentation reads smoothly and on-brand.
- Typography-corrected Chinese technical prose
- Consistent spacing around English terms, digits, and links
- Punctuation and bracket rules applied per Chinese context
Recommended Skills
Journey fit
Documentation quality for Chinese-speaking users is finalized while writing READMEs, API guides, and in-app copy during Build. Docs is the canonical shelf—typography rules apply to technical writing artifacts, not runtime code paths.
How it compares
Use as an explicit typography pass for Chinese prose, not as a general translation or SEO content generator.
Common Questions / FAQ
Who is chinese-documentation for?
Developers writing Chinese technical documentation who want 中文文案排版指北-level consistency without manual find-and-fix on every paragraph.
When should I use chinese-documentation?
During Build docs tasks when you deliberately run /chinese-documentation on drafts—README, API guides, changelogs—not for auto-triggered coding help.
Is chinese-documentation safe to install?
It is formatting guidance only; review the Security Audits panel on this Prism page for the parent skill package.
SKILL.md
READMESKILL.md - Chinese Documentation
# 中文技术文档写作规范 ## 概述 中文技术文档最常见的问题不是内容不够，而是**读起来别扭**——中英文挤在一起没有空格、全角半角混用、一股机翻味。本技能提供一套完整的中文技术文档写作规范，让你的文档**专业、好读、不出戏**。 **核心原则：** 排版服务于阅读体验，规范服务于一致性，内容服务于读者。 **参考标准：** [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines) ## 中文排版规范 ### 空格 **中英文之间加空格：** ``` # 好 使用 Git 进行版本管理，配合 Jenkins 实现持续集成。 # 坏 使用Git进行版本管理，配合Jenkins实现持续集成。 ``` **中文与数字之间加空格：** ``` # 好 本次更新包含 3 个新功能和 12 个 Bug 修复。 # 坏 本次更新包含3个新功能和12个Bug修复。 ``` **数字与单位之间加空格：** ``` # 好 文件大小不超过 5 MB，响应时间控制在 200 ms 以内。 # 坏 文件大小不超过5MB，响应时间控制在200ms以内。 ``` **例外：度数、百分比等不加空格：** ``` # 好 今天气温 32°C，CPU 使用率 95%。 # 坏 今天气温 32 °C，CPU 使用率 95 %。 ``` **链接前后加空格：** ``` # 好 请参考 [官方文档](https://example.com) 获取更多信息。 # 坏 请参考[官方文档](https://example.com)获取更多信息。 ``` ### 标点符号 **中文语境使用全角标点：** ``` # 好 注意：该接口需要鉴权，请先获取 Token。 # 坏 注意:该接口需要鉴权,请先获取 Token. ``` **全角标点与英文/数字之间不加空格：** ``` # 好 项目使用 MIT 协议，详见 LICENSE 文件。 # 坏 项目使用 MIT 协议 ，详见 LICENSE 文件 。 ``` **括号的使用：** ``` # 中文语境用全角括号 请运行安装命令（详见下方说明）。 # 括号内有英文或数字时用半角括号 该项目基于 Spring Boot (v3.2.0) 开发。 # 纯英文内容用半角括号 See the documentation (README.md) for details. ``` **引号的使用：** ``` # 中文使用直角引号（推荐） 「确定」按钮触发表单提交，「取消」按钮关闭弹窗。 # 也可以使用弯引号（视团队规范而定） "确定"按钮触发表单提交，"取消"按钮关闭弹窗。 # 嵌套引号 他说：「请点击『确定』按钮。」 ``` ### 数字 ``` # 阿拉伯数字（技术文档中统一使用半角数字） 支持最多 100 个并发连接。 # 不要用中文数字写技术参数 # 坏：支持最多一百个并发连接。 # 数字使用半角字符 版本号 v2.1.0，端口号 8080，HTTP 状态码 200。 ``` ## 中英混排最佳实践 ### 术语处理原则 **保留英文的情况：** - 专有名词：React、Kubernetes、Redis、MySQL - 行业通用缩写：API、SDK、CLI、ORM、CI/CD - 命令和代码：`npm install`、`git commit` - 协议和标准：HTTP、TCP/IP、JSON、REST - 没有公认中文翻译的术语：debounce、throttle、middleware **翻译为中文的情况：** - 有公认翻译的通用概念：数据库、服务器、浏览器、框架 - 描述性短语：version control → 版本控制，load balancing → 负载均衡 - 文档标题和章节名（尽量中文，技术名词可保留英文） ### 首次出现标注翻译 技术术语首次出现时，标注中英对照： ``` # 好 本系统采用消息队列（Message Queue）实现异步通信， 使用死信队列（Dead Letter Queue）处理消费失败的消息。 # 后续出现直接使用 消息队列的消费者需要实现幂等性…… ``` ### 避免过度翻译 ``` # 好：保留业界通用英文术语 在 Controller 层做参数校验，Service 层处理业务逻辑。 # 坏：强行翻译反而看不懂 在控制器层做参数校验，服务层处理业务逻辑。 # 好 使用 Redis 做 Session 缓存。 # 坏 使用"远程字典服务"做"会话"缓存。 ``` ## API 文档中英对照格式 ### 接口文档模板 ```markdown ## 创建订单 / Create Order ### 基本信息 - **请求方式 (Method):** POST - **请求路径 (Path):** `/api/v1/orders` - **鉴权方式 (Auth):** Bearer Token - **Content-Type:** application/json ### 请求参数 (Request Parameters) | 参数名 (Field) | 类型 (Type) | 必填 (Required) | 说明 (Description) | |----------------|-------------|-----------------|-------------------| | product_id | string | 是 | 商品 ID (Product ID) | | quantity | integer | 是 | 购买数量 (Quantity)，最小值为 1 | | address_id | string | 是 | 收货地址 ID (Shipping address ID) | | coupon_code | string | 否 | 优惠券码 (Coupon code) | ### 请求示例 (Request Example) \```json { "product_id": "prod_abc123", "quantity": 2, "address_id": "addr_xyz789", "coupon_code": "SUMMER2024" } \``` ### 响应参数 (Response Parameters) | 参数名 (Field) | 类型 (Type) | 说明 (Description) | |----------------|-------------|-------------------| | order_id | string | 订单 ID (Order ID) | | status | string | 订单状态 (Order status): pending / paid / shipped | | total_amount | integer | 订单总金额，单位：分 (Total amount in cents) | | created_at | string | 创建时间 (Created at)，ISO 8601 格式 | ### 响应示例 (Response Example) \```json { "code": 0, "message": "success", "data": { "order_id": "ord_20240315001", "status": "pending", "total_amount": 9900, "created_at": "2024-03-15T10:30:00+08:00" } } \``` ### 错误码 (Error Codes) | 错误码 (Code) | 说明 (Description) | 处理建议 (Suggestion) | |---------------|--------------------|--------------------| | 40001 | 商品不存在 (Product not found) | 检查 product_id 是否正确 | | 40002 | 库存不足 (Insufficient stock) | 减少购买数量或稍后重试 | | 40003 | 优惠券已过期 (Coupon expired) | 移除 coupon_code 或更换优惠券 | ``` ### 金额表示约定 ``` # 好：明确说明单位 total_amount: 9900 // 单位：分（即 99.00 元） # 坏：不说明单位，造成歧义 total_amount: 99.00 // 是元还是分？浮点数会有精度问题 ``` ## README.md 中文模板 国内开源项目常用的 README 结构： ```markdown # 项目名称 [![License](https://img.shields.