agent-ready

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Ready

Agent 就绪

Turn a public agent-readiness score, or a log of agents failing to navigate, into shipped, verified HTTP and docs changes.

IS: ingesting Mintlify Agent Score / AFDocs, Is Agentic, Is It Agent Ready, or url-discovery-bench findings, plus server-side evidence of agent 404s, inspecting the repo, implementing the matching protocols, adding tests, and verifying live responses.
IS NOT: rewriting docs prose (
```
ghostwriter
```
), package/CLI/SDK ergonomics (
```
dx-audit
```
), whether an in-product agent can be trusted (
```
ax-audit
```
), search ranking, crawler policy, and Next.js
```
llms.txt
```
/markdown routes (
```
seo
```
; this skill owns the AFDocs and Is Agentic contract those routes must satisfy), or repo instruction files (
```
agents-md
```
). Do not vendor vercel-labs/is-agentic; that skill retrieves reports. This one implements the product.

将公开的 Agent 就绪度评分，或 Agent 无法导航的日志，转化为已交付且经过验证的 HTTP 和文档改动。

是：接收并分析 Mintlify Agent Score / AFDocs、Is Agentic、Is It Agent Ready 或 url-discovery-bench 的发现结果，以及来自服务端证据的 Agent 404；检查代码仓库，实现相应协议，添加测试并验证线上响应。
不是： 重写文档文案（
```
ghostwriter
```
）、优化 package/CLI/SDK 易用性（
```
dx-audit
```
）、评估产品内 Agent 是否可信（
```
ax-audit
```
）、处理搜索排名、爬虫策略，以及 Next.js
```
llms.txt
```
/Markdown 路由（
```
seo
```
；本 Skill 负责这些路由必须满足的 AFDocs 和 Is Agentic 契约），也不处理仓库指令文件（
```
agents-md
```
）。不要 vendor vercel-labs/is-agentic；对应 Skill 负责检索报告，本 Skill 负责实现产品。

Workflow

工作流程

text

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

A pasted scorecard is the spec. If none is present and the user named a public URL, gather one:

bash

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

Is It Agent Ready:

POST https://isitagentready.com/api/scan

with

{"url":"<origin>","format":"agent"}

. Prefer the user's pasted report over a new scan when both exist.

Server logs are a brief too. Agents fetch server-side and run no JavaScript, so they never appear in client-side analytics; count requests for

.md

URLs,

llms.txt

, and recognized AI user agents, and treat a stream of 404s from those agents (fetch, 404, guess a sibling path, retry) as the failing check.

references/verification.md

has the log queries and the navigation benchmark.

Step 3 covers the whole origin, not only

/docs

: changelog, release notes, help center, community, and status pages are knowledge agents answer from, and they are usually HTML-only while the docs are ready. Decide per surface whether it gets markdown twins and an index entry; marketing pages do not.

Preserve visual design and existing product behavior. Change discovery, representations, headers, and documented contracts, not the feature set.

Local test suites that cannot reach production are safe to run, fix, and rerun. Do not deploy, change DNS, buy a registry name, or write outside the working tree without authorization.

Done when every in-scope failing check has a code or content change (or an explicit skip with reason), tests cover the new behavior, and Step 6 quotes status,

Content-Type

, and the relevant headers or body from the environment you actually hit.

text

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，则获取一份：

bash

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

Is It Agent Ready：

POST https://isitagentready.com/api/scan

，请求体为

{"url":"<origin>","format":"agent"}

。如果用户粘贴的报告和新扫描结果同时存在，优先使用用户粘贴的报告。

服务器日志同样是需求简报。Agent 在服务端发起请求且不运行 JavaScript，因此它们永远不会出现在客户端分析中；应统计针对

.md

URL、

llms.txt

和已识别 AI user agent 的请求，并将这些 Agent 连续出现的 404（请求、404、猜测同级路径、重试）视为失败检查。

references/verification.md

中提供了日志查询和导航基准测试。

第 3 步覆盖整个 origin，而不只是

/docs

：changelog、release notes、help center、community 和 status page 都是 Agent 回答问题时依据的知识面，而且它们通常只有 HTML，而文档已经就绪。逐个判断这些知识面是否需要 Markdown twin 和索引条目；营销页面不需要。

保留视觉设计和现有产品行为。改动发现机制、内容表示、请求头和已声明的契约，而不是功能集。

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

