为什么现在要做这件事
技术文档面对的读者已经变了。过去主要是工程师阅读页面，现在越来越多场景是人和 AI 一起工作：人做判断，AI 负责找资料、整理步骤、辅助执行。
如果文档只有网页形态，AI 通常要先处理 HTML，再从导航、样式和无关信息里抽正文。这一步会损耗准确率，也会拖慢响应。
所以文档 Skill 化要解决的不是一个新名词，而是一个实际问题：同一套知识，怎么同时服务人和 AI。
什么是文档 Skill 化
可以把它分成两层来理解。
第一层是让文档可被 AI 消费。常见入口是 llms.txt、llms-full.txt，以及页面级的 .md 出口。重点是让 AI 能稳定拿到结构化内容。
第二层是 Skill 仓库。用 SKILL.md 把流程、约束和最佳实践写成可调用能力，回答的是「在什么场景用什么规则」。
这两层是配合关系：前者提供内容入口，后者约束使用方式。
一条能落地的推进路线
先补 AI 入口，不必一上来重构全部文档。把 llms.txt 做出来，把关键页面的 .md 出口补齐，再根据需要提供 llms-full.txt。这样先保证能读，再慢慢把读得准、用得稳做起来。
然后把高频动作沉淀成 Skill。比如 SQL 文档写法、运维排障流程、升级检查项，这类内容复用率高，也最容易因为口径不一致出问题。
检索层建议采用「先检索，再读取」。在文档规模大、更新快的前提下，不要把全文一次塞进上下文。可以走 MCP，也可以走数据库查询层。关键不在接入形态，而在按需返回。
结合 oceanbase-doc-skills 的实践，这条路已经可行：skills、rules、examples 三张表存结构化知识，QueryService 按技能名、分类、关键词取回结果，再交给上层调用。
现有案例怎么做
Nuxt 的思路是先把入口标准化。官方给出 llms.txt 相关能力，Nuxt Content 也提供 LLM 集成模块。它不是手工维护两套文档，而是在原有内容体系上增加 AI 消费出口。
Docus 更偏「站内能力」。它把 AI Assistant 和 MCP 放进文档站，AI 不用预加载全站，而是按需检索。这样上下文压力小，命中也更可控。
Vite 的路径很直接：文档页和 Markdown 页一一对应，guide 对应 guide.md。再配合 llms.txt 做目录入口，形成「先定位，再按页拉取」的流程。工程改造成本相对低。
Cloudflare 的做法完整度高一些。文档入口、Skills 和检索能力是连在一起的，基本形成了内容、规则、调用闭环。
Anthropic 侧重点是标准化本身。通过 Agent Skills 规范和示例仓库，把 Skill 的元数据、触发描述、正文组织方式固定下来，便于跨工具复用。
这个方向带来的直接价值
第一是维护成本下降。一份知识源可以同时供网页阅读和 AI 调用，减少重复维护。
第二是团队记忆负担下降。运维语句、SQL 规范、排障流程从「靠人记」变成「按需调用」。
第三是离线场景更可用。内网或隔离环境下，llms-full.txt 和本地 Skill 可以支持本地检索与辅助执行。
第四是输出更一致。流程和格式前置到 Skill 里，不同人、不同模型之间的偏差会小很多。
需要提前处理的问题
这不是一次性工程。规范在变、工具在变、模型也在变，Skill 需要持续维护。
如果文档体量大，最忌讳一步到位。更稳妥的方式是先选高价值域试点，再逐步扩展。
另外，人读版本和 AI 消费入口要有同步机制。没有同步，最终会变成两套文档分叉。
最后，Skill 指令必须可执行、可验证。规则写得太抽象，落地时就会失控。
结论
文档 Skill 化不是换一种写文档的方法，而是重构知识交付路径：让同一份内容同时支持阅读、检索和执行。对技术团队来说，它最终体现为更低的沟通成本、更稳定的交付质量和更快的问题闭环。
