Tech-Doc-Style-Chinese README

The project's README from github.com/Fenng/Tech-Doc-Style-Chinese. As one markdown file: README.md.

Chinese Tech Doc Style

本项目只是一份面向中文技术文档、产品文案与界面文案的写作 Skill。

这份 Skill 的目标很明确:中文技术写作应更克制、更准确、更易读。不追求宣传感,也不试图把所有内容都写成统一模板,而是聚焦几类高频问题:

如果需要一套适合中文技术文档的基础写作规范,这份 Skill 可以直接拿来使用,或是作为参考。

适用场景

本 Skill 适合以下内容:

不适合以下内容:

核心规则概览

这份 Skill 主要覆盖以下规则:

完整规范请阅读:

仓库结构

tech-doc-style-chinese/
├── SKILL.md
├── NoCode-Skill.md
├── README.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── api-status-copy.md
│   ├── controlled-technical-chinese.md
│   ├── project-overrides-example.md
│   └── terminology-and-typography.md
├── scripts/
│   ├── lint_copy_rules.py
│   └── unwrap_md_paragraphs.py
└── tests/
    ├── test_lint_copy_rules.py
    ├── test_skill_structure.py
    └── test_unwrap_md_paragraphs.py

各文件的作用:

如何在 Codex 中使用

使用 npx 安装(推荐)

如果本机有 Node.js 环境,可直接用 npx skills 安装:

# 直接安装
npx skills add https://github.com/Fenng/tech-doc-style-chinese

如需无交互并明确安装到全局 Codex,可使用:

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

参数说明:

安装后建议重启 Codex,以确保新 Skill 被加载。

按 Release 安装(推荐)

固定版本安装,便于团队复现:

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

git clone --depth 1 --branch <release-tag> \
  https://github.com/Fenng/tech-doc-style-chinese.git \
  "$CODEX_HOME/skills/tech-doc-style-chinese"

<release-tag> 可替换为已发布版本,例如 v0.1.0.2.4。

本地目录安装(开发场景)

如果正在本地修改或调试,可直接复制目录:

