Claude Skill

tech-doc-style-chinese

在撰写、改写、校对或审阅中文技术文档、产品文案、界面文案、Markdown 文档、API 说明、操作手册、故障排查或运维文档时使用。采用克制、准确、可扫读的中文技术写作风格;保留原文事实、限制和机器可读内容;按任务读取术语排版、API 状态文案、项目覆盖或受控中文技术写作参考。

LLM Mart · 0 points · 6 views 134 listing impressions 0 install-command copies
Download taxueseek-plainspoken-writing-_archived_Tech-Doc-Style-Chinese-03b6573.zip · 45 KB

Install

skills CLI npx skills add https://github.com/taxueseek/plainspoken-writing/tree/main/_archived/Tech-Doc-Style-Chinese
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install taxueseek-plainspoken-writing@llmmart
Git git clone https://github.com/taxueseek/plainspoken-writing.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole taxueseek/plainspoken-writing collection as a plugin from our marketplace. Git is the plain clone.

README

Chinese Tech Doc Style

本项目是一份面向中文技术文档、产品文案与界面文案的写作 Skill,支持撰写、改写、校对和审阅。

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

  • 中文技术文案容易空泛、重复、宣传化
  • 中文与英文、数字混合排版时可读性差
  • 常见英文状态词和错误词容易被机械直译
  • 文档首页、解决方案页、接口说明页、FAQ 的信息密度和结构经常失衡
  • 操作说明中的术语、条件和动作不够明确,容易造成理解或执行偏差

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

适用场景

本 Skill 适合以下内容:

  • 文档首页、落地页、首屏文案
  • 接口文档、参数说明、错误码说明、更新日志
  • 操作手册、安装与部署步骤、多步骤 API 调用流程
  • 故障排查、运维 Runbook、安全说明
  • 产品能力介绍、解决方案页、能力说明页
  • 界面文案、按钮文案、导航标签、提示信息

文档中的以下内容保持原样,不应用文案改写和排版替换:

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

核心规则概览

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

  • 改写时保留事实、限制、条件和确定程度
  • 中文引号统一使用直角引号 「」
  • 默认避免不必要的直接称呼,允许项目语气覆盖
  • 在可见正文中处理中文与英文、数字之间的留白
  • 中文段落在源文件中保持一段一行,不做硬换行
  • 避免机械直译 Success、Invalid、Bad Request 等英文状态词
  • 避免高频互联网黑话,如 赋能、抓手、闭环、打通
  • 对操作、排查和运维文档应用受控中文技术写作方法

完整规范请阅读:

借鉴 STE 的技术写作方法

本项目的受控中文技术写作模块借鉴 ASD-STE100(Simplified Technical English,简称 STE)的受控语言思路,通过一致的术语、明确的动作和清晰的逻辑顺序,减少技术说明中的歧义。

模块将可迁移的方法适配到中文写作中:

  • 同一概念使用同一首选术语,不为避免重复而轮换同义词。
  • 一个步骤包含一个主要动作,多个有先后顺序的动作拆成编号步骤。
  • 执行前必须知道的条件和风险警告放在动作之前。
  • 明确执行者、操作对象和预期结果,区分人工操作与系统自动行为。
  • 保留原文事实、限制、例外和确定程度,不为简化表达而补造信息。

这些方法主要用于操作手册、安装与部署、故障排查、运维文档、安全说明和多步骤 API 流程。概念说明和产品介绍可选择性采用术语一致、指代明确等规则,不把品牌文案、叙事文本、固定引用或短按钮文案机械改成操作步骤。

STE 面向英文技术文档,其受控词典、词性、时态和句长规则不能直接套用于中文。本项目不是该标准的中文版本,也不承诺输出符合该标准;自动检查结果不代表 STE 合规。标准背景见 ASD-STE100 官方说明。

仓库结构

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

