更新了一下 Chinese Tech Doc Style ，面向中文技术文档、产品文案与界面文案的写作 Skill。

居然快 400 Stars 了……😂

https://t.co/OtoXT4vMMc

Fenng/tech-doc-style-chinese

Source: https://github.com/Fenng/tech-doc-style-chinese

Chinese Tech Doc Style

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

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

• 中文技术文案容易空泛、重复、宣传化
• 中文与英文、数字混合排版时可读性差
• 常见英文状态词和错误词容易被机械直译
• 文档首页、解决方案页、接口说明页、FAQ 的信息密度和结构经常失衡

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

适用场景

本 Skill 适合以下内容：

• 文档首页、落地页、首屏文案
• 接口文档、参数说明、错误码说明、更新日志
• 产品能力介绍、解决方案页、能力说明页
• 界面文案、按钮文案、导航标签、提示信息

不适合以下内容：

• 代码字面量
• JSON 键名
• URL
• API 路径
• 数据库字段名
• 其他机器可读标识符

核心规则概览

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

• 中文引号统一使用直角引号 「」
• 不使用 你、您、同学 这类直接称呼
• 在可见正文中处理中文与英文、数字之间的留白
• 避免机械直译 Success、Invalid、Bad Request 等英文状态词
• 避免高频互联网黑话，如 赋能、抓手、闭环、打通
• 按钮文案应体现下一步动作，避免与标题重复
• 移动端优先保证可读性，而不是继续沿用桌面排版

完整规范请阅读：

• NoCode-Skill.md

仓库结构

tech-doc-style-chinese/
├── SKILL.md
├── NoCode-Skill.md
├── README.md
├── agents/
│   └── openai.yaml
└── references/
    └── Project-Overrides.md

各文件的作用：

• SKILL.md：正式技能入口，供 Codex、Claude Code 等 Agent 使用
• NoCode-Skill.md：对外说明稿，适合公开阅读和分享
• README.md：GitHub 仓库首页说明
• agents/openai.yaml：技能展示元数据
• references/Project-Overrides.md：项目私有约定示例

如何在 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

参数说明：

• -a codex 表示安装到 Codex agent
• -g 表示全局安装（用户级），不加则安装到当前项目范围
• -y 表示跳过交互确认，便于自动化执行

安装后建议重启 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.

或者直接在相关任务中触发，例如：

• 重写中文技术文案
• 整理 FAQ
• 优化 API 文档措辞
• 优化落地页中文文案

如何在 Claude Code 中使用

直接让 Claude Code 安装（最简单）

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

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

这种方式较省事，但具体装到项目级还是全局、是否附带 references/Project-Overrides.md，取决于 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

参数说明：

• -a claude-code 表示安装到 Claude Code
• -g 表示全局安装（用户级，写入 ~/.claude/skills/），不加则安装到当前项目范围（写入 ./.claude/skills/）
• -y 表示跳过交互确认，便于自动化执行

安装后建议重启 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，无须手动触发，例如：

• 重写中文技术文案
• 整理 FAQ
• 优化 API 文档措辞
• 优化落地页中文文案

如何做项目级覆盖

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

如果项目存在自己的约定，建议通过单独的覆盖文件管理，例如：

• references/Project-Overrides.md

这类覆盖文件适合放：

• 版本展示约定
• 品牌或术语偏好
• 文档结构偏好
• 当前项目特有示例

这样可以保持核心 Skill 可复用，同时允许项目自行扩展。

轻量校验与 CI

仓库内置了一个零依赖校验脚本，用于检查高频规则：

• 引号：禁止可见正文出现 "、“、”
• 称呼：禁止可见正文出现 你、您、同学
• 术语大小写：检查 id/http/url/json/api/ai 等写法并提示归一
• 指定缩写：检查 JS / Js / H5 并提示改为 JavaScript / HTML5
• AI 术语：检查 llm/aigc/rag/chatgpt/openai api/embeding/finetune/fine tune 等误写
• 中文错词：检查 阀值/登陆/布署/配制/起用/反回/回朔/标示/帐户/帐号/截止/搜寻/即时/做为

本地执行：

python scripts/lint_copy_rules.py

仅检查指定文件或目录：

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

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

发布建议

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

• 保留 NoCode-Skill.md
• 用 README.md 做仓库首页说明

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

• 保留 SKILL.md
• 保留 agents/openai.yaml
• 在仓库里明确目录结构和安装方式

License

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