Tech-Doc-Style-Chinese: a writing skill that treats Chinese technical copy as a rules problem

What problem this actually solves

The README opens by refusing the usual framing. This is not a template engine and not a house style guide that forces every document into one shape. It targets four specific failure modes in Chinese technical writing, and they are concrete enough to check.

The first is that Chinese technical copy tends toward vagueness, repetition and promotional register. The second is that mixed Chinese and Latin text with numbers set inline reads badly. The third is mechanical translation of English status words. The fourth is that information density and structure drift across the four page types the author cares about most: documentation homepages, solution pages, API reference pages and FAQ pages.

That last item is the framing that makes this interesting. The target is not a blog post or a landing page, it is reference documentation and product copy where a reader arrived with a specific question. Density and structure are the right things to be opinionated about in that context.

The scope is stated as tightly as the problem. The skill applies to documentation homepages, landing pages, hero copy, API documentation with parameter and error code descriptions, changelogs, product capability pages, solution pages, and interface copy including buttons, navigation labels and prompts. It explicitly does not apply to code literals, JSON key names, URLs, API paths or database field names. A skill that tells you where not to use it is a sign the author has actually applied it.

Installing it into Codex or Claude Code

The recommended install path uses the `npx skills` CLI, and the README gives both an interactive and a non-interactive form:

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

For unattended setup targeting Codex globally, the flags are spelled out in the README: `-a codex` selects the agent, `-g` installs at user level rather than project level, and `-y` skips the confirmation prompt so the command works in automation. So the fully specified invocation is:

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

The Claude Code equivalents are the same command with `-a claude-code`, and the README notes that the global variant writes to `~/.claude/skills/` while omitting `-g` writes to `./.claude/skills/`. Claude Code decides when to invoke the skill from the `description` field in `SKILL.md`, so you do not have to trigger it by hand.

Two other install routes exist. Cloning a release tag gives you a reproducible copy, which is what the README recommends for a team that needs everyone on the same version. And copying the directory works for local development. Either way there is a verification step:

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

The README advises restarting Codex after installing so the new skill is loaded, which is a real operational step rather than a formality.

The rule set, and which rules are the load-bearing ones

The README lists the core rules, and two of them stand out as more than stylistic preference.

The first is that rewriting must preserve facts, limits, conditions and degree of certainty. This is the rule that separates this from a tone guide. The failure mode it prevents is specific: an LLM asked to make copy crisper will happily turn a qualified claim into an unconditional one. Naming certainty as something the rewriter must carry across unchanged is the correct instruction, and it is one most style documents omit.

The second is the mechanical-translation ban on status words. The README calls out `Success`, `Invalid` and `Bad Request` as examples of English strings that get translated word for word into Chinese, which produces copy that is technically accurate and practically useless to a reader scanning an error table. What to put there instead is left to the reference files, which is the right division of labour.

The typography rules are the ones you will feel most. Chinese quotation marks are unified on the corner bracket form `「」`. Spacing is handled in visible prose at the boundary between Chinese and Latin text or numbers, so a version string or a port number does not sit jammed against a Chinese character. And Chinese paragraphs stay one line per paragraph in the source file, with no hard wrapping, which is a source formatting rule rather than a typography rule and has its own script.

There is also a deliberate ban on high-frequency internet jargon of the kind that reads as internal shorthand at the company that uses it and as marketing everywhere else. The README names four such terms explicitly as words to avoid. These are precisely the words that read as marketing in Chinese technical copy while sounding like normal internal vocabulary to the person who typed them, which is why a written rule helps more here than a general request for restraint.

The linter, its three severity levels, and what it protects

The repository ships `scripts/lint_copy_rules.py`, described as a zero-dependency checker, and the severity model is the interesting design decision. Results come back in three categories: `error` for high-certainty mistakes which cause a non-zero exit by default, `warning` for context-dependent expressions that need a human, and `style` for project-specific preferences.

Three tiers rather than one matters because a copy linter that fails on every arguable phrase gets disabled within a week. Warnings are the pressure valve, and keeping them non-fatal is what lets the error list stay trustworthy.

The checker also protects the places where prose rules must not apply. Code blocks, inline code, URLs, Markdown link targets and single or multi-segment API paths are skipped. The README also notes that context-dependent items such as a deadline expression, logging in to the moon, preparing a solution and the token H5 were demoted from hard errors, which is an admission that an earlier version of the rules was too confident.

Running it is three commands depending on scope and strictness:

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

