⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

agent-ready

mblode@mblode⭐ 198 stars· last commit 4d ago· 0 open issues

Implements agent-readiness on public sites and docs from Mintlify Agent Score, AFDocs, Is Agentic, Is It Agent Ready, or url-discovery-bench reports, or from server logs of agents 404ing on guessed URLs. Use when asked to "make our site agent-ready", "improve Agent Score", "fix llms.txt coverage", "agents keep 404ing on our docs", or when a pasted scorecard is the brief.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 198 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Agent Skills

Nobody ships AI slop on purpose. These skills make sure you don’t.

UI audits, typography, docs, PR review, and releases. On-demand skills for coding agents.

Install

npx skills add mblode/agent-skills -g --agent codex claude-code -y

If these help, star the repo so others find them.

Agents: these skills. Humans: Taste Training, a course on spotting and fixing AI slop. First unit free.

Skills

Architecture

  • codebase-architecture: Design a structure, deepen an existing one, or harden it with guardrails.
  • scaffold-nextjs: Next.js turborepo with Blode UI, Ultracite (oxlint/shadcn), GitHub, and Vercel.
  • scaffold-cli: TypeScript CLI package: ESM, tsdown, vitest, changesets, CI.
  • multi-tenant-architecture: Tenant isolation, routing, and custom domains on Cloudflare or Vercel.

Design

  • product-design: What the interface should do, before anyone builds it.
  • ui-design: Visual direction, design-system extraction, Tailwind builds, screenshot to markup, dark mode, responsive, and a React and Next.js UX audit with a ship verdict.
  • ui-verification: Runs nine browser probes, reviews before/after captures and suspicious duplicate states, proves the fix cleared, and runs an exploratory pass that tries a finished feature like a real user.
  • app-verification: Builds and maintains a product's own verify CLI, doctor command, feature map, and worktree isolation, with reusable API checks, checked flow cleanup, and a reproduce-first bug handoff. Call by name.
  • ui-animation: Springs, gestures, easing, and curves pulled from a screen recording.
  • presentation-creator: Decks with a story spine, speaker notes, and a contrast-checked QA pass, as Marp markdown, a web app, or a handoff to pptx.

Writing

  • eli5: Explains in the form that fits: plain prose, controlled English modelled on ASD-STE100, diagrams, interactive HTML pages, or narrated explainer videos, with exact technical terms and house vocabulary.
  • ghostwriter: Writes anything as you or as your company: messages, posts, review comments, tickets, PRDs, design docs, talk scripts, copy, docs, READMEs, with the AI tells stripped. Works with no profile, writes one from pasted samples, and learns from your edits.

Quality

  • ax-audit: Agentic experience audit: 24 rules for tool parity, approval gates, and escape hatches, ship verdict.
  • dx-audit: Libraries, CLIs, SDKs, npm packages: 38 rules, agent-friendly checks, root-cause findings.
  • agent-ready: Implements AFDocs, Is Agentic, Is It Agent Ready, and agent 404 findings: llms.txt maps, markdown twins, API errors.
  • typography-audit: 78 rules: punctuation, fonts, sizing, spacing, hierarchy, pairing.
  • seo: SEO, AEO and GEO audits and fixes, search-demand research, writer briefs, and search, AI visibility, and conversion measurement.
  • test-audit: Prunes low-value tests across a whole suite to a measured target with coverage held; invoked explicitly for a repo-wide or subsystem-wide campaign.

Shipping

  • planning: Writes and reviews executable plans with repository evidence, vertical slices, and explicit acceptance criteria.
  • tidy: Diff or PR review with file:line findings in confirmed and plausible tiers (bugs, structure, AI slop, security, new-test gating), report-only by default; apply mode lands the fixes and simplifies the diff.
  • pr-creator: PRs with short human descriptions, Linear IDs, templates, drafts, tidied commits.
  • pr-babysitter: Watches an open PR: conflicts, CI, comments. Fixes what it can.
  • autoship: npm releases with changesets: fix loop, CI watch, Version Packages merge, OIDC publish verify.
  • ci-speedup: Finds where changes wait from push to deploy, then fixes the critical path, check placement, merge queue or post-merge revert, flaky tests, and deploy rate, and installs an agentic merge loop on GitHub (no merge queue, post-merge bisect and revert, agent re-lands and repairs), with a ledger.

Authoring

  • chat-history: Recover decisions, previous fixes, and context from past AI conversations with fast local search and source evidence.

  • agents-md: Wires a repo so Claude Code, Codex and Cursor read the same instructions, migrates to native AGENTS.md without Claude wrappers, then audits and refactors instructions with grades and holds them to a size budget.

  • agent-skills-creator: Creates and audits skills by their added value, with portable workflows, a validator, and regression scenarios.

  • save-md: Writes a named source as a markdown file the next turn can reread.

License

MIT


Crafted by Matthew Blode

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/agent-ready/SKILL.md7.8 KBupstream ↗
    ---
    name: agent-ready
    description: Implements agent-readiness on public sites and docs from Mintlify Agent Score, AFDocs, Is Agentic, Is It Agent Ready, or url-discovery-bench reports, or from server logs of agents 404ing on guessed URLs. Use when asked to "make our site agent-ready", "improve Agent Score", "fix llms.txt coverage", "agents keep 404ing on our docs", or when a pasted scorecard is the brief.
    compatibility: The verification script needs Bash and curl. Scanner commands need Node.js and npm registry access.
    ---
    
    # Agent 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](https://is-agentic.com/), [Is It Agent Ready](https://isitagentready.com/), or [url-discovery-bench](https://github.com/mintlify/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](https://github.com/vercel-labs/is-agentic); that skill retrieves reports. This one implements the product.
    
    ## Contents
    
    - [Workflow](#workflow)
    - [Reference files](#reference-files)
    - [Priority](#priority)
    - [Output](#output)
    - [Gotchas](#gotchas)
    
    ## 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
    npx afdocs check <docs-url> --format scorecard --sampling deterministic
    npx 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](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](references/api-surfaces.md) | Is Agentic API findings: JSON errors, OpenAPI, versioning, rate limits, function calling, CLI, MCP |
    | [references/site-discovery.md](references/site-discovery.md) | Is It Agent Ready: robots, sitemap, Link headers, DNS-AID, well-known catalogs, bot rules |
    | [references/verification.md](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:
    
    1. 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.
    2. 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).
    3. Warnings on those same surfaces (`llms.txt` coverage, buried directives, wrong `Content-Type`).
    4. Recommended checks that match a surface already in the repo (OpenAPI, MCP, OAuth).
    5. 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
    
    - 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 machin
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/mblode-agent-skills-skills-agent-ready.md

// REPO STATS

198 stars
0 open issues
Last commit: 4d ago