完成的标志是：范围内每个失败检查都已有代码或内容改动（或明确说明跳过原因），测试覆盖新行为，且第 6 步引用实际命中环境中的状态码、

Content-Type

以及相关响应头或响应体。

Reference files

参考文件

File	Read when
references/docs-afdocs.md	Mintlify Agent Score, AFDocs, `llms.txt` , `.md` URLs, the index link in markdown twins, Accept negotiation, page size, auth gates, non-docs knowledge surfaces
references/api-surfaces.md	Is Agentic API findings: JSON errors, OpenAPI, versioning, rate limits, function calling, CLI, MCP
references/site-discovery.md	Is It Agent Ready: robots, sitemap, Link headers, DNS-AID, well-known catalogs, bot rules
references/verification.md	Step 6: `check-surfaces.sh` , curl recipes, server-log measurement, url-discovery-bench, and what counts as evidence

文件	何时阅读
references/docs-afdocs.md	Mintlify Agent Score、AFDocs、 `llms.txt` 、 `.md` URL、Markdown twin 中的索引链接、Accept 协商、页面大小、鉴权门禁、非文档知识面
references/api-surfaces.md	Is Agentic API 发现结果：JSON 错误、OpenAPI、版本管理、速率限制、函数调用、CLI、MCP
references/site-discovery.md	Is It Agent Ready：robots、sitemap、Link 响应头、DNS-AID、well-known 目录、bot 规则
references/verification.md	第 6 步： `check-surfaces.sh` 、curl 操作示例、服务器日志测量、url-discovery-bench，以及有效证据的判定标准

Priority

优先级

Agents read markdown fine and fail at navigation. In Mintlify's 2026 benchmark (2,400 tasks, 20 docs sites, Claude and Codex) accuracy held at 94 to 99% in every format while failed requests per task went 2.23 on HTML, 1.42 on plain markdown, 0.11 once each markdown page linked

llms.txt

. Order work accordingly:

The map:
```
llms.txt
```
on the docs host, a link to it in the first lines of every markdown twin, and
```
Link
```
headers that advertise both. Agents request
```
.md
```
and
```
llms.txt
```
only when they know they exist.
Failures the product actually has (docs HTML that agents cannot read, HTML error pages on a real API, gated public docs with no alternate path).
Warnings on those same surfaces (
```
llms.txt
```
coverage, buried directives, wrong
```
Content-Type
```
).
Recommended checks that match a surface already in the repo (OpenAPI, MCP, OAuth).
Emerging extras (commerce protocols, A2A, DNS-AID) only when the product already offers them or the user asked to add them.

A missing MCP card is not a failure on a site that has no MCP server. Do not invent an API, CLI, or payment protocol to chase points.

Agent 能很好地读取 Markdown，却会在导航上失败。根据 Mintlify 的 2026 年基准测试（2,400 个任务、20 个文档站点、Claude 和 Codex），各种格式下的准确率都保持在 94% 至 99%；与此同时，每项任务的失败请求数在 HTML 下为 2.23，在纯 Markdown 下为 1.42，而在每个 Markdown 页面都链接

llms.txt

后降至 0.11。请据此安排工作顺序：

映射：在文档主机上提供
```
llms.txt
```
，在每个 Markdown twin 的前几行加入其链接，并使用
```
Link
```
响应头同时宣传两者。Agent 只有在知道这些资源存在时，才会请求
```
.md
```
和
```
llms.txt
```
。
产品实际存在的失败项（Agent 无法读取的文档 HTML、真实 API 返回的 HTML 错误页、被鉴权拦截且没有替代路径的公开文档）。
同一批知识面上的警告项（
```
llms.txt
```
覆盖率、位置过深的指令、错误的
```
Content-Type
```
）。
与仓库中已有知识面匹配的建议检查（OpenAPI、MCP、OAuth）。
新兴扩展项（commerce 协议、A2A、DNS-AID），仅在产品已经提供相应能力或用户明确要求添加时处理。

对于没有 MCP server 的站点，缺少 MCP card 并不构成失败。不要为了刷分而虚构 API、CLI 或支付协议。

Output

输出

Group work by check. For each: evidence from the report, files changed, exact markup or schema added, verification quote, skip reason if N/A. When the brief was a 404 log or benchmark, quote failed requests per task before and after.