各文件的作用:

  • SKILL.md:正式技能入口,供 Codex、Claude Code 等 Agent 使用
  • NoCode-Skill.md:对外说明稿,适合公开阅读和分享
  • README.md:GitHub 仓库首页说明
  • agents/openai.yaml:技能展示元数据
  • references/:按任务读取的详细规则和项目覆盖模板
  • scripts/lint_copy_rules.py:轻量检查器
  • scripts/unwrap_md_paragraphs.py:展开段落硬换行的工具
  • tests/:检查器、技能结构和硬换行工具的回归测试

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

这种方式较省事,但具体装到项目级还是全局取决于 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-example.md

这类覆盖文件适合放:

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

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

轻量校验与 CI

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

  • error:高度确定的错误,默认导致非零退出
  • warning:依赖语境的可疑表达,需要人工判断
  • style:项目风格和术语偏好

检查器会保护代码块、行内代码、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 块内时生效,因此上面这段代码示例不会让本文件免检。

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

发布建议

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

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

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

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

License

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

Skill manifest

中文技术文档与产品文案规范

适用范围

将本 Skill 用于中文技术内容的撰写、改写、校对和审阅,包括:

  • 文档首页、产品介绍、解决方案页和更新日志
  • API 文档、参数说明、错误码和常见问题
  • 操作手册、故障排查、运维 Runbook 和安全说明
  • 界面文案、按钮、导航、状态和提示信息

不要改写代码字面量、JSON 键名、URL、API 路径、数据库字段名、命令、配置项或其他机器可读标识符。

规则优先级

发生冲突时,按以下顺序处理:

  1. 保留事实、逻辑、限制、安全信息和法律含义。
  2. 服从用户明确要求和目标项目约定。
  3. 保持技术术语和机器可读内容准确。
  4. 改善结构、语义、语气和可扫读性。
  5. 最后处理标点、留白、大小写等排版细节。

不得为了句子更短、语气更确定或格式更统一而牺牲更高优先级的信息。

事实保真

  • 不新增原文或可靠上下文没有提供的日期、数字、时限、SLA、能力、条件、因果关系或结论。
  • 不删除前置条件、适用范围、例外、风险、安全警告、兼容性说明或失败处理。
  • 不把可能、计划、建议、通常等不确定表达改成确定事实。
  • 信息不足时保留原意,或明确标记「待确认」;不要自行补全。
  • 改写引用、法规、合同、错误原文或用户提供的固定文案时,优先保持原文并将建议单独列出。

示例:

  • 截止 4 月 12 日 -> 截至 4 月 12 日
  • 尽快处理 -> 在约定时限内处理〔具体时限待确认〕
  • 不要凭空补成 截至 2026 年 4 月 12 日 或 30 分钟内处理

先判断任务模式

撰写

  • 先确定受众、内容类型、事实来源、发布载体和篇幅。
  • 缺少会改变结论的事实时,先标记缺口,再继续组织可确认内容。

改写

  • 保留事实、逻辑关系、信息层级、限制和必要例外。
  • 默认交付完整改写稿;重大语义选择或待确认内容另行说明。

校对

  • 只处理约定范围内的错字、标点、留白、大小写和术语一致性。
  • 未经要求,不改变结构、语气或事实表达。

审阅

  • 先列问题,再给建议;按影响程度排序并引用具体原文。
  • 未经授权,不直接修改文件。

核心写作规则

语义与语气

  • 准确先于修辞,清晰先于热闹。
  • 使用克制、直接、可执行的中文。
  • 优先说明「是什么、适用于什么、需要做什么、接着看哪里」。
  • 避免问候式开场、宣传口号、空泛形容和连续堆叠黑话。
  • 默认不直接称呼读者;必要时使用明确角色,如「开发者」「实施人员」。
  • 第二人称、感叹号和品牌语气属于风格选择;项目约定或特定界面语境可以覆盖默认规则。

结构与句子

  • 一个段落承载一个主要信息点。
  • 一个句子保持一个清晰的主干;不要连续堆叠多个条件、动作和例外。
  • 列表项保持相同层级、句式和信息密度。
  • 标题反映用途,不只使用抽象名词。
  • 删除重复信息,不删除事实、条件和例外。
  • 指代可能不清时,用具体名称替代「该」「其」「此」「上述」。

