a11y-checker
AGENTS.md117 starsChanged 35 days agoMITView on GitHub
Agent-native accessibility scanner: CLI, MCP server and agent skill over two engines (web: Playwright + axe-core, source: ESLint a11y plugins) that return one Finding schema. Node 22+, TypeScript, ESM + CJS via tsup.
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
The file
We split this AGENTS.md into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Don't commit, push, publish or tag unless asked.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
a11y-checker
Agent-native accessibility scanner: CLI, MCP server and agent skill over two engines (web: Playwright + axe-core, source: ESLint a11y plugins) that return one Finding schema. Node 22+, TypeScript, ESM + CJS via tsup.
Commands
npm install && npx playwright install chromiumnpm run lint,npm run typechecknpm run test:unit: unit tests, no browsernpm test: builds, then runs everything, including real Chromium and ESLint
Conventions
- Tests live in
test/. Unit tests aretest/unit/<src-module>.test.ts: no browser, mocks allowed. Integration tests aretest/integration/<area>/<subject>.integration-test.ts: real ESLint, plugins, Chromium or the built binary, nothing stubbed. Put each behaviour on the lowest layer that can catch it. - Integration areas: one folder per framework (
react,vue,astro,angular,html),scan/for cross-framework scans (mixed code, warnings,resolveTarget, real-project noise), andcli,mcp,packagefor the three delivery surfaces. File names are kebab-case. - Fixtures are shared in
test/fixtures/, grouped by the same names (react/web,vue,html/bad.html,scan/mixed). Helpers shared by integration tests go intest/helpers.ts(not a test file). src/:cli.tsandindex.tsare the entry points,engines/holds the two scan engines,commands/the CLI commands,mcp/the MCP server;scan.ts,types.ts,threshold.tsandsequential.tsare shared.manifest.tsandskill.tsstay at the root because they findpackage.jsonandskills/withnew URL('../…', import.meta.url), which works only one level below the package root (src/and the flatdist/).- Engines and framework plugins are imported lazily (
await import(...)) so start-up stays fast. Don't add a static import ofengines/web.js,engines/source.tsor a plugin tocli.ts,scan.tsorcommands/run.ts. - ESLint stays on 9:
eslint-plugin-jsx-a11ypeers only up to 9. eslint-plugin-astrois an optional peer on purpose (its ESLint 9 releases pull in an unpatchedbraces). Don't move it todependencies.- The agent workflow is written once, in
skills/a11y-fix/SKILL.md. The MCP prompt (src/mcp/server.ts),install-skilland the Claude Code plugin all deliver that file: change it there, not in copies. - Don't commit, push, publish or tag unless asked.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