Finish with remaining items that need a product decision, DNS access, or credentials.

按检查项对工作进行分组。对于每一项，列出：报告中的证据、更改的文件、添加的确切 markup 或 schema、验证结果引用，以及不适用时的跳过原因。当需求来自 404 日志或基准测试时，引用每项任务在改动前后的失败请求数。

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

Gotchas

注意事项

A
```
.md
```
twin has no navigation: the conversion stripped it with the chrome. Emit the
```
llms.txt
```
link from the twin route so no page can miss it; a per-page edit drifts.
Markdown twins are a route in one app. When the changelog or blog lives in a separate marketing app on the same origin, it stays HTML-only without anyone deciding that; walk every app, not only the one with the twin route.
One
```
llms.txt
```
advertised three ways (
```
rel="llms-txt"
```
from a proxy,
```
rel="https://llmstxt.org/rel/llms-txt"
```
from framework headers,
```
rel="describedby"
```
from a layout
```
<link>
```
) leaves the scanner reading whichever layer wins on that response. Pick the rel set the scanners probe and emit it from one place.
```
llms.txt
```
that lists HTML while
```
.md
```
twins exist steers agents away from markdown and is scored worse than linking
```
.md
```
from the start.
A directive in
```
<head>
```
, nav, or past 50% of the HTML body does not count. Put it in the document body, near the top, server-rendered.
A dashboard with no agent traffic proves nothing: agents run no JavaScript, and Search Console and SERP tools count searchers, not agents. Server logs of
```
.md
```
,
```
llms.txt
```
, and AI user agent requests are the only readership measure; without a log drain the honest number is No data, not a client-side proxy.
Bot protection tuned for crawlers (challenge pages, WAF bot rules, tight rate limits on
```
text/markdown
```
routes) blocks the agents you are optimizing for, and they cannot pass a challenge. Exempt the machine-readable routes or serve them from paths the rules do not cover.
Coverage fail vs curated index: regenerate from the sitemap when the site intends parity; if the index is intentional, say so and do not pad it with marketing URLs.

Maintenance only:

evals/evals.json

is for changing this skill, not for a user task.

一个
```
.md
```
twin 没有导航：转换时将其连同 chrome 一并剥离了。应从 twin 路由发出
```
llms.txt
```
链接，确保任何页面都不会遗漏；逐页编辑会产生漂移。
Markdown twins 是某个 app 中的一组路由。当 changelog 或 blog 位于同一 origin 上另一个独立营销 app 中时，它会在无人决策的情况下继续保持仅 HTML。必须遍历每个 app，而不只是包含 twin 路由的那个 app。
同一个
```
llms.txt
```
通过三种方式宣传（代理发出的
```
rel="llms-txt"
```
、框架响应头发出的
```
rel="https://llmstxt.org/rel/llms-txt"
```
、布局
```
<link>
```
发出的
```
rel="describedby"
```
），会让扫描器只读取响应中最终生效的那一层。选择扫描器会探测的 rel 集合，并从单一位置统一输出。
当
```
.md
```
twins 存在时，
```
llms.txt
```
却列出 HTML，会把 Agent 引导远离 Markdown，其得分低于从一开始就链接
```
.md
```
。
位于
```
<head>
```
、nav 中，或处于 HTML body 50% 之后位置的指令不算数。将其放在文档正文靠前的位置，并进行服务端渲染。
没有 Agent 流量的 dashboard 什么都证明不了：Agent 不运行 JavaScript，而 Search Console 和 SERP 工具统计的是搜索用户，不是 Agent。
```
.md
```
、
```
llms.txt
```
和 AI user agent 请求的服务器日志是唯一的阅读量度量；没有日志收集管道时，诚实的数字是
```
No data
```
，而不是客户端代理数据。
为爬虫调优的 Bot 防护（challenge 页面、WAF bot 规则、对
```
text/markdown
```
路由设置过紧的速率限制）会阻挡你正在优化的 Agent，而它们无法通过 challenge。为机器可读路由设置豁免，或从规则未覆盖的路径提供这些路由。
coverage 失败与精选索引：如果站点希望两者保持一致，应基于 sitemap 重新生成；如果索引是刻意设计的，则明确说明，不要用营销 URL 填充。

仅用于维护：

evals/evals.json

用于修改本 Skill，而不是用户任务。