Docsbook
概览

docs-skills：面向文档中 AI 代理的模块化能力

在 2026 年，AI 代理不只是阅读文档——它们还会对文档执行操作。它们可以发布文档站点、修复失效链接、生成 llms.txt、编写缺失页面、审核无障碍性。它们之所以知道如何执行这些操作，是因为有“技能”——经过打包、可发现且以声明方式描述的能力。

本文将介绍技能是什么、Docsbook 的开源目录目前包含哪些内容，以及这一层如何连接 MCP 与你的内容。

简要概述#

  • “技能”是一个包含 frontmatter 的 SKILL.md 文件，用于描述某项能力——它的功能、触发时机以及所需工具
  • AI 代理（Claude Code、Cursor）会读取技能并自主执行
  • docs-skills 是一个包含四项文档技能的开源目录
  • Docsbook MCP 公开 find_skill，使代理能够在运行时通过查询发现技能
  • 你可以在本地安装技能（npx docs-skills install），也可以通过 MCP 使用它们

技能的形式#

一个最简的 SKILL.md：

---
name: docs-pr-check
description: Validate documentation changes in a pull request — check for broken links, missing frontmatter, accessibility issues, and SEO regressions. Use when reviewing docs PRs.
category: automation
mode: agent
keywords: [pull request, broken links, frontmatter, review]
requires_docsbook_mcp: true
version: 1
---
 
# docs-pr-check
 
When the user opens a docs PR, run this skill to validate the change.
 
Steps:
 
1. Run `doc_search_unresolved` to find broken links in changed files
2. Verify YAML frontmatter on every new or modified `.md` file
3. Check that internal links resolve
4. Suggest improvements
 
Tools used: `doc_search_unresolved`, `doc_outline`, `doc_resolve_link` (Docsbook MCP)

上面的技能示例用于说明格式，并不是目录中的条目——四个实际技能列在下方。frontmatter 字段就是架构实际定义的字段：name、description、category、mode、keywords、requires_docsbook_mcp 和 version。

frontmatter 是契约，正文是提示词。

为什么这对文档很重要#

技能解决的三个问题：

1. 能力的可发现性#

没有技能时，阅读你的文档 MCP 的 AI 代理必须猜测该做什么。有了技能后，代理会调用 find_skill("audit my docs")，并获取包含明确指令的 SKILL.md。

2. 模块化复用#

为一个项目编写的技能适用于任何项目。docs-manage 是编写页面并运行其所在网站的规则手册，适用于任何文档存储库，无论是否使用 Docsbook。

3. 组合#

技能是组合，而不是相乘。每个技能都包含一个 references/ 目录，其中存放专门的文档，仅在任务需要时加载——仅 docs-manage 就分别保存了检索、转换和写作规则的参考资料。代理先读取技能，然后读取最相关的一份参考资料，而不是加载一个目录。

docs-skills 目录#

docs-skills 目录中有什么？#

docs-skills 是一个开源目录，包含四项技能，每项技能涵盖代理使用文档完成的一类工作。它之前是一个狭长技能的长列表；之所以将其整合，是因为代理在五十个近义描述之间进行选择时往往表现不佳，而这四类工作是可以区分的。

技能 它完成的工作
docs-create 创建原本不存在的文档——来源可以是产品网站、代码仓库、你正在迁移出去的其他文档平台，或仅有一个产品名称
docs-analyze 找出已有文档的问题并修复，从搜索排名、AI 回答信号、读者行为和转化漏斗入手
docs-manage 编写页面以及运营其所在网站的规则手册——页面类型、结构、风格、受众、检索、转化
docs-automate 设置那些应该持续自动发生而无需任何人记住的事项——偏移防护、翻译触发器、版本发布公告

每项技能都是 GitHub 仓库中的独立 SKILL.md，其中包含一个代理按需读取的 references/ 目录。机器可读的索引位于同一仓库中的 index.json；上面的计数取自该索引，读取日期为 2026-09-03。

