readiness-audit 1.2.0 → 1.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/README.md +1 -1
- package/STANDARD.md +32 -27
- package/package.json +1 -1
- package/src/audit.mjs +2 -2
- package/src/helpers.mjs +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.2.1 (2026-10-06)
|
|
4
|
+
|
|
5
|
+
Principle 7 told skills to have the agent confirm with its person before registering, publishing or rotating a key, and S1 required it of every skill that publishes. That gates the core loop: an agent following it can't finish on its own, and a skill limited to explicit requests isn't used when it would help. No scoring changes.
|
|
6
|
+
|
|
7
|
+
- **Principle 7 is now "Tell agents the consequences, then let them act."** Skills, tool descriptions and responses say what becomes public, what can't be undone and what costs money. MCP annotations carry the same facts, and approval policy belongs to the client and whoever runs the agent.
|
|
8
|
+
- **New principle 10, "Caution has a cost, so count it."** Confirmation steps, ask-first lines, narrow triggers and disclaimers cost installs, engagement and organic discovery. Name the harm before adding a restriction, keep "only when asked" for destructive actions, and undo a change that lowers T5 or the come-back measure. Principles 8 and 9 keep their numbers.
|
|
9
|
+
- **S1:** trigger on the job, specifically enough not to fire on unrelated requests, and say what lasting actions do, with no ask-first gates on the core loop. ClawHub's scan flagged drifts' first plugin for broad triggers ("explore, travel"); animalhouse's plugin, with job-specific triggers and no gates on the core loop, scanned clean. The scorecard's S1 review line says the same. botsmatter had already declined the old rule. If your skills have ask-first lines or explicit-only triggers from the old wording, take them out of the core loop; republishing is the owner's call.
|
|
10
|
+
- **T5:** record every point where the agent couldn't go on by itself (`STOPS` in the runner's report). The runner's prompt no longer tells the agent to read the docs and the API, since finding them is part of what T5 measures, so earlier results aren't directly comparable. Record the full model ID: an alias like `sonnet` moves to each new release.
|
|
11
|
+
- **Fewer examples to copy.** Agents adopting the standard turn its examples into their own skills and copy, so rules teach with a generic example, a `[placeholder]` template or a check question, and name a project only as evidence: W1's title pattern, T2's come-back measure, the T5 goal, A8's placeholders (taken from your own docs, not a fixed list), A11, E2's mechanics (now attributed), E6 (applies when you run related sites), S3 (no skill counts; ClawHub flags near-identical skills as template spam) and §12's timestamp gotcha. S1 gains two check questions. README and §13 no longer list skills that act without asking as a gap. ClawHub observations get a dated row in §16.
|
|
12
|
+
- **docs/recipes.md:** route handlers take `params` as a promise (Next.js 15 and later), and Next.js 16 calls middleware `proxy.ts`.
|
|
13
|
+
- **AGENTS.md:** examples get copied; every restriction names the harm it prevents; the standard describes the current rule, and history goes here and in commits.
|
|
14
|
+
- **Examples that fit any project:** the T5 goal, A7, A8's aliases, N2 and W3 no longer use one project's terms. The principles list now says the first six (not seven) came from all six projects.
|
|
15
|
+
- **docs/adopting.md:** a third switch-over rule, that every restriction names the harm it prevents; step 5 says why it asks first; the intro no longer leads with a score.
|
|
16
|
+
|
|
3
17
|
## 1.2.0 (2026-10-06)
|
|
4
18
|
|
|
5
19
|
From drifts.bot's switch-over, the third project to adopt the standard. One new warning (D4), no new failures. It also ships 1.1.0, which wasn't published to npm.
|
package/README.md
CHANGED
|
@@ -49,7 +49,7 @@ The scorecard covers what's visible from outside. It checks:
|
|
|
49
49
|
- a sample of skill files: spec names and descriptions, and links to llms.txt and the API reference;
|
|
50
50
|
- markdown negotiation, the AI catalog, the DNS AID record, the API catalog, auth.md and the skills index.
|
|
51
51
|
|
|
52
|
-
It can't see whether `next_steps` guide well, whether input is forgiving, whether skills
|
|
52
|
+
It can't see whether `next_steps` guide well, whether input is forgiving, whether an agent can follow your skills through the core loop, or whether you have tests. The standard marks those items "review" or "test". The agent usability test (T5) measures what all of it is for: whether a fresh agent, given only your domain and a goal, succeeds. [docs/usability-test.md](docs/usability-test.md) has the procedure and a runner. A high score is not the goal.
|
|
53
53
|
|
|
54
54
|
## Use it in your project
|
|
55
55
|
|
package/STANDARD.md
CHANGED
|
@@ -33,7 +33,7 @@ This is the common standard our projects work toward, published for anyone who b
|
|
|
33
33
|
|
|
34
34
|
## 1. Principles
|
|
35
35
|
|
|
36
|
-
The first
|
|
36
|
+
The first six came from all six projects independently.
|
|
37
37
|
|
|
38
38
|
1. **One source per fact.** The site URL, install lines, counts and request schemas each live in one module. Every discovery file, card, manifest, skills index and MCP tool list is generated from it. (inbed keeps the facts in `agent-discovery.ts`; at animalhouse the OpenAPI registry generates the spec, the MCP tools and the server card.)
|
|
39
39
|
2. **Only declare what's true.** A manifest is a promise a client will act on. An A2A card with no A2A endpoint, OAuth metadata for an authorization server that doesn't exist, or a catalog entry typed as something it isn't sends agents into a dead end, and validators flag it. Answer the paths you don't support with a JSON 404 that points to what you do run. When a scanner's score and the truth disagree, the truth wins ([What scanners check](#what-scanners-check)).
|
|
@@ -41,9 +41,10 @@ The first seven came from all six projects independently.
|
|
|
41
41
|
4. **Guard every surface with a test you've watched fail.** Untested discovery files drift without anyone noticing. A magnifica skills index advertised a parameter the API rejects. The animalhouse `agents.txt` still said "there is no hosted MCP" after the hosted endpoint shipped.
|
|
42
42
|
5. **Make the first call worth it, and point every response at the next one:** `next_steps` with ready-to-send bodies, and errors carrying a `suggestion` that names the call that fixes them.
|
|
43
43
|
6. **Be forgiving at the edge and strict where it counts.** Accept aliases, any `Accept` header and guessable wrong paths. Never guess on a write.
|
|
44
|
-
7. **
|
|
44
|
+
7. **Tell agents the consequences, then let them act.** Skills, tool descriptions and responses say what becomes public, what can't be undone and what costs money. MCP annotations (`readOnlyHint`, `destructiveHint`) carry the same facts in a form clients act on, so any approval policy belongs to the client and whoever runs the agent. An agent should be able to finish your core loop on its own, and T5 measures whether it can.
|
|
45
45
|
8. **Raise the floor together.** When one project finds a better way, it goes into this standard, and the others adopt it. The scorecard and the status page make the gaps visible.
|
|
46
46
|
9. **A project's values come first.** A project may decline items that conflict with what it stands for. achurch.ai rules out engagement mechanics, recommendation algorithms and analytics beyond aggregate traffic, so it declines those parts of E2, E6 and T2. A decision written down with its reason counts as meeting the item. Silence doesn't.
|
|
47
|
+
10. **Caution has a cost, so count it.** Every confirmation step, ask-first line, narrow trigger, disclaimer or feature pulled "to be safe" costs the product something. An agent told to stop and ask can't finish the core loop, and a skill that waits for a request naming your product isn't used when it would help. That shows up as fewer installs, less engagement and less organic discovery, which are the reasons to run the project at all. Name the harm before adding a restriction, and keep "only when asked" for actions that destroy something, like deleting data or rotating a key. If T5's success rate, the come-back measure (T2) or installs drop after a change, undo it. Coding agents lean cautious by default, so when you adopt this standard, add only the restrictions it asks for.
|
|
47
48
|
|
|
48
49
|
---
|
|
49
50
|
|
|
@@ -104,9 +105,10 @@ What it means:
|
|
|
104
105
|
| takes payments from agents | that payment protocol's manifest | |
|
|
105
106
|
| is free | a JSON 404 at the payment paths (`x402`, `mpp`, `payment-manifest`) saying so | payment manifests |
|
|
106
107
|
| has endpoints with side effects | a robots `Disallow` for each one, so a crawler can't trigger it | |
|
|
107
|
-
| has agents that write or post |
|
|
108
|
+
| has agents that write or post | S1's consequence statements and the honesty rules in A11 | ask-first gates on the core loop (principle 10) |
|
|
108
109
|
| has many generated pages (profiles, items, versions) | W3's one indexability rule, and W6's unique paragraph per page | indexing every version or empty profile |
|
|
109
110
|
| serves several languages | W11 | |
|
|
111
|
+
| runs related sites for the same audience | E6 | |
|
|
110
112
|
| rules out engagement mechanics | the items in E2 that fit its values, with the rest declined in writing (principle 9) | |
|
|
111
113
|
|
|
112
114
|
---
|
|
@@ -296,7 +298,7 @@ The evidence that this work pays: achurch.ai's August batch rewrote titles and s
|
|
|
296
298
|
**W1 Titles and descriptions.** *Why: they're the snippet people choose from (achurch's click-through rate rose after the rewrite).*
|
|
297
299
|
- **One helper builds every page's metadata:** title, description, canonical, Open Graph and Twitter tags (drifts' `pageMetadata()`, achurch's page-meta builder, inbed's `generateMetadata`). Change it in one place.
|
|
298
300
|
- **Unique per URL, generated from the page's data.** botsmatter's 1,937 Ground versions once shared 43 titles.
|
|
299
|
-
- **Titles name what people search for**, with the brand last after a
|
|
301
|
+
- **Titles name what people search for**, with the brand last after a `|`: `[what the page offers] | [brand]`.
|
|
300
302
|
- **Descriptions of about 140 to 160 characters,** built from whole sentences or cut at a word boundary, never mid-word.
|
|
301
303
|
- **Lengths are a guide, not a rule.** Google sets no limit: it cuts titles and snippets to the screen's width and may rewrite them. Titles under about 70 characters usually show in full. The scorecard warns past 70 and outside 50 to 160.
|
|
302
304
|
- **Set them on the server.** A client-side `document.title` overwrites the server's title after load, so people and crawlers see different titles (achurch).
|
|
@@ -311,7 +313,7 @@ The evidence that this work pays: achurch.ai's August batch rewrote titles and s
|
|
|
311
313
|
|
|
312
314
|
**W3 One rule for what's indexable.** *Why: thin, duplicate and test pages fill Google's "crawled, not indexed" bucket and drag down how the rest of the site is judged.*
|
|
313
315
|
- One rule decides which pages are indexable, and the sitemap, the page's robots meta and internal recommendation lists all use it (inbed's `indexable()` SQL column; at animalhouse the sitemap's filters are mirrored by `noindex`).
|
|
314
|
-
- Not indexable: test and template accounts ([recipe](docs/recipes.md#test-accounts-out-of-public-pages-t5-w3)), empty profiles,
|
|
316
|
+
- Not indexable: test and template accounts ([recipe](docs/recipes.md#test-accounts-out-of-public-pages-t5-w3)), empty profiles, unfinished or ephemeral items, filtered views, sign-in pages, and thin pages (inbed: chats with fewer than five messages). They still render, with `noindex`, and stay out of the sitemap. Google has no `follow` rule (following links is the default), so don't count on `noindex` pages to get other pages found: link those from indexable pages (W7).
|
|
315
317
|
- Missing items return a real 404 (or 410; Google treats them the same), never a 200 page that says "not found". Google calls that a soft 404 and drops it (achurch fixed a silent fallback). Empty filter combinations and page numbers past the end get a 404 too.
|
|
316
318
|
- In Next.js, a `loading.tsx` above a detail page streams a 200 before `notFound()` runs, so every missing item answers 200. inbed moved its root `loading.tsx` off the profile routes, and missing profiles went from 200 to 404 in production. Keep loading boundaries off the routes of detail pages; the scorecard's missing-page probe shows whether it worked.
|
|
317
319
|
- The sitemap lists only indexable canonical URLs that answer 200 without a redirect. Google and Bing both ignore `changefreq` and `priority`, and both use `lastmod` only when it's the real date of a meaningful change (D2). Bing asks for ISO 8601 with a time. Leave `lastmod` off where it would churn: drifts omits it on profiles, whose activity changes every few minutes.
|
|
@@ -384,7 +386,7 @@ magnifica does this for 15 languages.
|
|
|
384
386
|
|
|
385
387
|
The test is whether most of the six projects should do it. These came from one or two projects and don't pass:
|
|
386
388
|
|
|
387
|
-
- **Share actions to X or Moltbook in `next_steps`** (inbed): untested elsewhere
|
|
389
|
+
- **Share actions to X or Moltbook in `next_steps`** (inbed): untested elsewhere. Where a project adds them, the step says the post is public (principle 7).
|
|
388
390
|
- **Commit messages that end with a call to action:** a team habit; neither search nor agents read them.
|
|
389
391
|
- **Keyword-rich image file names** (drifts): little measurable effect.
|
|
390
392
|
- **A web manifest and a light/dark `theme-color`:** nice for installability, no effect on search.
|
|
@@ -403,7 +405,7 @@ The test is whether most of the six projects should do it. These came from one o
|
|
|
403
405
|
|
|
404
406
|
- **Make it a thin adapter over the same operations as the REST API.** One tool per operation, with the same names, generated from the OpenAPI spec where you can (animalhouse) and held to it by parity tests (achurch.ai checks that each tool returns exactly what its REST twin does, in both protocol eras).
|
|
405
407
|
- **Write descriptions for the model:** when to call the tool, what it returns, what becomes public and what stays private. Starting with `Wraps METHOD /path.` lets `next_steps` map straight to a tool.
|
|
406
|
-
- **Annotate:** `readOnlyHint` on reads and `destructiveHint` on irreversible actions, so
|
|
408
|
+
- **Annotate:** `readOnlyHint` on reads and `destructiveHint` on irreversible actions, so each host can apply its own policy: reads run freely, and irreversible actions get whatever its operator chose (principle 7).
|
|
407
409
|
- **Turn API errors into tool results** with `isError: true`, carrying the API's own words. An MCP endpoint should never answer HTTP 401, because a 401 sends clients into OAuth discovery.
|
|
408
410
|
- **Put `next_steps` in every result,** each naming the tool that takes it (achurch.ai).
|
|
409
411
|
- **Add prompts and resources:** prompts for getting started and for the core loop; resources such as `about` and any doc by path.
|
|
@@ -472,7 +474,9 @@ The test is whether most of the six projects should do it. These came from one o
|
|
|
472
474
|
- Keep the body under 500 lines and about 5,000 tokens (the spec's recommendation); ClawHub practice is under 20 KB.
|
|
473
475
|
- One skill per job or intent; never reshuffled duplicates.
|
|
474
476
|
- **Keep display titles out of `name`.** ClawHub ranks on the display title, and its CLI takes that title separately (`clawhub publish --name "..."`; animalhouse's publish script passes the H1). So the frontmatter `name` can follow the spec. Skills that ship inside a plugin must: Claude Code, Codex and Cursor load them.
|
|
475
|
-
- **Trigger
|
|
477
|
+
- **Trigger on the job, and say what lasting actions do.** The description names the job specifically enough that an unrelated request can't match it, and it applies to any request that fits the job. The body says what becomes public, what's saved on the machine and what can't be undone, and an agent can follow it through the core loop on its own (principle 10). Keep "only when the user asks" for actions that destroy something, like deleting data or rotating a key.
|
|
478
|
+
- **Check it:** could a request that has nothing to do with your product match the description? Could an agent with no person present finish the core loop by following the skill?
|
|
479
|
+
- **What ClawHub's scan did:** it rated drifts' first plugin suspicious for broad triggers: general activities that unrelated requests also match. animalhouse's plugin can do the same things (register a persistent account, save a key, create public pages); its triggers name its job, it states the consequences, and an agent runs the core loop without stopping. It scanned clean. That's one case each, so if a scan flags you, make the smallest change that passes and record what it was.
|
|
476
480
|
- **Link the map.** Every skill links llms.txt and the API or MCP reference (`/docs/api.md`, `/openapi.json` or your MCP docs), because an agent's fetch tool only reads what it's pointed at (D4). The scorecard checks this on a sample of skills from your index. At animalhouse, the core skill and both plugin skills linked neither.
|
|
477
481
|
- **Serve the raw file** at a stable URL so an agent can install it with one fetch (`/.well-known/agent-skills/<name>/SKILL.md` keeps the folder name in the URL), plus a `/skills` page. Index them in S2, with each digest computed from the bytes you serve.
|
|
478
482
|
- **Index the skills the site serves, not every listing.** inbed lists about 95 skills on ClawHub and indexes the 6 its site serves; animalhouse indexes 93 of 176, leaving out keyword variants of its core guide. Publishing an index makes S1 apply, so the required count goes up by one. Editing skills to pass it means republishing them and syncing any plugin copies, which is the owner's call.
|
|
@@ -481,7 +485,7 @@ The test is whether most of the six projects should do it. These came from one o
|
|
|
481
485
|
|
|
482
486
|
*Recommended.*
|
|
483
487
|
|
|
484
|
-
- **Per-item skills** can each rank for their own searches: one
|
|
488
|
+
- **Per-item skills** can each rank for their own searches: one for each item people look for by name (animalhouse, inbed and drifts publish them). Give each its own display name and content, with no keyword stuffing: ClawHub flags near-identical skills as template spam.
|
|
485
489
|
- **ClawHub rules:**
|
|
486
490
|
- Skills and plugins share one namespace.
|
|
487
491
|
- New releases stay hidden until the security scan passes.
|
|
@@ -530,10 +534,10 @@ The test is whether most of the six projects should do it. These came from one o
|
|
|
530
534
|
*Required.*
|
|
531
535
|
|
|
532
536
|
- **A7** A JSON catch-all for unknown API paths:
|
|
533
|
-
-
|
|
537
|
+
- An action name used as a path gets a 404 that names the right call (animalhouse answers `POST /api/house/feed` with `POST /api/house/care` and `{"action": "feed"}`).
|
|
534
538
|
- A real operation's name in the wrong place gets `did_you_mean`.
|
|
535
539
|
- A cut-off link gets a 308 to the real path, with a relative `Location`.
|
|
536
|
-
- **A8** Accept the aliases agents guess: `id` or `
|
|
540
|
+
- **A8** Accept the aliases agents guess: `id` or the full field name (`post_id`); a UUID, slug or display name; `Bearer` in any case (one of our projects accepted only the exact capitalization); a bare key; `X-API-Key`. Truncate over-long text with a warning instead of rejecting it, and reject a value copied from a placeholder in your own docs or examples, with a clear message. Reads may default; writes never guess: with several possible targets and none named, return a 400 with the list. Help polling agents with `since` filters, `total_pages` and a recommended next check-in time.
|
|
537
541
|
|
|
538
542
|
### A9 Limits machines can read
|
|
539
543
|
|
|
@@ -556,7 +560,7 @@ The test is whether most of the six projects should do it. These came from one o
|
|
|
556
560
|
|
|
557
561
|
*Required.*
|
|
558
562
|
|
|
559
|
-
- Say what becomes public. Keep private reads
|
|
563
|
+
- Say what becomes public. Keep private reads, such as a search, separate from public writes, such as a post.
|
|
560
564
|
- One function strips private fields from every response. A hand-rolled strip in one of our projects once let private fields through.
|
|
561
565
|
- Search and answers draw only on pages the site serves, so every citation opens (achurch.ai).
|
|
562
566
|
- Agent contributions that change shared content go through review (achurch.ai's contributions open a pull request).
|
|
@@ -566,11 +570,11 @@ The test is whether most of the six projects should do it. These came from one o
|
|
|
566
570
|
*Required: give agents some reason to return. Which mechanics you use is your choice, and any of them may be declined (principle 9).*
|
|
567
571
|
|
|
568
572
|
- **Time:**
|
|
569
|
-
- A real-time clock, so stats decay while the agent is away.
|
|
570
|
-
- Time-locked steps with a teaser and an unlock time.
|
|
571
|
-
- A daily prompt.
|
|
573
|
+
- A real-time clock, so stats decay while the agent is away (animalhouse).
|
|
574
|
+
- Time-locked steps with a teaser and an unlock time (drifts).
|
|
575
|
+
- A daily prompt (botsmatter).
|
|
572
576
|
- Keep the first steps unlocked: at drifts, a lock right after step 1 is where most travelers left.
|
|
573
|
-
- **Something the agent owns:** a postcard assembled from its own reflections
|
|
577
|
+
- **Something the agent owns:** a public profile, a postcard assembled from its own reflections (drifts), a portrait gallery or a gravestone (animalhouse).
|
|
574
578
|
- **An inhabited world:** platform activity (inbed's `room`, animalhouse's house activity), excerpts from others' reflections on the same step, anonymous popularity.
|
|
575
579
|
- **Progress and anticipation** in varied wording, and recommendations with one slot reserved for something new.
|
|
576
580
|
- **Continuity for agents without memory:** `while_you_were_away`, `your_recent`, a scheduling hint (`recommended_checkin`), and a heartbeat that keeps an active agent ranked as active (inbed).
|
|
@@ -604,15 +608,15 @@ The test is whether most of the six projects should do it. These came from one o
|
|
|
604
608
|
|
|
605
609
|
### E6 Point to the sibling projects
|
|
606
610
|
|
|
607
|
-
*Recommended
|
|
611
|
+
*Recommended when you run related sites for the same audience.* List them in llms.txt and the `/for-agents` page; for some projects (achurch.ai) that's enough. In API responses, mention a sibling only where it's relevant to what the agent just did. inbed links one in about 30% of responses; at that rate a link can read as an ad.
|
|
608
612
|
|
|
609
613
|
---
|
|
610
614
|
|
|
611
615
|
## 9. Next level
|
|
612
616
|
|
|
613
|
-
Higher-value features that most of our projects don't have yet. Each one fixes a failure we've seen or can predict. Build one when your own traffic shows the problem: botsmatter checked its logs and found duplicate writes too rare to need N2.
|
|
617
|
+
Higher-value features that most of our projects don't have yet. Each one fixes a failure we've seen or can predict. Build one when your own traffic shows the problem: botsmatter checked its logs and found duplicate writes too rare to need N2.
|
|
614
618
|
|
|
615
|
-
**D8 Markdown for agents
|
|
619
|
+
**D8 Markdown for agents.** Markdown costs an agent fewer tokens than HTML, and some agent fetchers ask for it with `Accept: text/markdown`. But none of our logs can show that traffic yet: Railway's HTTP logs, which several of our projects use, keep the user agent but not the `Accept` header. And a scanner check alone doesn't make an item recommended (principle 3). *Build it when* your logs show agents asking: log the `Accept` header in middleware to find out ([recipe](docs/recipes.md#markdown-for-agents-without-a-cdn-plan-d8)).
|
|
616
620
|
- Start with the homepage and your docs, not every page. `Accept: text/markdown` and a `.md` URL both return the page as markdown. animalhouse serves llms.txt as the homepage's markdown, and its API reference at `/docs/api.md`.
|
|
617
621
|
- No CDN plan is needed: a `.md` route and a few lines of middleware do it ([recipe](docs/recipes.md#markdown-for-agents-without-a-cdn-plan-d8)). Cloudflare's Markdown for Agents feature (Pro and up) converts pages for you, but it's optional.
|
|
618
622
|
- Send `Vary: Accept` on both representations (RFC 9110 §12.5.5). Otherwise a cache can hand HTML readers the markdown, or the reverse.
|
|
@@ -622,7 +626,7 @@ Higher-value features that most of our projects don't have yet. Each one fixes a
|
|
|
622
626
|
- Negotiate in front of prerendered pages too, or they ignore it (magnifica).
|
|
623
627
|
- Whole-corpus indexes help: `/docs/index.md` and `/docs/index.json` (achurch.ai).
|
|
624
628
|
|
|
625
|
-
**N2 `Idempotency-Key` on writes** (IETF draft). Agents retry after timeouts, which can mean a duplicate registration or
|
|
629
|
+
**N2 `Idempotency-Key` on writes** (IETF draft). Agents retry after timeouts, which can mean a duplicate registration or the same action taken twice. Accept the header on every POST, store the first response for 24 hours, and replay it for a repeated key. *Build it when* your logs show the same write repeated within minutes.
|
|
626
630
|
|
|
627
631
|
**N3 Conditional requests on polled reads.** Send an `ETag` (or `Last-Modified`) and answer `If-None-Match` with a 304, so an unchanged check-in costs almost nothing on either side. *Build it when* scheduled polling is a large share of your traffic.
|
|
628
632
|
|
|
@@ -654,13 +658,13 @@ Higher-value features that most of our projects don't have yet. Each one fixes a
|
|
|
654
658
|
- MCP log lines: for stdio servers, the User-Agent on every API call; for a hosted endpoint, the protocol era, method, tool and client.
|
|
655
659
|
- Structured request and error logs (drifts writes JSONL, rotated daily) and admin analytics.
|
|
656
660
|
- Logs that outlive a deploy. Logs written inside the container vanish with it: after one deploy, drifts had five minutes of history. Keep them on a volume, ship them out, or use the platform's own HTTP logs.
|
|
657
|
-
- **T2 Attribution and one come-back measure** (required; per-agent tracking may be declined). Record `source` plus User-Agent per entry point, and judge entry points by who comes back, not just who signs up.
|
|
661
|
+
- **T2 Attribution and one come-back measure** (required; per-agent tracking may be declined). Record `source` plus User-Agent per entry point, and judge entry points by who comes back, not just who signs up. A come-back measure is the share of agents who return to the core action a day or more after their first success: at animalhouse, the share of adoptions that get care again 24 hours or more after hatching (about 12%). An aggregate measure works for projects that rule out per-agent analytics.
|
|
658
662
|
- **T3 Reviews** (required):
|
|
659
663
|
- A monthly log review, paged so no window is truncated (platform log commands often return only the newest window): requested well-known paths, 404s, refusals, crawler user agents.
|
|
660
664
|
- After each deploy, run the scorecard, lint the OpenAPI spec, and diff generated files against the previous production output. About 24 hours later, review the logs and database query performance.
|
|
661
|
-
- **T5 The agent usability test** (required
|
|
665
|
+
- **T5 The agent usability test** (required).
|
|
662
666
|
- **Why:** it's the only check that measures what the whole standard is for, and without it the scorecard becomes the target.
|
|
663
|
-
- **How:** give a fresh agent nothing but your domain and a goal
|
|
667
|
+
- **How:** give a fresh agent nothing but your domain and a goal: your core loop, as a person would ask for it ([examples](docs/usability-test.md#setup)). Choose a goal it can finish alone: one that needs someone else to act (a match on a dating site needs the other side to like back) can't be completed in one run. Run it headless, for example `claude -p` with only web fetch and curl allowed. Record whether it succeeds, how many calls it takes, every error it hits, and every point where it couldn't go on by itself (principle 10).
|
|
664
668
|
- **When:** monthly, and after big API changes.
|
|
665
669
|
- **Report** its first-try success rate next to your score.
|
|
666
670
|
- **Rules:** run it only against your own site, with a test username so analytics filter it out.
|
|
@@ -719,7 +723,7 @@ A project with no test suite fails T4 however well it scores (botsmatter's own r
|
|
|
719
723
|
- **A crawler that follows a GET with side effects** counts as a visit. achurch.ai disallows `/api/attend`.
|
|
720
724
|
- **Supabase silently caps a select at 1,000 rows,** and its client has no default timeout.
|
|
721
725
|
- **Next.js 14.2's `force-dynamic` alone leaves fetches cached.** Use `revalidate = 0` for live pages (inbed). Route segment config can't be re-exported either.
|
|
722
|
-
- **
|
|
726
|
+
- **A timestamp set when a job notices an event records the detection, not the event** (animalhouse's `died_at`).
|
|
723
727
|
- **MCP SDK v1 can't speak 2026-07-28.** SDK v2's legacy fallback speaks only SSE and is strict about `Accept` (M4).
|
|
724
728
|
- **A redirect from `/sse` doesn't make the old SSE transport work.** 2024-11-05 clients GET `/sse` and expect an `endpoint` event.
|
|
725
729
|
- **Claude Code ignores AGENTS.md when CLAUDE.md exists,** unless CLAUDE.md imports it.
|
|
@@ -728,7 +732,7 @@ A project with no test suite fails T4 however well it scores (botsmatter's own r
|
|
|
728
732
|
- **A catalog entry's type is a claim.** Typing `mcp.json` as a server card is a false declaration even when `mcp.json` itself is honest.
|
|
729
733
|
- **A client-side `document.title`** overwrites the server's title after load, so people and crawlers see different titles.
|
|
730
734
|
- **A site-wide `twitter:title`** overrides every page's own `og:title` on X.
|
|
731
|
-
- **Two items with the same name can share one URL.** animalhouse's creature page
|
|
735
|
+
- **Two items with the same name can share one URL.** animalhouse's creature page 404'd when an agent reused a name, while the sitemap still listed the URL; the lookup now picks the item the URL means (a living one first, then one with a gravestone). W3's sitemap sample catches it.
|
|
732
736
|
- **`og:locale` and JSON-LD `inLanguage` use different formats:** `en_US` and `en-US`, `zh_CN` and `zh-Hans`.
|
|
733
737
|
- **Retired rich results still get added.** FAQ, HowTo and the sitelinks search box no longer show in Google for any site.
|
|
734
738
|
- **ClawHub's shared namespace, scan delay and account ownership** (S3).
|
|
@@ -751,7 +755,7 @@ The page lists every check for every site, the scores at each level, and each fa
|
|
|
751
755
|
Score a local or preview build before you deploy: `npx readiness-audit@1 example.com --base http://localhost:3000` requests the site's URLs from the base and reports them under the domain, skipping DNS and host redirects. To see what changed since the last run, compare against that page: `npx readiness-audit@1 <domain> --compare docs/readiness-status.md` lists what was fixed, what newly fails and what newly applies. Scores alone mislead here, because the denominator grows as items start to apply.
|
|
752
756
|
|
|
753
757
|
Read it with three caveats:
|
|
754
|
-
- **It covers only what's visible from outside.** One of our projects scored well with no test suite, and
|
|
758
|
+
- **It covers only what's visible from outside.** One of our projects scored well with no test suite, and the score couldn't show it.
|
|
755
759
|
- **Compare a project against its own applicable items, not against other projects.** A read-only site with no auth and no hosted MCP has far fewer items than one with an API, keys and an MCP endpoint.
|
|
756
760
|
- **T5 and T6 come from outside the scorecard.** Record the agent usability test (T5) and the search numbers (T6) in a JSON file and pass it with `--recorded`; they appear as rows next to the scores, or as "not recorded".
|
|
757
761
|
|
|
@@ -831,7 +835,7 @@ Level: **R** required where it applies, **Rec** recommended, **N** next level. W
|
|
|
831
835
|
| M3 | Published to npm, the MCP Registry, Smithery and Glama, one version | R | discovery | test |
|
|
832
836
|
| M4 | Hosted edge: both eras, JSON for every Accept, browser redirect, aliases, logs | R | agents, traffic | score |
|
|
833
837
|
| M5 | Server card at `<endpoint>/server-card`, listed in the AI catalog | Rec | discovery | score |
|
|
834
|
-
| S1 | Spec-compliant SKILL.md files that link llms.txt and the API or MCP reference;
|
|
838
|
+
| S1 | Spec-compliant SKILL.md files that link llms.txt and the API or MCP reference; triggers name the job; lasting actions say what they do; an agent can follow them through the core loop on its own | R | agents, honesty | score (sample), review |
|
|
835
839
|
| S2 | Skills discovery index, v0.2.0 | Rec | discovery | score |
|
|
836
840
|
| S3 | ClawHub owners map, per-item skills, slow publishing | Rec | discovery | review |
|
|
837
841
|
| S4 | Plugin bundle for four hosts, generated manifests | Rec | agents | test |
|
|
@@ -934,3 +938,4 @@ Status as of 2026-10-05. Several are drafts, so re-check before relying on a det
|
|
|
934
938
|
| AI crawlers | OpenAI, Perplexity, Anthropic docs | https://developers.openai.com/api/docs/bots · https://docs.perplexity.ai/docs/resources/perplexity-crawlers · https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler |
|
|
935
939
|
| Measured search results | achurch.ai's August 2026 retrospective | not published |
|
|
936
940
|
| isitagentready.com | Cloudflare scanner | https://isitagentready.com/ |
|
|
941
|
+
| ClawHub behavior (S1, S3) | observed while publishing (animalhouse, drifts), September and October 2026; not documented by ClawHub | https://clawhub.ai/ |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "readiness-audit",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.1",
|
|
4
4
|
"description": "Score a live site against the Agent and Search Readiness Standard: discovery files, search, API, MCP and skills, for AI agents and search engines.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
package/src/audit.mjs
CHANGED
|
@@ -12,7 +12,7 @@ import { request as httpsRequest } from 'node:https';
|
|
|
12
12
|
import { isIP } from 'node:net';
|
|
13
13
|
import { SKILL_NAME, sampleSkillEntries, skillNameProblem, cdnCacheNote, repeatsSummary, hasVariantDescription, spread, llmsLinks, baseMapper, formatRecorded } from './helpers.mjs';
|
|
14
14
|
|
|
15
|
-
export const VERSION = '1.2.
|
|
15
|
+
export const VERSION = '1.2.1';
|
|
16
16
|
export const REPO = 'https://github.com/geeks-accelerator/agent-and-search-readiness';
|
|
17
17
|
const UA = `readiness-audit/${VERSION} (+${REPO})`;
|
|
18
18
|
const AI_BOTS = ['gptbot', 'oai-searchbot', 'chatgpt-user', 'claudebot', 'claude-user', 'claude-searchbot', 'perplexitybot', 'perplexity-user', 'google-extended', 'applebot-extended'];
|
|
@@ -36,7 +36,7 @@ export const REVIEW = [
|
|
|
36
36
|
['A11', 'public and private stated honestly, one privacy filter'],
|
|
37
37
|
['M2', 'stdio package: saved key, register guard, rotate, User-Agent'],
|
|
38
38
|
['M3', 'published to npm, the MCP Registry, Smithery and Glama, one version'],
|
|
39
|
-
['S1', 'skills
|
|
39
|
+
['S1', 'skills: triggers name the job, lasting actions say what they do, and an agent can follow them through the core loop on its own (the scorecard checks names, descriptions and links on a sample)'],
|
|
40
40
|
['S3', 'ClawHub owners map'],
|
|
41
41
|
['S4', 'plugin bundle with generated manifests'],
|
|
42
42
|
['E1-E6', 'first-call value, reasons to return, scheduled-agent performance'],
|
package/src/helpers.mjs
CHANGED
|
@@ -23,7 +23,7 @@ export function spread(list, n) {
|
|
|
23
23
|
/**
|
|
24
24
|
* The site's own links in an llms.txt: markdown links and bare URLs, resolved
|
|
25
25
|
* against the file's URL, without fragments, kept only when they point at one
|
|
26
|
-
* of the site's hosts. Templates such as /
|
|
26
|
+
* of the site's hosts. Templates such as /items/{id} are skipped.
|
|
27
27
|
*/
|
|
28
28
|
export function llmsLinks(text, llmsUrl, hosts) {
|
|
29
29
|
const raw = [
|