Chinese Tech Doc Style

Chinese Tech Doc Style 是一份专为中文技术文档、产品文案及界面文案设计的写作 Skill，核心目标是提升内容的克制性、准确性与可读性。它针对中文技术写作中常见的空泛宣传、中英数字混排混乱、英文状态词机械直译、信息结构失衡等问题提供具体规则，不追求统一模板或营销感。

核心规则体系：从语言细节到信息架构

1. 语言准确性规则

2. 排版与可读性规则

• 中英数字留白：正文可见区域自动处理空格（如「使用 Python 3.10 运行」），代码块/URL内不添加
• 避免直接称呼：默认不使用「您」「亲」等称谓，允许项目语气覆盖文件自定义
• 状态词本土化：Success→「成功」，Failed→「失败」，但保留原始错误码供排查

3. 信息结构平衡规则

• 文档首页：首屏明确价值主张+核心入口，避免堆砌功能列表
• API说明页：参数表格优先于长段落，错误码独立成节
• FAQ：问题按用户任务分组，答案前置结论再展开
• 解决方案页：场景→方案→收益三段式，避免纯功能罗列

安装与集成指南

Codex 安装方式

# 推荐：npx全局安装（无交互）
npx -y skills add https://github.com/Fenng/tech-doc-style-chinese -a codex -g

# Release固定版本（团队协作）
CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
git clone --depth 1 --branch v0.1.0.2.4 \
  https://github.com/Fenng/tech-doc-style-chinese.git \
  "$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... 或自然语言触发（如「优化API文档措辞」）

Claude Code 安装方式

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

# 本地安装
mkdir -p ~/.claude/skills/tech-doc-style-chinese
cp SKILL.md references/* ~/.claude/skills/tech-doc-style-chinese/

Claude Code 根据 SKILL.md description 自动判断调用时机，无需显式指令

项目级覆盖机制
在目标项目创建 references/project-overrides-example.md，自定义：

• 版本展示格式（如「v2.3.1」vs「2024.06」）
• 品牌术语表（如「云原生」vs「Cloud Native」）
• 文档结构偏好（如FAQ置顶/底部）
• 特有示例库
  ⚠️ 覆盖文件仅作用于当前项目，不影响全局Skill

质量保障：校验脚本与CI集成

零依赖校验工具

# 基础检查（error级失败）
python scripts/lint_copy_rules.py

# 严格模式（warning/style也失败）
python scripts/lint_copy_rules.py --strict SKILL.md references/

# 指定文件检查
python scripts/lint_copy_rules.py docs/api.md docs/faq.md

# 单行豁免
<!-- copy-lint-disable-line --> 此处保留原文「Bad Request」因对接第三方系统

检查结果分级

CI集成

• GitHub Actions配置：.github/workflows/skill-lint.yml
• 触发时机：PR提交 + main分支push
• 保护范围：自动跳过代码块、URL、Markdown链接目标、API路径
• 回归测试：python -m unittest discover -s tests -v