引言
这篇文章延续此前两篇的脉络：
- 第一篇《当 84% 的开发者都在用 AI Coding，CKB 开发者体验的下一步怎么走？》系统调研了 CKB 在 AI 可消费性上的差距，给出了行动路线图；
- 第二篇《为 AI 时代的开发者重建文档：CCC 文档站的建设实录(1)》记录了 docs.ckbccc.com 从零到 35 个中英双语页面的建设过程，文末提到：面向人类开发者的文档已经就绪，下一步要围绕 AI 发现（Discoverability）与 AI 消费（Consumption）继续迭代。
本文就是这个“下一步”的实录，主要包括两件事：
- 用一个新兴的规范草案—— AFDocs（Agent-Friendly Documentation Spec）——系统性地检验并补齐 CCC 文档站的 AI 友好度；
- 将单体的
SKILL.md拆分成了 Hub + Spoke 架构，形成了一套完整的 CCC Skills。
一、意外的发现：一项面向 AI Agent 的文档规范草案
完成《建设实录（1）》里的工作后，我们的重心正式转向了 AI 发现（Discoverability）与 AI 消费（Consumption）。正当我们发愁该如何测试文档站点能否被 AI 识别和利用时，无意间看到了 Mintlify 新推出的检测工具 mintlify.com/score：
它的定位很明确：“你的文档看起来不错，但 Agent 能读到吗？”—— 这不正是我们当下最想知道的事情吗！ 它的工作原理是按照 Agent 实际读取文档的方式来打分：能不能找到页面、能不能解析内容、能不能用上读到的东西。这套打分标准的依据，就是它页面上提到的 AFDocs 标准。
顺着链接查过去，发现这是一个 2026 年 5 月 8 日才发布的规范草案，开源在 GitHub 上，由 agent-ecosystem/agent-docs-spec 维护，当前版本为 v0.5.0，仍处于 Draft 阶段，并配有一个同名 CLI 工具 afdocs。
该规范定义了 23 项检查、覆盖 7 大类目，用来衡量一个文档站对 AI Coding Agent 是否友好：
- 能否发现文档（Content Discoverability）
- 有没有可用的 Markdown 版本（Markdown Availability）
- 页面会不会因为太大被截断（Page Size and Truncation Risk）
- 内容结构是否规整（Content Structure）
- URL 是否稳定（URL Stability）
- 可观测性（Observability）
- 鉴权处理（Authentication）等等。
CCC 文档站有幸成为该规范的早期受益者之一。
规范的来源也很有意思：它源于作者的实证研究——作者花了 10 多个小时，用 Claude 实际验证了 578 个编程场景下 Agent 访问文档的表现，系统梳理了 URL 失败模式、llms.txt 的发现路径、Markdown 相比 HTML 的优势，以及页面截断这几类问题的根源。换句话说，AFDocs 不是一份“应该怎么做”的理论建议，而是一份“我们观察到 Agent 实际是怎么被卡住的”故障清单。
把 docs.ckbccc.com 输进 Mintlify 的检测框，跑出来的结果让人挺受鼓舞：AFDocs 检查的重点，和我们在建设实录（1）里做的事情——llms.txt、逐页 Markdown 等——高度重合，说明我们的大方向没偏。但报告也明确指出了几个我们此前没有覆盖到的盲点，这就是接下来要讲的具体落地工作。
二、AFDocs 落地：具体改了什么
值得一提的是，AFDocs 提供了本地检测工具，可以在开发过程中反复迭代：
npx afdocs check <http://localhost:3000> --canonical-origin <https://docs.ckbccc.com> --format scorecard
这条命令会在本地开发环境下跑一遍全部检查，输出结构化的 scorecard。我们可以针对每一项 fail/warn 反复调整，直到指标满意后再推送到正式站点，大大提升了验证效率：
就这样，对照 AFDocs check 的报告结果，我们提交了一版改造 PR：ckb-devrel/ccc#420，主要包含三类改动。
1. 核心规范合规
- 新增
/SKILL.md：作为面向 Agent 的操作指南入口（下一节详细展开）； - 增强
llms.txt：补充分区索引，改善结构，让 Agent 不用一次性拉全文就能定位目标章节； - 给
llms.txt等端点加上Cache-Control头； - 实现基于
.md后缀和内容协商的按页 Markdown 输出； - 在 layout 层嵌入一段面向爬虫/Agent 可发现的指令性元信息；
- 更新文档页面结构，使其更符合 Agent 友好的组织方式。
2. 示例代码的可发现性
此前 Code Examples 页面里的示例代码，source 字段用的是仓库内的相对路径。这类路径只有在 Agent 已经拿到完整仓库上下文时才有意义——但很多时候 Agent 只是访问了文档页面，并没有整个仓库的上下文。我们把中英文两个版本的 code-examples.mdx 里的 source 字段，全部换成了 raw.githubusercontent.com 的绝对 URL。同时，我们在文档中增加了对 AI Agent 的引导说明：
这样 Agent 就可以直接抓取到示例源码，不再依赖仓库上下文。
3. Markdown 响应的元信息头
给每个页面的 Markdown 响应加上了标题、URL、GitHub 源文件链接，并把页面描述作为 blockquote 放在开头。这样 Agent 在拿到一段 Markdown 内容时，能立刻知道“这是哪个页面、从哪来、原始文件在哪”，而不是一段脱离上下文的纯文本。
这几类改动看起来琐碎，但正好对应 AFDocs 报告里反复强调的一件事：Agent 不会读你的导航结构，很多时候它拿到的就是一段孤立的文本，你得在这段文本本身里把上下文信息补全。
三、Skills：从一份单体文件，到 Hub + Spoke
1. 为什么要拆
第一个版本的 CCC Skill，是放在文档站 public 目录下的一份单体 SKILL.md。但完成后我们发现，这样一份全量的 SKILL 文件天然存在一个问题：CCC 覆盖的场景很多（钱包连接、交易组装、UDT、Spore……），内容会持续增长和迭代，单个文件一旦变得很长，就有被部分 AI 工具截断上下文的风险——truncation 恰好也是 AFDocs 报告里点名的一类问题。
拆分本身有几种可选方案，我们最终选择了目前比较主流的做法：把 Skill 文件迁到 ckb-devrel/ccc 主仓库，同时把文档站根目录的 skill.md 改造成一份索引文件，指向各个具体的 Skill。
这样设计的好处是可以覆盖到多种场景的开发者：装了本地 Skill 的开发者可以直接在编程工具里加载对应的 spoke；而在网页版、没有安装任何本地 skill 的场景下，skill.md 依然可以作为唯一入口被访问到（这一点会在下一节详细展开）。
现在 CCC 的 Skills 是一个 Hub + Spoke 结构，Hub 是 ckb-ccc-fundamentals（讲清 Cell 模型、包选择、交易处理、地址处理这些基础概念），围绕它的 6 个 spoke 分别是：
| Skill | 覆盖领域 |
|---|---|
ckb-ccc-fundamentals（Hub） |
CKB/CCC 基础概念、包选择、DeepWiki/Context7 查询方式 |
ckb-ccc-signer-setup |
钱包连接（前端 Provider/Hooks）、后端私钥 Signer |
ckb-ccc-transactions |
交易组装、补齐输入与手续费、cell dep、链上查询 |
ckb-ccc-udt |
UDT/xUDT 代币的发行、转账 |
ckb-ccc-spore |
Spore 协议 NFT/DOB 的铸造、转让、销毁 |
ckb-ccc-playground |
CCC Playground 在线调试工具的使用 |
ckb-ccc-examples-finder |
帮助定位/复用现成的 CCC 示例代码 |
安装方式仍然是一行命令：npx skills add ckb-devrel/ccc --all。
2. 重点展开：playground 与 examples-finder
这两个是后加的 spoke，也是我个人认为比较能体现“skill 不只是 API 说明书”的两个例子。
ckb-ccc-playground：live.ckbccc.com 是一个零配置的浏览器内 CCC 运行环境。我自己写脚本验证某个特定功能时，经常直接在 Playground 里跑，而不是本地搭一个完整项目。这种用法对开发者非常高效，但如果不特意说明，很少有人会想到用它。所以我们专门做了一个 Skill，让 AI 在合适的场景下（比如用户只是想验证一个想法、调试一段代码）主动把 Playground 推荐给开发者，而不是默认让开发者去搭完整的本地工程。
ckb-ccc-examples-finder：解决的是另一个常见痛点——开发者不知道去哪找示例、找 Demo。很多时候他们直接去问 AI，而 AI 手头并没有“CCC 有哪些现成示例、分别在哪”这类结构化信息。这个 Skill 就是要让 AI 能够：要么直接引导开发者去正确的位置查找；要么自己去把示例找到、直接呈现给开发者；甚至可以进一步分析拿到的示例，重新组装出更贴合开发者具体需求的脚本。
下图是在 Devin 里的实测效果：
四、Prompt 模板：让不同起点的开发者都能用上 Skill
CKB 生态目前的开发者体量还很小，我们需要的不仅仅是服务好已经在用 Cursor / Claude Code 的老手，更重要的是把更多新开发者引导进来。这批新开发者中有相当一部分人，第一次接触 CKB 开发可能是通过某个 AI 驱动的网页应用构建器（纯聊天交互，构建网站/网页应用/移动应用），先直接把 MVP 聊出来，验证完想法之后，才会把代码下载到本地、换成正式的编程工具继续迭代。
这意味着 skill 的使用场景天然分成两类：
- 纯网页对话场景：没有安装任何本地 Skill，此时唯一的入口就是那份
skill.md索引文件（https://docs.ckbccc.com/skill.md），需要开发者（或者产品自身）显式把这个链接贴进对话里； - 已装 Skill 的 AI 编程工具场景：Cursor / Devin / Claude Code 等工具会根据 Skill 的
description字段和任务的自然语言描述自动路由到对应 spoke，开发者不需要、也不应该被要求记住具体的 Skill 名字。
我们希望这两类开发者都能顺利用上 CCC 的知识库，网页对话构建 MVP 之后，本地继续迭代时 Skill 原生环境也能无缝接上。因此，我们在 CCC 的文档站点里对这两种使用场景均做了相应的指引。
五、效果：从检测分数到真实案例
1. AFDocs 检测分数
改造之前，docs.ckbccc.com 在 Mintlify Agent Score 上的得分是 92 分；PR #420 合并之后，分数提升到了 100/100（A+），在 30 项检查中通过了 24 项。
Mintlify 这个检测工具在 AFDocs 核心 23 项检查的基础上，又额外加了几类检查项，比如 Agent Skills、MCP Server。目前我们仍有 2 项 fail、1 项 warning。
其中 MCP Server 这一项 CCC 没有实施，是出于这样的考量：CCC 的代码和文档已经同步更新到 DeepWiki、Context7 等主流 AI 友好平台，这些平台均提供了各自的 MCP Server，AI 编程工具可以方便地配置使用。我们在测试中也验证过，当工具中配置了 DeepWiki 或 Context7 的 MCP Server 后，询问 CCC 相关问题能够正确调用并返回高准确率的回复。因此，我们决定不额外增加一个需要开发者单独配置的 MCP Server，而是充分利用已有的生态基础设施。
下图是我在 Devin 里问 AI：“给我解释一下 ccc 里的 tx.completeFeeBy 方法”之后 AI 的回复。可以清楚地看到它的搜索路径：由于我的 Devin 里配置了 DeepWiki 和 Context7 的 MCP，它先调用了 DeepWiki 的 MCP，请求失败（可能网络原因）后，又继续调用 Context7 的 MCP 服务来获取相关信息。
2. Skills 的早期数据
Skills 目前刚发布不久，我们还没有对外公开推广，skills.sh 上的安装数据也还很早期：
这部分数据现阶段更多是一个起点记录，而不是拿来证明什么，后续会持续跟踪。
3. 真实案例：AI 工具用上 Skill 前后
比起分数，更想拿出来分享的是几个实测案例，看看 AI 加上 Skill 前后的对比效果到底如何。
3.1 没有使用 Skill 时
首先，我们来看看没有使用 Skill 的情况下，AI 开发 Demo 的表现：
帮我写一个 React 网页应用，实现： 连接钱包后，可以发行一个 CKB 链上的 xUDT 代币，同时支持对该代币发起转账交易。
查看 AI 的执行过程：
结果：
- 几乎全靠搜索、猜，东拼西凑
- 运行时会报错
- xUDT 发了之后无法识别，功能几乎不可用，相应的交易链接：https://testnet.explorer.nervos.org/transaction/0x10fbf3c969e73d32a81fb7b16a37bf6876b8154782b0d8aa0313e63fb290a4a2
3.2 用上 Skill 后
接下来，我们来看看当 AI 使用上 Skill 后，开发的 Demo 如何。
我们还是在 bolt.new 上做——使用相同的平台，前后对比的结果更有参考意义。与此前无 Skill 测试的提示词几乎一样，只是我们加了一句“请先访问 https://docs.ckbccc.com/skill.md”。
案例 1：xUDT 代币的发行与转账应用
请先访问 https://docs.ckbccc.com/skill.md ，然后帮我写一个应用，该应用的核心功能是发行xUDT代币，并支持转账xUDT。
这个提示词里，我刻意去掉了CKB、CCC等关键字，因为只要 AI 去加载我们的 Skill 索引文件，必然可以知道这些信息。
查看 AI 的执行过程：
可以看到，AI 正在按照我们设定的规则执行：
- 首先去加载了
https://docs.ckbccc.com/skill.md这个文件； - 读取内容后，它发现还需要加载 fundamentals、signer setup、transactions 以及 udt 这几个 Skill 才能完成需求；
- 获取到相应的 Skill 文件后，它将这些内容放进自己的缓存中以便随时读取；
- 根据 Skill 规范开始编写代码。
结果令人惊叹！主体功能一次通过，大家可以在这里体验：xudt-token-issuance-kynx.bolt.host （testnet，仅用于演示）
加上了 Skill 之后，上面的应用生成得很成功，是巧合还是必然？为了进一步验证 AI 工具是否真的在使用我们的 Skill，我们又额外增加了一个案例 Demo 的测试。
案例 2：链上留言墙
请先访问 <https://docs.ckbccc.com/skill.md，然后用> CCC SDK 做一个 React 网页应用：
连接钱包后可以发一条短留言，留言内容写入一笔 CKB 交易的 cell data 里，永久上链；
首页按时间倒序展示所有留言和发送者地址。
同样，我们使用上面的提示词在 bolt.new 里执行，观察 AI 的执行流程是否符合预期，并验证最终应用是否可用。
AI 完全按照我们预想的方式在处理，而且它还做了一些额外的、我们的提示词里没有提到的工作来完善 Demo 的体验。看到效果的那一刻，我不禁感叹：装上了 Skill 的 AI 真的太强了。
这里预览：ckb-chain-message-wa-66g4.bolt.host
以上两个案例除了涉及钱包连接、交易组装这类在第一篇调研报告中被反复强调“AI 容易出错”的环节（capacity 计算、cell 占用逻辑等）之外，还涵盖了 UDT 的三步发行与转账，以及留言板里如何汇总查询链上记录等复杂场景。接入 Skill 之后，这些流程均一次跑通。这可能不算一个非常严谨、全面的测试，但作为方向性的验证，给了我们非常大的信心。
上述预览链接仅用于演示 skill 的效果，请勿用于其他用途。
除了 bolt.new 以外，我们还在 Lovable、BASE44等平台上测试了使用 Skill 之后的效果。
也想借这个机会邀请社区一起来测试：如果你在用 Cursor / Claude Code / 网页版 AI 工具开发 CKB 应用，欢迎试试安装或引用 CCC 的 Skill，把你遇到的效果、踩到的坑反馈给我们。
六、方法论
下面是我们将 CCC 文档建站这两篇实录（建设文档站 + 补齐 AI 友好度）中的经验，提炼成的一份可复用的 checklist，供你参考：
- 先把文档做实，再谈 AI 友好：AI 可消费性建立在人类可读的高质量文档之上，顺序不能反。
- 借助行业规范或检测工具自查：用 AFDocs 或 Mintlify Agent Score 这类工具跑一遍现状，能发现很多凭经验想不到的盲点。
- 本地反复迭代，再部署上线：
npx afdocs check <本地地址> --canonical-origin <线上域名>可以快速验证，避免每次改动都依赖线上环境。 - 让 Markdown 响应自带上下文：Agent 拿到的往往是脱离页面结构的一段文本，务必在响应中显式带标题、来源 URL、GitHub 源文件链接等元信息。
- 示例代码使用绝对 URL，不要依赖 Agent 已经拿到仓库上下文这一假设。
- 提前规划 Skill 的演进结构：内容会持续增长，采用 Hub + Spoke 或类似拆分方式，避免单体文件被截断。
- 兼顾两种用户场景：既照顾已安装本地 Skill 的开发者，也为纯网页对话用户（尤其是新上手用户）提供便捷的入口。
- 用真实案例验证效果：选择几个典型场景实测 AI 生成代码的成功率，比单纯看检测分数更有说服力。
后记
至此，CCC 文档站在“AI 发现”和“AI 消费”这两个方向上都完成了一轮系统性建设：AFDocs 规范草案把此前偏经验性的 AI 友好度工作，变成了一套可检测、可量化、可持续迭代的标准；Skills 生态则让这些沉淀下来的最佳实践，能够以 Agent 原生的方式被直接调用，而不只是“文档写得好、AI 自己去悟”。
不过这还不是终点。我们将持续改善文档与 Skill，补充更多可供参考的示例代码，以便更好地服务AI 时代的开发者。
同时，如果你正在用 AI 工具开发 CKB / CCC 应用，欢迎试试 CCC 的 Skill，把你的体验和建议留在评论区。
参考链接
- 建设实录系列前两篇：
- CCC 文档站：docs.ckbccc.com
- CCC skill 索引入口：
https://docs.ckbccc.com/skill.md - Agent-Friendly Documentation Spec 官网：agentdocsspec.com
- AFDocs 规范仓库：github.com/agent-ecosystem/agent-docs-spec
- AFDocs 改造 PR：ckb-devrel/ccc#420
- Mintlify Agent Score 检测工具：mintlify.com/score
- CCC 文档站的 Agent Score 报告：mintlify.com/score/ckbccc
- CCC Skills 列表（skills.sh）：skills.sh/ckb-devrel/ccc
- CCC Playground：live.ckbccc.com
- bolt.new：bolt.new
- 案例一预览 - xUDT 发行/转账应用：xudt-token-issuance-kynx.bolt.host
- 案例二预览 - 链上留言墙：ckb-chain-message-wa-66g4.bolt.host
