agentleFS
MuhnadMuhnad/a11y-checker/AGENTS.md

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.

  • In this repository2 other files it gives its agents.

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
  1. Distinctive:

    Don't commit, push, publish or tag unless asked.

    line 22

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 chromium
  • npm run lint, npm run typecheck
  • npm run test:unit: unit tests, no browser
  • npm test: builds, then runs everything, including real Chromium and ESLint

Conventions

  • Tests live in test/. Unit tests are test/unit/<src-module>.test.ts: no browser, mocks allowed. Integration tests are test/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), and cli, mcp, package for 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 in test/helpers.ts (not a test file).
  • src/: cli.ts and index.ts are the entry points, engines/ holds the two scan engines, commands/ the CLI commands, mcp/ the MCP server; scan.ts, types.ts, threshold.ts and sequential.ts are shared. manifest.ts and skill.ts stay at the root because they find package.json and skills/ with new URL('../…', import.meta.url), which works only one level below the package root (src/ and the flat dist/).
  • Engines and framework plugins are imported lazily (await import(...)) so start-up stays fast. Don't add a static import of engines/web.js, engines/source.ts or a plugin to cli.ts, scan.ts or commands/run.ts.
  • ESLint stays on 9: eslint-plugin-jsx-a11y peers only up to 9.
  • eslint-plugin-astro is an optional peer on purpose (its ESLint 9 releases pull in an unpatched braces). Don't move it to dependencies.
  • The agent workflow is written once, in skills/a11y-fix/SKILL.md. The MCP prompt (src/mcp/server.ts), install-skill and the Claude Code plugin all deliver that file: change it there, not in copies.
  • Don't commit, push, publish or tag unless asked.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.