使用技能的两种方式#

本地安装#

npx docs-skills install

将目录复制到 .claude/skills/、.cursor/rules/ 或 AGENTS.md（取决于检测到的工具）。支持离线使用。使用 docs-skills update 更新。

这种模式：工具的技能位于你的代码仓库中，并由版本控制。

通过 MCP 进行运行时发现#

如果您已连接 Docsbook MCP，您的代理会调用：

find_skill({ query: "audit my docs for SEO and accessibility" })

它会返回最匹配的技能，每个 SKILL.md 对应一个 raw_url。代理会获取并遵循这些说明。

这种模式无需本地安装，始终使用最新版本，并且可跨机器运行。

AI 代理在实践中如何使用技能#

我们见过的三个实际工作流程：

工作流 1：PR 审查#

开发者打开一个涉及 docs/ 的 PR。他们的 Claude Code（或 Cursor）调用 docs-pr-check。该技能：

  1. 列出已更改的 .md 文件
  2. 对每个文件调用 doc_search_unresolved
  3. 检查 frontmatter 的完整性
  4. 将发现的问题作为 PR 评论报告

开发者会在人工审查者之前看到报告。许多文档问题甚至不会传到团队那里。

工作流 2：过时内容检测#

用户设置中的每周 cron 会调用 docs-stale-watcher。该技能：

  1. 查询 Docsbook 分析数据，找出有流量但 90 天以上未编辑的页面
  2. 与文档图谱进行交叉引用
  3. 列出待更新的候选页面

输出结果是一份待更新页面的积压列表——具有收入信号的内容缺口。

工作流 3：AI 聊天调优#

用户说：“我的 AI 聊天正在虚构有关功能 X 的内容。”代理调用 docs-tune-ai-chat。该技能：

  1. 调用 get_ai_questions 查看最近未回答的查询
  2. 调用 get_negative_feedback 查看点踩模式
  3. 识别缺失或薄弱的内容
  4. 建议创建新页面或更改系统提示词

这就是“代理改进代理”的循环。

技能 + MCP：架构#

技能告诉代理做什么。MCP 工具告诉代理如何做。

  • 技能说明“审核每个页面的无障碍性”
  • 技能正文列出诸如“调用 doc_list_pages，然后对每个调用 doc_outline”这样的步骤
  • MCP 提供技能调用的实际工具

单独来看，两者都不够。它们共同构成一个完整的循环：发现（find_skill）→ 指令（SKILL.md）→ 执行（MCP 工具）。

这对你自己的文档意味着什么#

如果你发布的是面向开发者的产品，并且希望 AI 代理能够良好地与文档交互，只需三步：

  1. 在支持 llms.txt 的平台上发布 — Docsbook 会为每个工作区自动生成一个
  2. 公开 MCP 服务器或依赖平台的 — Docsbook MCP 已包含在内
  3. 在本地安装相关的 docs-skills — npx docs-skills install

完成后，任何代理（Claude Code、Cursor、支持 HTTP MCP 的 ChatGPT）都可以自主使用你的文档。

构建你自己的技能#

如果你的文档工作流不在目录中，欢迎贡献一个。SKILL.md 格式很简单，目录是公开的，贡献内容可在数天内发布。

一个有用的技能应当具备：

  • 具体（专注于一项工作，并将其做好）
  • 可组合（调用现有的 MCP 工具）
  • 由明确的用户意图触发
  • 配有示例文档

代码仓库中有一个 SKILL.md 模板和贡献指南。

Docsbook 提供 docs-skills 支持：用于运行时发现的 find_skill MCP 工具，以及用于本地副本的 npx docs-skills install。发布工作区后，MCP 端点会随之提供——设置步骤请参见 docsbook.io/mcp。

免费开始——无需信用卡

后续步骤#

Updated

此页面对您有帮助吗？

由...提供支持 Docsbook