Implements agent-readiness on public sites and documentation by applying findings from readiness reports and fixing navigation failures.
- GitHub stars
- 194
- Files
- 7
- Last commit
- Nov 10, 2026
- License
- MIT
- Allowed tools
- —
What does the agent-ready skill do?
agent-ready implements agent-readiness on public sites and documentation by applying findings from readiness reports and fixing navigation failures.
Summary generated from the skill's SKILL.md.
About the agent-ready skill
Improving the accessibility of public websites and documentation for AI agents is what this skill does. It takes readiness reports from sources like Mintlify Agent Score, AFDocs, Is Agentic, or url-discovery-bench and translates those findings into actual code changes. It also processes server logs that show agents encountering 404 errors when attempting to navigate your documentation or API surfaces.
When an agent loads this skill, it inspects your existing codebase to map findings to real knowledge surfaces like changelogs, help centers, or status pages. It implements protocols such as adding llms.txt files, creating markdown twins for HTML pages, and configuring Link headers. The process relies on Bash, curl, Node.js, and npm to run scanners and verify that every public endpoint and machine-readable file responds correctly after the changes are applied.
This skill focuses on technical implementation and verification rather than rewriting prose or changing product features. It ensures that machine-readable routes are exempt from bot protection and that discovery mechanisms like sitemaps and robots.txt are correctly configured to guide AI users.
What an agent can do with it
- 1Fix documentation navigation failuresResolve issues where AI agents are hitting 404 errors while trying to find specific documentation paths.
- 2Improve agent readiness scoresApply specific fixes based on a provided scorecard to increase your site's compatibility with LLMs.
- 3Implement machine-readable documentation routesCreate markdown versions of HTML pages and set up llms.txt to help agents find content more efficiently.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the agent-ready skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the agent-ready skill in Claude Code
~/.claude/skills/agent-ready/SKILL.md
$ npx degit mblode/agent-skills/skills/agent-ready ~/.claude/skills/agent-readyInstall the agent-ready skill in Claude Code (project)
.claude/skills/agent-ready/SKILL.md
$ npx degit mblode/agent-skills/skills/agent-ready .claude/skills/agent-readyInstall the agent-ready skill in Codex
~/.agents/skills/agent-ready/SKILL.md
$ npx degit mblode/agent-skills/skills/agent-ready ~/.agents/skills/agent-readyInstall the agent-ready skill in Gemini CLI
~/.gemini/skills/agent-ready/SKILL.md
$ npx degit mblode/agent-skills/skills/agent-ready ~/.gemini/skills/agent-readyInstall the agent-ready skill in Claude.ai
npx degit mblode/agent-skills/skills/agent-ready agent-ready && zip -r agent-ready.zip agent-ready # claude.ai → Customize → Skills → + → Create skill → Upload a skill → agent-ready.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablemblode/agent-skills/skills/agent-ready is public and reachablegithub.com/mblode/agent-skills/tree/HEAD/skills/agent-ready ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-10github.com/mblode/agent-skills/commits ↗Pass
- No download-and-run or credential theft in scripts1 script read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/mblode/agent-skills/blob/HEAD/skills/agent-ready/ ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/mblode/agent-skills/blob/HEAD/skills/agent-ready/ ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 94 linesgithub.com/mblode/agent-skills/blob/HEAD/skills/agent-ready/ ↗Pass
SKILL.md
View on GitHubAgent Ready
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.jsllms.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.
Contents
Workflow
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:
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.
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 | Any Is Agentic report: essential checks (content without JavaScript, agent-friendly 404s), 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 |
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.txton the docs host, a link to it in the first lines of every markdown twin, andLinkheaders that advertise both. Agents request.mdandllms.txtonly 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.txtcoverage, buried directives, wrongContent-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.
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.
Gotchas
is-agentic.com/scan/<domain>shows the last stored snapshot, which can be months old. Check the snapshot date and press Rescan (or run the CLI) before treating it as the brief, and rescan again to verify.- A
.mdtwin has no navigation: the conversion stripped it with the chrome. Emit thellms.txtlink 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.txtadvertised 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.txtthat lists HTML while.mdtwins exist steers agents away from markdown and is scored worse than linking.mdfrom 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/markdownroutes) 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.
Files in this skill
7agent-ready skill questions
How do I install the agent-ready skill in Claude Code?
Run npx degit mblode/agent-skills/skills/agent-ready ~/.claude/skills/agent-ready. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the agent-ready skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What kind of reports can this skill process?
It can ingest findings from Mintlify Agent Score, AFDocs, Is Agentic, Is It Agent Ready, or url-discovery-bench reports, as well as server logs showing agent 404 errors.
Does this skill rewrite documentation prose?
No, it focuses on implementing protocols and machine-readable surfaces rather than rewriting the actual prose of the documentation.
How can I verify if the changes worked?
Verification is done by running scripts like scripts/check-surfaces.sh and using curl recipes to check public endpoints and machine-readable files.