文档专家Skill：把“能看懂”的文档，升级成“找得到、读得下去、维护得起”的文档
- 六维体检：从结构与组织、内容连贯性与流程、受众定位与清晰度、导航与可发现性、内容维护与质量、视觉设计与可读性六个维度系统诊断文档问题，而不是零散地“改改错别字”。
- 真实命令驱动：技能内置
find、wc、grep、npx markdownlint-cli、npx markdown-link-check等可执行命令，先量化现状（文件数、最大文件、导航深度、死链），再谈改造。 - 三级渐进修复：每个问题都给出“快速修复 → 适当修复 → 最佳实践”三层路径，小团队可以先止血，成熟团队可以直接上 Diátaxis 框架。
- 边界清晰、懂得转交：遇到 API 文档、国际化、Markdown 语法、视觉设计系统等超纲问题，会明确提示改用对应子代理并停止，避免“什么都能聊、什么都做不深”。
- 可验收：给出导航深度 ≤3 级、单文档 <3000 字、术语一致性 >90%、零损坏链接、6 个月内更新等量化成功指标，改造效果可度量。
1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？
技能中文名：文档专家Skill 技能英文名：documentation-expert 技能ID：11756
它要解决的问题非常具体：文档“写了不少，但没人看得懂、找不到、也没人维护”。典型症状包括——导航层级一路挖到四五级（getting-started/installation/prerequisites/system-requirements.md 这种）；单个文档超过一万字还不拆分；孤儿页面没有任何入站链接；术语在 setup、set-up、set up 之间反复横跳；内部链接早就失效；初学者和专家内容混在同一页；大段无断点的“文字墙”。这个技能的价值在于：把技术写作的成熟方法论，变成 AI 可以自动执行、逐条落地的检查流程。
“一键安装”的思路与步骤（具体命令与入口以官方说明为准，下同）：
- 确认前提：该技能面向 Claude Code 环境使用，本质是一个具备文档专业知识的子代理/技能，依赖 Reads、Grep、Glob、Bash、Edit、MultiEdit 等文件与命令工具能力，因此需要你的 AI 编码环境已支持技能（Skill）加载机制。
- 定位技能：在技能市场或技能目录中，用技能ID 11756 或英文名 documentation-expert 检索，可快速锁定目标，避免同名技能混淆。
- 完成安装：按官方说明执行安装或导入操作（可能是技能市场点击安装，也可能是将技能目录放入本地技能路径），安装后通常需要重启会话或刷新技能列表才能生效。具体命令与安装路径请以官方说明为准。
- 验证是否生效：在会话中直接提出文档类诉求，例如“帮我体检一下 docs/ 目录的文档结构”。若技能已正确加载，它会先执行结构与规模检测命令（如
find docs/ -name "*.md" | head -5、find . -name "README*"、test -f mkdocs.yml），并输出“检测到 Markdown 文档”“检测到 MkDocs”一类的环境判断，而不是立刻开始泛泛而谈——出现这类“先探测再分析”的行为，基本可以确认技能已生效。
2. 该技能的主要功能和特点
核心功能：
- 文档结构诊断：识别导航层级过深（>3 级）、超大文档未拆分、孤儿页面三类高频结构病，并给出扁平化、中心辐射模型（Hub & Spoke）、Diátaxis 四象限（tutorials / how-to / reference / explanation）三级修复方案。
- 内容连贯性优化：检测“主题切换无过渡词”“新信息先于上下文出现”“跨章节术语不一致”等问题，提供过渡句补写、旧信息到新信息的信息流改写、标准章节模板（概述 → 先决条件 → 概念 → 实施 → 示例 → 相关主题）三种解法。
- 受众定位校准：发现初学者与高级内容混杂、术语未定义、复杂度标错的情况，可添加“受众/先决条件/预计时间”提示头，按专业水平拆分目录，或建立角色驱动（如面向 DevOps 工程师）的写作约定。
- 导航与可发现性增强：补齐面包屑、页内目录、相关主题链接，构建分类法（taxonomy），并检测内部链接是否损坏。
- 内容维护与质量治理：通过
last_updated、version、status元数据与“90 天未更新自动列出”的审查脚本，配合 GitHub Actions 自动化代码示例测试，防止文档腐烂。 - 视觉设计与可读性规范：控制段落长度、标题层级不跳级、代码块不超过 20 行，形成可复用的文档设计令牌（正文字号、行高、最大宽度、代码背景色）。
- 工具化验证：用
markdownlint-cli做格式校验（并合理禁用 MD013 行长度、MD033 内联 HTML、MD041 首行标题这类过度严格的规则），用markdown-link-check做死链检测。
和普通工具比强在哪：
- 普通 Lint 工具只回答“格式对不对”，它能回答“结构合不合理、读者读不读得下去”。
- 通用 AI 对话会给泛泛建议，它会先跑命令拿数据——最大文件多大、最深目录几层、某个术语出现几次，再基于事实下结论。
- 内置委托优先机制：涉及 API 文档细节、国际化/本地化、Markdown 语法、视觉设计系统时，会明确输出“这需要 {专长} 专业知识，使用 {子代理}，在此停止”，避免越界给出半吊子方案。
- 交付物是可直接执行的 Edit/MultiEdit 改动 + 可勾选的代码审查清单，而不是一份读完就忘的建议书。
3. 如何使用该技能？
第 1 步：交代任务边界 清楚说明文档位置、目标读者、当前痛点。示例输入：
“请对
docs/目录做一次完整的文档健康检查。目标读者是初次接入的中级后端工程师。先只输出问题清单和量化数据，不要修改任何文件。”
第 2 步：让它先做初始评估
技能会执行结构扫描（总 Markdown 文件数、最大的 5 个文件、根目录 README/CHANGELOG、docs/ 下的目录深度分布），并识别文档工具链（MkDocs、Docusaurus、VitePress）。输出通常是“现状数据 + 异常项”的清单。
第 3 步：看它按六类归因
输出会把问题归入结构、连贯性、受众、导航、维护、可读性六类，并标注根因。例如“导航最大深度 4 级，超过 3 级红线”“guide.md 单文件 12,000 字未拆分”“setup / set-up / set up 三种写法各出现若干次”。
第 4 步：选择修复层级 明确告诉它走哪一层：只想止血就说“只做快速修复”；准备重构就说“按 Diátaxis 最佳实践重构目录”。示例输入：
“README 已经超过 8000 字了。请按 Diátaxis 拆成 tutorials / how-to / reference / explanation 四个目录，并新建一个中心页汇总所有安装相关链接。”
第 5 步：确认后再落地修改 技能具备 Edit、MultiEdit 能力，可以直接改写文件。稳妥做法是先让它出“改动计划（改哪些文件、改成什么结构）”，你确认后再执行批量修改。
第 6 步：发布前跑验证
在主要文档发布前，让它执行完整验证套件：npx --yes markdownlint-cli --disable MD013 MD033 MD041 -- "*.md" "[DOC_FOLDER]/**/*.md" 做格式检查，npx --yes markdown-link-check "*.md" "[DOC_FOLDER]/**/*.md" 做链接检查（[DOC_FOLDER] 需替换为实际文档目录）。针对性排查时，还可让它统计过渡词数量、核对术语一致性、逐文件检查内链目标是否存在。
第 7 步：对照清单验收 最后用技能自带的代码审查清单逐项打勾：结构（≤3 级导航、单文档 <3000 字、无孤儿页面）、内容（术语一致、章节过渡、缩写首次定义）、体验（受众明确、先决条件前置、面包屑、每页 3-5 个相关链接）、维护（更新日期可见、版本最新、无死链、示例已测试）、视觉（标题层级一致、段落 <5 行、代码块 <20 行）、可访问性（链接文本具描述性、图片有替代文本、标题结构适配屏幕阅读器、颜色非唯一意义指示）。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 文档专家Skill（documentation-expert） | AI 文档架构与质量顾问 | 六维诊断、三级渐进修复、信息架构重构、命令化验证、审查清单 | 需支持技能加载的 Claude Code 环境，安装后即可自然语言调用（以官方说明为准） | 文档库整体重构、README 拆分、导航治理、发布前门禁 | 优势：覆盖“结构+内容+体验”全链路，先量化再动手；不足：依赖 AI 环境，深度 API 文档需转交专用子代理 |
| 通用 AI 对话模型 | 通用问答与写作助手 | 生成、润色、解释、改写 | 门槛最低，打开即用 | 单篇文档润色、临时写作求助 | 优势：灵活通用；不足：缺方法论骨架与量化检查，易给“正确的废话”，不会主动跑命令核对现状 |
| markdownlint-cli / markdown-link-check 等检查工具 | 单点自动化校验 | 格式规则校验、死链检测 | 命令行调用，npx 即可，无需安装 |
CI 流水线、提交前预检 | 优势：确定性强、速度快、可进流水线；不足：只查“格式对不对”，不判断信息架构、受众定位、可读性 |
| 人工技术写作与文档评审 | 专业人力评审 | 深度内容设计、风格统一、长期治理 | 需专业人力与评审周期，成本较高 | 对外发布的重要文档、合规文档 | 优势：判断力最强、懂业务语境；不足：成本高、周期长、难以覆盖全部文档 |
选型建议：把格式与死链交给检查工具进 CI，把“结构与体验”的批量诊断和改造交给文档专家Skill，把最关键的对外文档终审留给人工——三者是互补关系，不是替代关系。
5. 该技能的典型应用场景与实际体验情况
场景一：开源项目维护者接手“历史遗留”README 角色：个人开源作者或新晋维护者。痛点：README 一路膨胀到上万字，从安装到架构全塞在一页，新人第一个 issue 永远是“怎么装都装不上”。使用方式：让它先统计 README 字数与章节结构，再按 Diátaxis 拆成 tutorials / how-to / reference / explanation 四个目录，并生成一个中心概览页，各辐射页反向链回。实际体验：上手几乎没有门槛，一句自然语言就能拿到“问题清单 + 目录树改造方案”；效果最明显的是“导航层级”和“单文档体积”两项指标，往往一次就能从 4 级压到 2 级。注意事项：目录重构属于大动作，务必先看改动计划再执行，避免一次性打乱已有外链。
场景二：技术文档团队重构 docs/ 信息架构
角色：技术写作或 DevRel 团队。痛点：文档越写越多，孤儿页面成片，术语三套写法并存，读者靠搜索硬找。使用方式：先跑全量健康检查拿到基线数据（文件总数、最大文件、深度分布、术语出现次数），再按“快速修复 → 适当修复 → 最佳实践”分三期推进，每期结束跑一次 markdownlint 与死链检测。实际体验：最大的惊喜是术语一致性检查——同一段 for term in "setup" "set-up" "set up" 统计，能把长期被忽视的写法分裂问题一眼暴露。注意事项：术语统一属于“改了就会影响所有文件”的操作，建议先在小范围目录试跑。
场景三：面向多角色的产品文档分层 角色：产品经理与研发协作团队。痛点：一页文档既要给新手看又要给资深工程师看，新手觉得术语太多，专家嫌啰嗦。使用方式：让技能按专业水平拆分 quickstart / guides / advanced，并在每篇头部加上“受众 / 先决条件 / 预计时间”提示头，同时为缩写补上首次定义。实际体验：受众指示器是成本最低、见效最快的一项改动，几乎不影响原有内容就能显著改善“打开即劝退”的问题。注意事项：拆分后要同步更新所有指向旧路径的站内链接，否则会新增死链。
场景四：文档发布前的质量门禁
角色：负责发版的研发或 CI 维护者。痛点：每次大版本更新，代码示例过时、内部链接失效，全靠人工点一遍。使用方式：发布前让技能执行完整验证套件，输出格式告警与失效链接清单；再叠加“90 天未更新文档”审查脚本，形成周期性治理。实际体验：把“零损坏链接”和“更新日期可见”变成可勾选的验收项之后，文档腐朽速度肉眼可见地下降。注意事项：markdownlint 的默认规则偏严格（行长度、内联 HTML、首行标题），按技能建议禁用 MD013 / MD033 / MD041，能大幅减少噪音告警。
6. 该技能能为用户带来的价值
效率层面：把过去需要人工逐页翻查的“文档盘点”压缩成一次命令扫描。文件规模 Top5、导航最大深度、术语出现频次、失效链接列表，这些原本要花半天的手工统计，在技能里是开箱即用的检测项。改造阶段更有价值——一次诊断输出同时包含问题定位、根因说明、三级修复方案和可直接执行的编辑动作，省掉了“发现问题—查资料—想方案”这一大段空转。
门槛层面：信息架构、Diátaxis 框架、旧新信息流、中心辐射模型这些原本属于专业技术写作领域的知识，被封装成了可调用的流程。中小团队不必专门配一名文档架构师，也能按业界公认方法论改造文档库。
可量化的收益：技能自带明确的成功指标——导航深度 ≤3 级、单文档 <3000 字（或有意拆分）、术语一致性 >90%、零损坏链接、每篇文档有清晰受众定义、每 2-3 段有过渡、所有文档 6 个月内更新。这意味着文档质量从“感觉还行”变成可以对照验收的指标，也方便向团队或上级证明改造效果。
长期价值：文档是会持续腐烂的资产。技能提供的元数据规范、季度审查脚本、CI 自动化校验，把“一次性美化”变成了“可持续维护机制”。同时，其委托优先机制保证它只在文档架构与质量这个专长区间内输出结论，遇到边界问题主动交给更专业的子代理——这种克制，恰恰是长期可信赖的基础。
7. 常见问题 FAQ
Q1：文档专家Skill 怎么安装？需要什么前提？ A：它运行在 Claude Code 环境中，需要你的 AI 环境已支持技能加载，并具备文件读写与命令执行能力（Read、Grep、Glob、Bash、Edit、MultiEdit）。在技能市场或技能目录中用技能ID 11756 或英文名 documentation-expert 检索，按官方说明完成安装，之后重启会话或刷新技能列表。具体安装命令与路径请以官方说明为准。安装后可用“帮我体检一下 docs/ 目录”这类请求验证是否生效。
Q2：这个技能收费吗？
A：技能本身的授权与计费方式取决于其发布方的规则，请以官方说明为准。需要提醒的是，它调用的 markdownlint-cli 与 markdown-link-check 通过 npx 运行，属于按需拉取的命令行工具，不构成额外安装负担。
Q3：它适合谁用？不适合谁？ A：最适合开源项目维护者、技术文档工程师、DevRel、以及需要长期维护 docs/ 目录的产品研发团队。如果你只有一两篇短文、也不打算做信息架构，用通用 AI 对话润色即可，不必动用它。另外，涉及 API 文档细节、国际化/本地化、Markdown 语法细节、视觉设计系统时，它会主动提示改用对应子代理并停止——这类需求本就该交给更专精的技能。
Q4：它和 markdownlint 这类工具是替代还是互补？ A：是互补。markdownlint 与 markdown-link-check 只判断“格式是否合规、链接是否可达”，属于确定性的机械校验；文档专家Skill 判断的是“结构是否合理、内容是否连贯、受众是否匹配”，属于判断性工作，并且它会反过来调用这些工具做验证。推荐做法是：把格式与死链检查放进 CI 流水线做常态门禁，把架构诊断与重构交给技能按需执行。
Q5：它会直接修改我的文件吗？安全吗？ A：它具备 Edit 与 MultiEdit 工具，确实可以直接改写文件。稳妥的使用姿势是分两步：先要求“只输出问题清单和改动计划，不要改文件”，确认无误后再让它执行批量编辑；同时配合版本控制，改动前后各提交一次，便于回滚。对于术语统一、目录重构这类影响面大的操作，建议先在小范围目录试跑。