术语与排版

  • 同一概念使用同一首选术语,不因追求变化而替换同义词。
  • 中文正文使用直角引号 「」,嵌套引用使用 『』;项目、地区或固定引用规范可以覆盖。
  • 在可见正文中,中文与英文、阿拉伯数字和版本号之间加一个半角空格,例如 使用 API 获取数据、等待 3 秒、版本 2.0 已发布。
  • 中文与行内代码之间加一个半角空格;链接按显示文字判断留白。中文全角标点前后不额外加空格,不修改代码、链接目标、官方名称和用户指定字面量。
  • 中文段落在源文件中保持一段一行,不为了控制行宽做硬换行;代码块、表格、标题和列表结构保持原样。
  • 术语、产品名和缩写优先采用项目规范或官方写法,不机械替换。
  • 不直接批量运行排版替换工具;先保护 Markdown、代码和机器可读内容。

详细规则见 术语与排版。

按内容类型处理

入口页和介绍页

首段优先回答:

  • 内容覆盖什么
  • 适合谁使用
  • 从哪里开始读

避免标题、正文和行动按钮重复同一信息。

API 文档

  • 请求方法、路径、字段和值使用代码环境保护。
  • 参数说明一列一义,并写清类型、单位、默认值、限制和是否必填。
  • 状态和错误文案根据实际语义翻译,不机械对应单个英文词。
  • 写明前置条件、成功结果、失败结果和恢复方式。

详细规则见 API 状态与错误文案。

界面文案

  • 按钮说明动作和目标,不重复页面标题。
  • 错误提示说明发生了什么、影响是什么,以及如何恢复。
  • 危险操作写清对象、后果和是否可撤销。
  • 空状态区分「没有数据」「尚未创建」「无权限」和「加载失败」。

操作与故障排查

对操作手册、故障排查、运维 Runbook、安全说明和多步骤 API 流程,读取并应用 受控中文技术写作。不要把这些规则机械应用于品牌文案、叙事文本或固定引用。

项目覆盖规则

先检查目标项目自己的 AGENTS.md、术语表、品牌规范、既有文档和用户指示。不要把本 Skill 仓库中的示例约定当成目标项目约定。

需要建立项目覆盖文件时,参考 项目覆盖模板,并将实际文件放在目标项目中。

编辑流程

以下流程按任务模式选择执行;校对只执行约定范围内的检查和修改。

  1. 确认任务模式、内容类型、受众和项目约定。
  2. 标记事实、数字、限制、引用和机器可读内容,建立不可改动边界。
  3. 修复语义错误、歧义、遗漏和不一致。
  4. 调整信息顺序、段落、标题和列表。
  5. 处理语气、术语、标点、留白和大小写。
  6. 对照原文复核事实、条件、否定范围、因果关系和确定程度。
  7. 运行适用的轻量检查器,并人工判断警告和风格提示。

最终检查

  • 是否新增了来源不明的日期、数字、时限、能力或结论
  • 是否遗漏了条件、例外、风险、单位、默认值或恢复方式
  • 主语、对象、否定范围、因果关系和确定程度是否保持准确
  • 同一概念是否使用同一术语
  • 标题、正文、卡片和按钮是否重复
  • 代码、路径、字段、命令和引用是否保持原样
  • 内容是否便于目标读者扫读和执行
  • 段落是否残留硬换行,拼接边界的中西文留白是否正确
  • 项目覆盖规则是否来自目标项目,而不是示例文件

参考资料路由