The first checks everything, the second limits it to named files or a directory, and the third promotes warnings and style hints to failures, which is the form you want in CI. There is also a per-line escape hatch using an HTML comment marker, for a line that genuinely has to keep its original wording. The test suite runs with `python -m unittest discover -s tests -v`, and a GitHub Actions workflow at `.github/workflows/skill-lint.yml` runs the check on pull requests and pushes to `main`.

The unwrapper, and why one line per paragraph is enforced

`scripts/unwrap_md_paragraphs.py` exists to enforce one thing: Chinese paragraphs are one line per paragraph in the source. The stated reason is source line width, and the second reason is more interesting. Hard wrapping in the middle of a paragraph makes the file read as fragments, and at the boundary between Chinese and English text a hard line break can gain or lose a space depending on the renderer.

The script scans structure before joining anything, and the protected list is long enough to be worth reading as a specification of what a Markdown parser considers structure: front matter, fenced code blocks including fences written after a list marker, indented code blocks inside list items, table rows, headings, horizontal rules, multi-line HTML blocks including `pre`, `script`, `style`, `textarea` and comments, link reference definitions, block quotes, and explicit line breaks marked by two trailing spaces or a trailing backslash.

Joining respects the same CJK and Latin spacing rule the prose rules impose. Chinese next to Chinese gets no space, Chinese next to half-width English or a digit gets exactly one space, and full-width punctuation gets no space on either side.

The three modes cover the workflow you would actually want:

python scripts/unwrap_md_paragraphs.py --check .
python scripts/unwrap_md_paragraphs.py docs/ README.md
python scripts/unwrap_md_paragraphs.py --stdout docs/guide.md

`--check` reports without writing, the plain form writes in place, and `--stdout` prints without writing. A whole file can be exempted with an `unwrap-disable-file` marker on its own line, which only takes effect outside code blocks and HTML blocks so it cannot be triggered accidentally by example text. The script's own limitation is stated plainly: it only fixes the join boundaries and leaves whitespace, punctuation and wording inside paragraphs alone, so a human still reviews the result.

Repository layout, project overrides, and where the limits are

The structure is documented as a tree in the README, and each file has a stated role. `SKILL.md` is the entry point consumed by agents. `NoCode-Skill.md` is a public explanation suitable for reading and sharing. `README.md` is the repository homepage. `agents/openai.yaml` is skill display metadata. `references/` holds the detailed rules read per task, including terminology and typography, controlled technical Chinese, API status copy and a project override template.

The override mechanism is the part that shows the author's intent. The core rules deliberately do not hard-code a version display format, brand voice, glossary or information architecture, because those are project-specific. Instead you create your own override file in the target project, starting from `references/project-overrides-example.md`, and put version display conventions, terminology preferences, documentation structure preferences and project-specific examples in it. The README warns explicitly not to treat the example template as active business terminology, which is the failure mode a template file invites.

The limits are honest and worth repeating. This is a Chinese-language skill, so it does nothing for English documentation. It excludes machine-readable identifiers entirely. And it is a set of rules plus two scripts, not a model or a service: it will not rewrite your documentation for you unless you wire it into an agent that can, which is why the install instructions target Codex and Claude Code rather than a CLI.

It is MIT licensed, releases run to v0.3.0 published on 2026-08-07 with v0.2.0.4.9 and v0.2.0.4.8 before it, and the last push was on 2026-09-13. A version line that reaches patch-level tags like `v0.2.0.4.9` is telling you the author iterates on rule text frequently, so pinning a release tag rather than tracking the default branch is the sane choice for a team.

Editorial conclusion

This skill earns its place when you publish Chinese technical documentation and your actual problem is tone and consistency rather than a lack of writing ability, because the rules are specific enough to be checked by a script instead of argued about in review. It is the wrong tool for code comments, JSON keys, URLs or database field names, which the README explicitly excludes, and it is the wrong tool for English copy. The repository is not archived, the last push was on 2026-09-13, and releases run to v0.3.0 from 2026-08-07, so the rule set is still moving. Install it with `npx skills add https://github.com/Fenng/tech-doc-style-chinese`, read `SKILL.md` before you trust the linter, and run `python scripts/lint_copy_rules.py --strict SKILL.md references/` to see whether your existing docs already violate it.

Frequently asked questions

Official sources

1. Fenng/Tech-Doc-Style-Chinese on GitHub
2. Issues
3. License: MIT
4. README
5. Releases