agent-ready

Agent Ready

将公开的 Agent 就绪度评分，或记录 Agent 导航失败情况的日志，转化为已发布且经过验证的 HTTP 和文档更改。

• 包含： 收集 Mintlify Agent Score / AFDocs、Is Agentic、Is It Agent Ready 或 url-discovery-bench 的结果，以及服务端 Agent 404 证据；检查代码库、实现相应协议、添加测试，并验证线上响应。
• 不包含： 重写文档文案（ghostwriter）、改善软件包/CLI/SDK 的易用性（dx-audit）、判断产品内 Agent 是否可信（ax-audit）、搜索排名、爬虫策略，以及 Next.js llms.txt/Markdown 路由（seo；本技能负责这些路由必须满足的 AFDocs 和 Is Agentic 契约），或代码库指令文件（agents-md）。不要引入 vercel-labs/is-agentic；该技能负责获取报告。本技能负责实现产品。

目录

• 工作流
• 参考文件
• 优先级
• 输出
• 注意事项

工作流

Agent-ready progress:
- [ ] Step 1: Ingest the report, the agent 404 log, or run scanners against the public URL
- [ ] Step 2: Inspect the existing codebase before any edit
- [ ] Step 3: Inventory every knowledge surface the origin serves and map each finding to a real one; skip surfaces the product does not offer
- [ ] Step 4: Load the matching reference and implement the map first, then failures, then warnings. For Next.js App Router `llms.txt` and markdown routes, load `seo` (that skill's `nextjs-implementation.md` and `answer-engines.md`) instead of a second recipe.
- [ ] Step 5: Add or update tests for every behavior you change
- [ ] Step 6: Verify every public endpoint and machine-readable file you touched (`scripts/check-surfaces.sh`, then the curl recipes for anything it does not cover)
- [ ] Step 7: Report changes, quoted verification, and remaining product decisions

粘贴的评分卡就是规范。如果没有评分卡，且用户提供了公开 URL，则获取一份：

pnpm dlx afdocs check <docs-url> --format scorecard --sampling deterministic
pnpm dlx is-agentic <domain> --json

Is It Agent Ready：向 https://isitagentready.com/api/scan 发送 POST 请求，附带 {"url":"<origin>","format":"agent"}。如果用户粘贴了报告，且已有报告，则优先使用用户提供的报告，而不是重新扫描。

服务器日志也可以作为任务说明。Agent 在服务端发起请求，不运行 JavaScript，因此不会出现在客户端分析数据中；统计 .md URL、llms.txt 和已识别 AI 用户代理的请求，并将这些 Agent 连续出现 404（获取、404、猜测相邻路径、重试）的情况视为未通过的检查。references/verification.md 包含日志查询和导航基准测试。

第 3 步涵盖整个源站，而不只是 /docs：变更日志、发行说明、帮助中心、社区和状态页都是知识 Agent 会用来回答问题的内容，但它们通常只有 HTML，而文档已准备就绪。针对每个内容区域，判断是否需要添加 Markdown 版本和索引条目；营销页面不需要。

保留视觉设计和现有产品行为。更改发现方式、内容表示、标头和文档化契约，不要更改功能集。

无法访问生产环境的本地测试套件可以安全运行、修复并重新运行。未经授权，不要部署、更改 DNS、购买注册名称，或在工作树之外写入文件。

完成标准：每项范围内未通过的检查都已通过代码或内容更改解决（或明确说明跳过及原因）；测试覆盖了新增行为；第 6 步引用了实际访问环境返回的状态码、Content-Type 和相关标头或正文。

参考文件

文件	何时阅读
references/docs-afdocs.md	Mintlify Agent Score、AFDocs、llms.txt、.md URL、Markdown 版本中的索引链接、Accept 协商、页面大小、身份验证门槛、非文档知识内容区域
references/api-surfaces.md	任何 Is Agentic 报告：基本检查（无需 JavaScript 即可获取内容、对 Agent 友好的 404）、JSON 错误、OpenAPI、版本控制、速率限制、函数调用、CLI、MCP
references/site-discovery.md	Is It Agent Ready：robots、sitemap、Link 标头、DNS-AID、well-known 目录、机器人规则
references/verification.md	第 6 步：check-surfaces.sh、curl 示例、服务器日志测量、url-discovery-bench，以及证据的判定标准

优先级

Agent 能很好地读取 Markdown，但在导航方面容易失败。Mintlify 的 2026 年基准测试（2,400 项任务、20 个文档站点、Claude 和 Codex）显示，无论格式如何，准确率都保持在 94% 到 99%；但每项任务的失败请求数从 HTML 的 2.23 次降至纯 Markdown 的 1.42 次，并在每个 Markdown 页面都链接 llms.txt 后降至 0.11 次。按以下顺序开展工作：

1. 地图：在文档主机上提供 llms.txt，在每个 Markdown 对应页面的首行中添加其链接，并添加同时声明两者的 Link 标头。只有知道 .md 和 llms.txt 存在时，Agent 才会请求它们。
2. 产品实际存在的问题（Agent 无法读取的文档 HTML、真实 API 返回的 HTML 错误页面、没有备用路径的受限公开文档）。
3. 同一表面上的警告（llms.txt 覆盖范围、埋得太深的指令、错误的 Content-Type）。
4. 与仓库中已有表面相符的建议检查（OpenAPI、MCP、OAuth）。
5. 新兴扩展（电商协议、A2A、DNS-AID），仅在产品已支持这些内容或用户要求添加时处理。

如果站点没有 MCP 服务，那么缺少 MCP 卡片就不算问题。不要为了追求分数而臆造 API、CLI 或支付协议。

输出

按检查项分组。每项包括：报告中的证据、修改的文件、添加的确切标记或架构、验证引文，以及不适用时的跳过原因。如果任务简报是 404 日志或基准测试，请引用修改前后的每项任务失败请求数。

最后列出仍需产品决策、DNS 访问权限或凭据的事项。

易错点

• is-agentic.com/scan/<domain> 显示的是上次存储的快照，可能已经过时数月。将其视为任务简报前，请检查快照日期并按 Rescan（或运行 CLI）重新扫描；验证时也要再次扫描。
• .md 对应页面没有导航：转换时，导航随页面框架一起被剥离。应从对应页面路由输出 llms.txt 链接，确保不会漏掉任何页面；逐页修改会产生偏差。
• Markdown 对应页面属于一个应用中的路由。如果变更日志或博客位于同一源站的独立营销应用中，那么在无人决策的情况下，它们仍然只有 HTML。请检查每个应用，而不只是包含对应页面路由的应用。
• 通过三种方式声明同一个 llms.txt（代理中的 rel="llms-txt"、框架标头中的 rel="https://llmstxt.org/rel/llms-txt"、布局 <link> 中的 rel="describedby"），会导致扫描器读取该响应中最终生效的那一层。选择扫描器会探测的 rel 集合，并从一个位置输出。
• 如果 llms.txt 列出 HTML，而 .md 对应页面已经存在，就会引导 Agent 远离 Markdown，评分也会低于一开始就链接 .md 的做法。
• <head>、导航中或 HTML 正文过半之后的指令都不计入。请将指令放在文档正文靠前的位置，并由服务器渲染。
• 没有 Agent 流量的仪表板无法证明任何问题：Agent 不会运行 JavaScript；Search Console 和 SERP 工具统计的是搜索者，而非 Agent。服务器日志中 .md、llms.txt 和 AI 用户代理的请求才是唯一的阅读量指标；如果没有日志导出，诚实的数字应是 No data，而非客户端代理数据。
• 针对爬虫调整的机器人防护（质询页面、WAF 机器人规则、对 text/markdown 路由设置严格的速率限制）会阻止你要优化的 Agent，而它们无法通过质询。请将机器可读路由排除在这些规则之外，或从规则不覆盖的路径提供这些内容。
• 覆盖范围失败与精选索引：如果站点需要保持内容一致，请根据站点地图重新生成；如果索引是有意精选的，请明确说明，不要用营销 URL 凑数。

仅用于维护：evals/evals.json 用于修改此技能，而非处理用户任务。