Files (plainspoken-writing)
  • .github
    • workflows
      • skill-lint.yml 682 B
        Loading…
  • agents
    • openai.yaml 282 B
      Loading…
  • references
    • api-status-copy.md 2.2 KB
      Loading…
    • controlled-technical-chinese.md 7.7 KB
      Loading…
    • project-overrides-example.md 1.1 KB
      Loading…
    • terminology-and-typography.md 10.6 KB
      Loading…
  • scripts
    • lint_copy_rules.py 16.5 KB
      Loading…
    • unwrap_md_paragraphs.py 23.2 KB
      Loading…
  • tests
    • test_lint_copy_rules.py 9.2 KB
      Loading…
    • test_skill_structure.py 2 KB
      Loading…
    • test_unwrap_md_paragraphs.py 16.4 KB
      Loading…
  • LICENSE 1 KB · in bundle
  • NoCode-Skill.md 3 KB
    Loading…
  • README.md 11.5 KB
    # Chinese Tech Doc Style
    
    本项目是一份面向中文技术文档、产品文案与界面文案的写作 Skill,支持撰写、改写、校对和审阅。
    
    这份 Skill 的目标很明确:中文技术写作应更克制、更准确、更易读。不追求宣传感,也不试图把所有内容都写成统一模板,而是聚焦几类高频问题:
    
    - 中文技术文案容易空泛、重复、宣传化
    - 中文与英文、数字混合排版时可读性差
    - 常见英文状态词和错误词容易被机械直译
    - 文档首页、解决方案页、接口说明页、FAQ 的信息密度和结构经常失衡
    - 操作说明中的术语、条件和动作不够明确,容易造成理解或执行偏差
    
    如果需要一套适合中文技术文档的基础写作规范,这份 Skill 可以直接拿来使用,或是作为参考。
    
    ## 适用场景
    
    本 Skill 适合以下内容:
    
    - 文档首页、落地页、首屏文案
    - 接口文档、参数说明、错误码说明、更新日志
    - 操作手册、安装与部署步骤、多步骤 API 调用流程
    - 故障排查、运维 Runbook、安全说明
    - 产品能力介绍、解决方案页、能力说明页
    - 界面文案、按钮文案、导航标签、提示信息
    
    文档中的以下内容保持原样,不应用文案改写和排版替换:
    
    - 代码字面量
    - JSON 键名
    - URL
    - API 路径
    - 数据库字段名
    - 其他机器可读标识符
    
    ## 核心规则概览
    
    这份 Skill 主要覆盖以下规则:
    
    - 改写时保留事实、限制、条件和确定程度
    - 中文引号统一使用直角引号 `「」`
    - 默认避免不必要的直接称呼,允许项目语气覆盖
    - 在可见正文中处理中文与英文、数字之间的留白
    - 中文段落在源文件中保持一段一行,不做硬换行
    - 避免机械直译 `Success`、`Invalid`、`Bad Request` 等英文状态词
    - 避免高频互联网黑话,如 `赋能`、`抓手`、`闭环`、`打通`
    - 对操作、排查和运维文档应用受控中文技术写作方法
    
    完整规范请阅读:
    
    - [SKILL.md](./SKILL.md)
    - [公开说明稿](./NoCode-Skill.md)
    
    ## 借鉴 STE 的技术写作方法
    
    本项目的[受控中文技术写作模块](./references/controlled-technical-chinese.md)借鉴 ASD-STE100(Simplified Technical English,简称 STE)的受控语言思路,通过一致的术语、明确的动作和清晰的逻辑顺序,减少技术说明中的歧义。
    
    模块将可迁移的方法适配到中文写作中:
    
    - 同一概念使用同一首选术语,不为避免重复而轮换同义词。
    - 一个步骤包含一个主要动作,多个有先后顺序的动作拆成编号步骤。
    - 执行前必须知道的条件和风险警告放在动作之前。
    - 明确执行者、操作对象和预期结果,区分人工操作与系统自动行为。
    - 保留原文事实、限制、例外和确定程度,不为简化表达而补造信息。
    
    这些方法主要用于操作手册、安装与部署、故障排查、运维文档、安全说明和多步骤 API 流程。概念说明和产品介绍可选择性采用术语一致、指代明确等规则,不把品牌文案、叙事文本、固定引用或短按钮文案机械改成操作步骤。
    
    STE 面向英文技术文档,其受控词典、词性、时态和句长规则不能直接套用于中文。本项目不是该标准的中文版本,也不承诺输出符合该标准;自动检查结果不代表 STE 合规。标准背景见 [ASD-STE100 官方说明](https://www.asd-ste100.org/about_STE.html)。
    
    ## 仓库结构
    
    ```text
    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
    ```
    
    各文件的作用:
    
    - `SKILL.md`:正式技能入口,供 Codex、Claude Code 等 Agent 使用
    - `NoCode-Skill.md`:对外说明稿,适合公开阅读和分享
    - `README.md`:GitHub 仓库首页说明
    - `agents/openai.yaml`:技能展示元数据
    - `references/`:按任务读取的详细规则和项目覆盖模板
    - `scripts/lint_copy_rules.py`:轻量检查器
    - `scripts/unwrap_md_paragraphs.py`:展开段落硬换行的工具
    - `tests/`:检查器、技能结构和硬换行工具的回归测试
    
    ## 如何在 Codex 中使用
    
    ### 使用 npx 安装(推荐)
    
    如果本机有 Node.js 环境,可直接用 `npx skills` 安装:
    
    ```bash
    # 直接安装
    npx skills add https://github.com/Fenng/tech-doc-style-chinese
    ```
    
    如需无交互并明确安装到全局 Codex,可使用:
    
    ```bash
    npx -y skills add https://github.com/Fenng/tech-doc-style-chinese -a codex -g
    ```
    
    参数说明:
    
    - `-a codex` 表示安装到 Codex agent
    - `-g` 表示全局安装(用户级),不加则安装到当前项目范围
    - `-y` 表示跳过交互确认,便于自动化执行
    
    安装后建议重启 Codex,以确保新 Skill 被加载。
    
    ### 按 Release 安装(推荐)
    
    固定版本安装,便于团队复现:
    
    ```bash
    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`。
    
    ### 本地目录安装(开发场景)
    
    如果正在本地修改或调试,可直接复制目录:
    
    ```bash
    mkdir -p "$CODEX_HOME/skills/tech-doc-style-chinese"
    cp -R ./* "$CODEX_HOME/skills/tech-doc-style-chinese/"
    ```
    
    安装后可快速校验:
    
    ```bash
    test -f "$CODEX_HOME/skills/tech-doc-style-chinese/SKILL.md" && echo "installed"
    ```
    
    安装完成后,可在任务中显式调用:
    
    ```text
    Use $tech-doc-style-chinese to rewrite this Chinese technical copy.
    ```
    
    或者直接在相关任务中触发,例如:
    
    - 重写中文技术文案
    - 整理 FAQ
    - 优化 API 文档措辞
    - 优化落地页中文文案
    
    ## 如何在 Claude Code 中使用
    
    ### 直接让 Claude Code 安装(最简单)
    
    如果当前 Claude Code 环境支持安装 Skills,可让它读取本仓库并安装:
    
    ```text
    请安装这份 Skill:https://github.com/Fenng/tech-doc-style-chinese
    ```
    
    这种方式较省事,但具体装到项目级还是全局取决于 Claude Code 当时的能力与判断。团队协作或需要写进文档、CI 的场景,建议用下面的 npx 命令。
    
    ### 使用 npx 安装(推荐)
    
    如果本机有 Node.js 环境,可直接用 `npx skills` 安装:
    
    ```bash
    # 安装到当前项目
    npx skills add https://github.com/Fenng/tech-doc-style-chinese -a claude-code
    ```
    
    如需无交互并明确安装到全局 Claude Code,可使用:
    
    ```bash
    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 被加载。
    
    ### 本地目录安装(开发场景)
    
    如果正在本地修改或调试,可直接复制目录:
    
    ```bash
    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/
    ```
    
    安装后可快速校验:
    
    ```bash
    test -f ~/.claude/skills/tech-doc-style-chinese/SKILL.md && echo "installed"
    ```
    
    Claude Code 会根据 `SKILL.md` 里的 `description` 自动判断何时调用该 Skill,无须手动触发,例如:
    
    - 重写中文技术文案
    - 整理 FAQ
    - 优化 API 文档措辞
    - 优化落地页中文文案
    
    ## 如何做项目级覆盖
    
    这份 Skill 只放通用规则,不把某个项目的版本展示、品牌语气、术语表或信息架构硬编码到核心规范里。
    
    如果项目存在自己的约定,在目标项目中建立单独的覆盖文件。可以从以下模板开始:
    
    - `references/project-overrides-example.md`
    
    这类覆盖文件适合放:
    
    - 版本展示约定
    - 品牌或术语偏好
    - 文档结构偏好
    - 当前项目特有示例
    
    模板本身不包含默认生效的业务术语。不要把示例文件当成目标项目约定。
    
    ## 轻量校验与 CI
    
    仓库内置了一个零依赖校验脚本,用于检查高频规则。结果分为:
    
    - `error`:高度确定的错误,默认导致非零退出
    - `warning`:依赖语境的可疑表达,需要人工判断
    - `style`:项目风格和术语偏好
    
    检查器会保护代码块、行内代码、URL、Markdown 链接目标和单段或多段 API 路径。`截止日期`、`登陆月球`、`配制溶液`、`H5` 等语境项不再作为确定错误。
    
    本地执行:
    
    ```bash
    python scripts/lint_copy_rules.py
    ```
    
    仅检查指定文件或目录:
    
    ```bash
    python scripts/lint_copy_rules.py SKILL.md NoCode-Skill.md references/
    ```
    
    将警告和风格提示也作为失败处理:
    
    ```bash
    python scripts/lint_copy_rules.py --strict SKILL.md references/
    ```
    
    忽略单行检查:
    
    ```markdown
    需要保留的原文 <!-- copy-lint-disable-line -->
    ```
    
    运行回归测试:
    
    ```bash
    python -m unittest discover -s tests -v
    ```
    
    GitHub Actions 配置文件为 `.github/workflows/skill-lint.yml`,会在 `pull_request` 和 `main` 分支 `push` 时自动运行。
    
    ## 展开段落硬换行
    
    为了控制源码行宽而在段落中间手动断行,会让源文件读起来很碎;中文与英文边界上的断行还会在部分渲染器里多出或吞掉空格。仓库提供一个零依赖脚本,把段落和列表项还原为「一段一行」,正文靠编辑器软换行阅读。
    
    检查是否存在硬换行,不改动文件:
    
    ```bash
    python scripts/unwrap_md_paragraphs.py --check .
    ```
    
    展开指定文件或目录,直接写回:
    
    ```bash
    python scripts/unwrap_md_paragraphs.py docs/ README.md
    ```
    
    只查看结果,不写回文件:
    
    ```bash
    python scripts/unwrap_md_paragraphs.py --stdout docs/guide.md
    ```
    
    拼接边界按中西文留白规则处理:中文与中文之间不加空格,中文与半角英文、数字之间加一个空格,全角标点两侧不加空格。
    
    脚本先扫描结构再拼接段落,因此以下内容按整块保留,不只保护起始行:front matter、围栏代码块(包括写在列表标记之后的 `- ```sh`)、缩进代码块(包括列表项内的缩进代码)、表格行、标题、分隔线、多行 HTML 块(`<pre>`、`<script>`、`<style>`、`<textarea>` 和注释)、链接引用定义、引用块,以及行尾两个空格或反斜杠表示的显式换行。
    
    需要整份文件跳过时,在代码块之外单独用一行写出标记:
    
    ```markdown
    <!-- unwrap-disable-file -->
    ```
    
    标记只在独立成行且不在代码块、HTML 块内时生效,因此上面这段代码示例不会让本文件免检。
    
    脚本只处理拼接边界,不修改段落内部已有的留白、标点和措辞。展开后仍需人工复查一遍边界留白和列表、表格结构。
    
    ## 发布建议
    
    如果只是公开分享规范内容:
    
    - 保留 `NoCode-Skill.md`
    - 用 `README.md` 做仓库首页说明
    
    如果希望别人能直接安装使用:
    
    - 保留 `SKILL.md`
    - 保留 `agents/openai.yaml`
    - 在仓库里明确目录结构和安装方式
    
    <!-- 作者:Fenng(GitHub:@Fenng) -->
    
    ## License
    
    本项目采用 MIT License。  
    详见 [LICENSE](./LICENSE)。
    
  • SKILL.md 7.9 KB
    ---
    name: tech-doc-style-chinese
    description: 在撰写、改写、校对或审阅中文技术文档、产品文案、界面文案、Markdown 文档、API 说明、操作手册、故障排查或运维文档时使用。采用克制、准确、可扫读的中文技术写作风格;保留原文事实、限制和机器可读内容;按任务读取术语排版、API 状态文案、项目覆盖或受控中文技术写作参考。
    ---
    
    # 中文技术文档与产品文案规范
    
    <!-- 作者:Fenng(GitHub:@Fenng) -->
    
    ## 适用范围
    
    将本 Skill 用于中文技术内容的撰写、改写、校对和审阅,包括:
    
    - 文档首页、产品介绍、解决方案页和更新日志
    - API 文档、参数说明、错误码和常见问题
    - 操作手册、故障排查、运维 Runbook 和安全说明
    - 界面文案、按钮、导航、状态和提示信息
    
    不要改写代码字面量、JSON 键名、URL、API 路径、数据库字段名、命令、配置项或其他机器可读标识符。
    
    ## 规则优先级
    
    发生冲突时,按以下顺序处理:
    
    1. 保留事实、逻辑、限制、安全信息和法律含义。
    2. 服从用户明确要求和目标项目约定。
    3. 保持技术术语和机器可读内容准确。
    4. 改善结构、语义、语气和可扫读性。
    5. 最后处理标点、留白、大小写等排版细节。
    
    不得为了句子更短、语气更确定或格式更统一而牺牲更高优先级的信息。
    
    ## 事实保真
    
    - 不新增原文或可靠上下文没有提供的日期、数字、时限、SLA、能力、条件、因果关系或结论。
    - 不删除前置条件、适用范围、例外、风险、安全警告、兼容性说明或失败处理。
    - 不把可能、计划、建议、通常等不确定表达改成确定事实。
    - 信息不足时保留原意,或明确标记「待确认」;不要自行补全。
    - 改写引用、法规、合同、错误原文或用户提供的固定文案时,优先保持原文并将建议单独列出。
    
    示例:
    
    - `截止 4 月 12 日` -> `截至 4 月 12 日`
    - `尽快处理` -> `在约定时限内处理〔具体时限待确认〕`
    - 不要凭空补成 `截至 2026 年 4 月 12 日` 或 `30 分钟内处理`
    
    ## 先判断任务模式
    
    ### 撰写
    
    - 先确定受众、内容类型、事实来源、发布载体和篇幅。
    - 缺少会改变结论的事实时,先标记缺口,再继续组织可确认内容。
    
    ### 改写
    
    - 保留事实、逻辑关系、信息层级、限制和必要例外。
    - 默认交付完整改写稿;重大语义选择或待确认内容另行说明。
    
    ### 校对
    
    - 只处理约定范围内的错字、标点、留白、大小写和术语一致性。
    - 未经要求,不改变结构、语气或事实表达。
    
    ### 审阅
    
    - 先列问题,再给建议;按影响程度排序并引用具体原文。
    - 未经授权,不直接修改文件。
    
    ## 核心写作规则
    
    ### 语义与语气
    
    - 准确先于修辞,清晰先于热闹。
    - 使用克制、直接、可执行的中文。
    - 优先说明「是什么、适用于什么、需要做什么、接着看哪里」。
    - 避免问候式开场、宣传口号、空泛形容和连续堆叠黑话。
    - 默认不直接称呼读者;必要时使用明确角色,如「开发者」「实施人员」。
    - 第二人称、感叹号和品牌语气属于风格选择;项目约定或特定界面语境可以覆盖默认规则。
    
    ### 结构与句子
    
    - 一个段落承载一个主要信息点。
    - 一个句子保持一个清晰的主干;不要连续堆叠多个条件、动作和例外。
    - 列表项保持相同层级、句式和信息密度。
    - 标题反映用途,不只使用抽象名词。
    - 删除重复信息,不删除事实、条件和例外。
    - 指代可能不清时,用具体名称替代「该」「其」「此」「上述」。
    
    ### 术语与排版
    
    - 同一概念使用同一首选术语,不因追求变化而替换同义词。
    - 中文正文使用直角引号 `「」`,嵌套引用使用 `『』`;项目、地区或固定引用规范可以覆盖。
    - 在可见正文中,中文与英文、阿拉伯数字和版本号之间加一个半角空格,例如 `使用 API 获取数据`、`等待 3 秒`、`版本 2.0 已发布`。
    - 中文与行内代码之间加一个半角空格;链接按显示文字判断留白。中文全角标点前后不额外加空格,不修改代码、链接目标、官方名称和用户指定字面量。
    - 中文段落在源文件中保持一段一行,不为了控制行宽做硬换行;代码块、表格、标题和列表结构保持原样。
    - 术语、产品名和缩写优先采用项目规范或官方写法,不机械替换。
    - 不直接批量运行排版替换工具;先保护 Markdown、代码和机器可读内容。
    
    详细规则见 [术语与排版](references/terminology-and-typography.md)。
    
    ## 按内容类型处理
    
    ### 入口页和介绍页
    
    首段优先回答:
    
    - 内容覆盖什么
    - 适合谁使用
    - 从哪里开始读
    
    避免标题、正文和行动按钮重复同一信息。
    
    ### API 文档
    
    - 请求方法、路径、字段和值使用代码环境保护。
    - 参数说明一列一义,并写清类型、单位、默认值、限制和是否必填。
    - 状态和错误文案根据实际语义翻译,不机械对应单个英文词。
    - 写明前置条件、成功结果、失败结果和恢复方式。
    
    详细规则见 [API 状态与错误文案](references/api-status-copy.md)。
    
    ### 界面文案
    
    - 按钮说明动作和目标,不重复页面标题。
    - 错误提示说明发生了什么、影响是什么,以及如何恢复。
    - 危险操作写清对象、后果和是否可撤销。
    - 空状态区分「没有数据」「尚未创建」「无权限」和「加载失败」。
    
    ### 操作与故障排查
    
    对操作手册、故障排查、运维 Runbook、安全说明和多步骤 API 流程,读取并应用 [受控中文技术写作](references/controlled-technical-chinese.md)。不要把这些规则机械应用于品牌文案、叙事文本或固定引用。
    
    ## 项目覆盖规则
    
    先检查目标项目自己的 `AGENTS.md`、术语表、品牌规范、既有文档和用户指示。不要把本 Skill 仓库中的示例约定当成目标项目约定。
    
    需要建立项目覆盖文件时,参考 [项目覆盖模板](references/project-overrides-example.md),并将实际文件放在目标项目中。
    
    ## 编辑流程
    
    以下流程按任务模式选择执行;校对只执行约定范围内的检查和修改。
    
    1. 确认任务模式、内容类型、受众和项目约定。
    2. 标记事实、数字、限制、引用和机器可读内容,建立不可改动边界。
    3. 修复语义错误、歧义、遗漏和不一致。
    4. 调整信息顺序、段落、标题和列表。
    5. 处理语气、术语、标点、留白和大小写。
    6. 对照原文复核事实、条件、否定范围、因果关系和确定程度。
    7. 运行适用的轻量检查器,并人工判断警告和风格提示。
    
    ## 最终检查
    
    - 是否新增了来源不明的日期、数字、时限、能力或结论
    - 是否遗漏了条件、例外、风险、单位、默认值或恢复方式
    - 主语、对象、否定范围、因果关系和确定程度是否保持准确
    - 同一概念是否使用同一术语
    - 标题、正文、卡片和按钮是否重复
    - 代码、路径、字段、命令和引用是否保持原样
    - 内容是否便于目标读者扫读和执行
    - 段落是否残留硬换行,拼接边界的中西文留白是否正确
    - 项目覆盖规则是否来自目标项目,而不是示例文件
    
    ## 参考资料路由
    
    - 术语、黑话、错词、大小写、标点、中西文留白和段落换行:读取 [术语与排版](references/terminology-and-typography.md)
    - API 状态、错误码和常见英文状态词:读取 [API 状态与错误文案](references/api-status-copy.md)
    - 操作步骤、故障排查、安全说明和运维文档:读取 [受控中文技术写作](references/controlled-technical-chinese.md)
    - 建立目标项目自己的约定:读取 [项目覆盖模板](references/project-overrides-example.md)
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.