mkdir -p "$CODEX_HOME/skills/tech-doc-style-chinese"
cp -R ./* "$CODEX_HOME/skills/tech-doc-style-chinese/"

安装后可快速校验:

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

安装完成后,可在任务中显式调用:

Use $tech-doc-style-chinese to rewrite this Chinese technical copy.

或者直接在相关任务中触发,例如:

如何在 Claude Code 中使用

直接让 Claude Code 安装(最简单)

如果当前 Claude Code 环境支持安装 Skills,可让它读取本仓库并安装:

请安装这份 Skill:https://github.com/Fenng/tech-doc-style-chinese

这种方式较省事,但具体装到项目级还是全局取决于 Claude Code 当时的能力与判断。团队协作或需要写进文档、CI 的场景,建议用下面的 npx 命令。

使用 npx 安装(推荐)

如果本机有 Node.js 环境,可直接用 npx skills 安装:

# 安装到当前项目
npx skills add https://github.com/Fenng/tech-doc-style-chinese -a claude-code

如需无交互并明确安装到全局 Claude Code,可使用:

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

参数说明:

安装后建议重启 Claude Code,以确保新 Skill 被加载。

本地目录安装(开发场景)

如果正在本地修改或调试,可直接复制目录:

mkdir -p ~/.claude/skills/tech-doc-style-chinese
cp SKILL.md ~/.claude/skills/tech-doc-style-chinese/
cp -R references ~/.claude/skills/tech-doc-style-chinese/

安装后可快速校验:

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

Claude Code 会根据 SKILL.md 里的 description 自动判断何时调用该 Skill,无须手动触发,例如:

如何做项目级覆盖

这份 Skill 只放通用规则,不把某个项目的版本展示、品牌语气、术语表或信息架构硬编码到核心规范里。

如果项目存在自己的约定,在目标项目中建立单独的覆盖文件。可以从以下模板开始:

这类覆盖文件适合放:

模板本身不包含默认生效的业务术语。不要把示例文件当成目标项目约定。

轻量校验与 CI

仓库内置了一个零依赖校验脚本,用于检查高频规则。结果分为:

检查器会保护代码块、行内代码、URL、Markdown 链接目标和单段或多段 API 路径。截止日期、登陆月球、配制溶液、H5 等语境项不再作为确定错误。

本地执行:

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/

忽略单行检查:

需要保留的原文 <!-- copy-lint-disable-line -->

运行回归测试:

python -m unittest discover -s tests -v

GitHub Actions 配置文件为 .github/workflows/skill-lint.yml,会在 pull_request 和 main 分支 push 时自动运行。

展开段落硬换行

为了控制源码行宽而在段落中间手动断行,会让源文件读起来很碎;中文与英文边界上的断行还会在部分渲染器里多出或吞掉空格。仓库提供一个零依赖脚本,把段落和列表项还原为「一段一行」,正文靠编辑器软换行阅读。

检查是否存在硬换行,不改动文件:

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

拼接边界按中西文留白规则处理:中文与中文之间不加空格,中文与半角英文、数字之间加一个空格,全角标点两侧不加空格。

脚本先扫描结构再拼接段落,因此以下内容按整块保留,不只保护起始行:front matter、围栏代码块(包括写在列表标记之后的 - ```sh)、缩进代码块(包括列表项内的缩进代码)、表格行、标题、分隔线、多行 HTML 块(<pre>、<script>、<style>、<textarea> 和注释)、链接引用定义、引用块,以及行尾两个空格或反斜杠表示的显式换行。

需要整份文件跳过时,在代码块之外单独用一行写出标记:

<!-- unwrap-disable-file -->

标记只在独立成行且不在代码块、HTML 块内时生效,因此上面这段代码示例不会让本文件免检。

脚本只处理拼接边界,不修改段落内部已有的留白、标点和措辞。展开后仍需人工复查一遍边界留白和列表、表格结构。

发布建议

如果只是公开分享规范内容:

如果希望别人能直接安装使用:

License

本项目采用 MIT License。
详见 LICENSE。

Tech-Doc-Style-Chinese (Fenng/Tech-Doc-Style-Chinese)

Searching Database…

What is this?It is a reusable writing 'Skill' (a rule file plus helper scripts) for Chinese technical documentation and product copy, meant to be loaded by AI coding agents like Claude Code or Codex so they rewrite Chinese text more precisely and less like marketing fluff.
Is this a skill file or also a standalone tool?It is primarily a SKILL.md rule file that agents read to change how they write Chinese, but the repo also ships a small zero-dependency Python linter and a paragraph-unwrapping script you can run yourself.
How do I install it for Claude Code or Codex?The recommended way is `npx skills` with `-a codex` or `-a claude-code` to install it (add `-g` for a global install, `-y` to skip prompts); you can also install a pinned release version or just copy the folder locally for development.
Do I need Node.js to install it?Yes for the recommended npx-based install path; alternatively you can install from a GitHub Release or by copying the repo folder directly without Node.js.
What kind of text does it deliberately leave alone?It is meant for prose like docs, landing pages, API descriptions and UI copy, but it explicitly does not touch code literals, JSON keys, URLs, API paths, database field names or other machine-readable identifiers.
What core writing rules does the Skill enforce?It keeps facts, constraints and certainty levels intact when rewriting, uses the corner quotes 「」 for Chinese quotation marks, adds spacing between Chinese and English/numbers in visible text, keeps one paragraph per line in source files, and avoids literal translations of English status words (Success, Invalid, Bad Request) and internet buzzwords like 赋能/抓手/闭环.
Does the repo include an automated checker?Yes, scripts/lint_copy_rules.py is a zero-dependency linter that flags issues as error, warning, or style, and it is wired into GitHub Actions (.github/workflows/skill-lint.yml) to run on pull requests and pushes to main.
What does the paragraph-unwrap script do?scripts/unwrap_md_paragraphs.py reflows manually hard-wrapped Markdown paragraphs and list items back into single lines, respecting Chinese/English/number spacing rules, while protecting code blocks, front matter, and URLs.
Can I customize the rules for my own project?Yes, you add a separate override file (starting from references/project-overrides-example.md) in your target project for version-display conventions, terminology, or structure preferences, since the core Skill intentionally stays generic.
Creator
Fenng
Size
0.1 MB
Stars
1.5K
Age
6mo
Commits · 90 Days