A set of conventions for Chinese technical documentation: 8 rules in 3 categories.
How to use this skill
The total number of rules is small, so you can read the index first and take what you need; if you are focusing on organizing a batch of documents, reading straight through AGENTS.md is also not costly.
| What you are doing | Read first |
|---|---|
| Writing any Chinese document | cjk-*(3 rules, lowest cost and most direct benefit) |
| Writing a README / design doc | content-*、struct-heading-no-skip |
| Writing an operations manual / procedure steps | content-example-copy-ready、struct-code-fence-language |
| Organizing existing documentation | All |
What these kinds of conventions have in common
Documents fail differently from code:no compiler will tell you that you wrote it wrong. Inconsistent formatting, examples that cannot be copied, missing "why"—none of these will raise an error, but they will slowly cause readers to stop trusting the document.
And an outdated or vague document is worse than no document: it will be trusted, and then lead people astray.
Categories and impact levels
| Priority | Category | Impact | Prefix | Count |
|---|---|---|---|---|
| 1 | Content quality | HIGH | content- |
2 |
| 2 | Document structure | MEDIUM | struct- |
3 |
| 3 | Chinese typography | MEDIUM | cjk- |
3 |
Sorted by impact, not by reading order—cjk-* is the most commonly used but has the mildest consequences.
Rule index
1. Content quality (HIGH)
content-example-copy-ready— Examples use real values and can be pasted and executed directly; placeholders will be copied incorrectly, and the error happens in the reader's environmentcontent-why-not-just-what— Write clearly why; documents that only say "how" cannot be judged for whether they still apply when circumstances change
2. Document structure (MEDIUM)
struct-code-fence-language— Code blocks must be labeled with a language; labeling incorrectly is worse than not labeling, and plain output should be explicitly labeledtextstruct-heading-no-skip— Do not skip heading levels, one H1 per document, and keep depth within H4struct-table-vs-list— Use tables when there is a shared dimension, lists when there is not; do not put long paragraphs in tables
3. Chinese typography (MEDIUM)
cjk-latin-spacing— Add spaces between Chinese and Western text and inline code; consistency matters more than which choice you makecjk-number-spacing— Add spaces between Chinese and numberscjk-punctuation— Use full-width punctuation in Chinese sentences; the criterion is the primary language of this paragraph, not the entire document
Relationship to project conventions
This skill is across-project general baseline. Specific glossaries, platform names, and external copy wording are project facts and should be written in the project's CLAUDE.md, not here.
In case of conflict, the project's own conventions take precedence.
Maintenance
After changing rules/ , the full version must be regenerated:
bash scripts/build.sh