a11y-skills
AGENTS.md0 starsChanged 29 days agoMITView on GitHub
You are contributing to a library of skills for other agents. Two things follow from that, and they override the usual instincts. The content is the product, and it is read by machines. A skill is instructions that another agent will follow without asking. So a wrong claim here does not just mislead a person, it gets executed. Accuracy beats helpfulness. This repository verifies its own claims, loudly. Almost every rule below is enforced by npm test, and the enforcement…
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 33,315 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 repository33 other files it gives its agents.
- accessible-authenticationSkill
- accessible-formsSkill
- accessible-nameSkill
- accordion-disclosureSkill
- audit-componentSkill
- carouselSkill
- charts-and-datavizSkill
- combobox-autocompleteSkill
- data-tableSkill
- email-html-accessibilitySkill
- fix-color-contrastSkill
- forced-colors-and-dark-modeSkill
- headings-and-landmarksSkill
- keyboard-focusSkill
- live-regionsSkill
- media-captionsSkill
- menu-buttonSkill
- modal-dialogSkill
- motion-and-animationSkill
- page-title-and-languageSkill
- pagination-and-searchSkill
- pointer-and-gesturesSkill
- predictable-contextSkill
- progress-and-loadingSkill
- screen-reader-test-planSkill
- semantic-htmlSkill
- skip-linksSkill
- svg-and-iconsSkill
- tabsSkill
- tooltip-popoverSkill
- triage-automated-resultsSkill
- wcag22-new-criteriaSkill
- zoom-reflow-text-spacingSkill
The file
We split this AGENTS.md into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 50
Never claim an unmeasured number anywhere: If a count appears in the README, the index, or the coverage report, it must come from the …
- Very specific: line 121
Add a dependency to bin/ or to the skills themselves.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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
Notes for AI agents working in this repository
You are contributing to a library of skills for other agents. Two things follow from that, and they override the usual instincts.
The content is the product, and it is read by machines. A skill is instructions that another agent will follow without asking. So a wrong claim here does not just mislead a person, it gets executed. Accuracy beats helpfulness.
This repository verifies its own claims, loudly. Almost every rule below is
enforced by npm test, and the enforcement is the point of the project. Do not
weaken a check to make a change pass.
Commands
npm test # content gate + README/claims pinning. No browser, fast.
npm run fixtures # axe-core in Chromium over every before/after pair
npm run build-docs # regenerate skills/README.md, docs/COVERAGE.md, the badge,
# and docs/RULE-MAP.md
npm run axe-rules # refresh verify/axe-rules.json from the installed axe-core
npm run rule-docs # regenerate docs/RULE-MAP.md and validate verify/rule-map.json
npm run demo # regenerate docs/demo.gif (needs ffmpeg)
npm run demo:cli # regenerate docs/cli.gif (needs ffmpeg)
npm run check # build-docs + test + fixturesnpm test is the gate. Run it before you claim to be done, and read the output
rather than assuming it passed.
Invariants — breaking any of these fails CI
- Frontmatter holds exactly
nameanddescription. Nothing else, ever. Criteria belong on the**Criteria:**line in the body. Awcagkey in the frontmatter looks harmless and is not portable; it is reported asSG-META-009by SkillSleuth and the report is correct. namematches the directory name.descriptionstarts withUse whenand names the user-visible trigger in the words a user would use. This is the string another agent matches a request against. A vague description means the skill silently never loads.- Criterion names are copied character-for-character from
verify/wcag-2.2.json.SC 1.4.3 Contrast (Minimum), not "Minimum Contrast". Do not citeSC 4.1.1— it was removed in WCAG 2.2. - Required sections, exactly:
## When to use,## Procedure,## Verify,## Failure modes. At least one fenced code block. At least four failure modes. - Never invent a number. 4.5:1 body text, 3:1 large text (≥24px, or ≥18.66px bold), 3:1 non-text, 24×24 CSS px target size, 2 CSS px focus perimeter. If you are unsure of a value, look it up — do not round it.
- Never claim an unmeasured number anywhere. If a count appears in the
README, the index, or the coverage report, it must come from the generator or
from a test.
verify/verify-readme.jswill catch you. skills/README.md,docs/COVERAGE.md,docs/badge-coverage.svganddocs/RULE-MAP.mdare generated. Edit the skill or the generator, thennpm run build-docs. Never hand-edit the output.after.htmlin a fixture must be completely axe-clean, best-practice rules included. If it is not, fix the fixture, not the assertion.verify/axe-rules.jsonis generated from axe-core;verify/rule-map.jsonis curated by hand. Never edit the snapshot by hand — runnpm run axe-rules. The map is the one place a judgement call is recorded, and it is checked: every rule id must exist in the snapshot, every skill must exist, and the skill must declare at least one of the criteria axe tags the rule with. If you cannot map a rule to a skill that satisfies check three, leave it out — a gap is reported honestly indocs/RULE-MAP.mdand costs nothing, while a wrong mapping fails CI and misleads anyone who follows it.- A fixture that tests a rule axe ships disabled must enable it explicitly,
with
axeOptionsin that fixture'smeta.json.target-sizeandp-as-headingare both off by default, so a fixture that names one of them without enabling it passes while testing nothing. - No logic in
action.yml. Its audit step runsscripts/ci-audit.sh, and that is all it does. Arun:block executes only on the runner, which makes it the one place here that no test can reach — and it is exactly where two real bugs lived, one of which reported every audit as zero findings while the CLI beneath it exited 1. Change the script, and change the assertions in the fixtures job with it. - A fix suggestion is either computed or labelled
structure. Inlib/fixes.js,exactmeans there is one right answer and the value is calculated — colour contrast, the viewport tag, 24×24 px.structuremeans the shape is determined but the words are the author's. Never dress a guess asexact: noalttext from a file name, no label text from a field name. Everycolor-contrastsuggestion is applied in Chromium duringnpm run fixtures, and the run fails if axe keeps reporting the finding.
Facts about axe-core that are easy to get wrong
These were measured against the committed snapshot (verify/axe-rules.json) rather
than assumed, and each one has bitten somebody:
- 15 rules are disabled by default, including
target-size— the only automated check for SC 2.5.8, one of the two criteria WCAG 2.2 itself added. A green audit says nothing about target sizes.p-as-headingis also off. duplicate-idandduplicate-id-activeare still tagged SC 4.1.1, which WCAG 2.2 removed, and are disabled. If a report cites 4.1.1, it is citing something that no longer exists.- The
labelrule accepts a non-emptyplaceholderas a label, so a placeholder-only field passes a full audit and still fails SC 3.3.2. p-as-headinghas a length heuristic: it only fires when the styled paragraph is shorter than the paragraph that follows it (failLength0.5), so a bold two-word paragraph above a long one is invisible to it.target-sizeonly applies to widgets that are not inside a text block, so a small link inside a sentence is never reported. A toolbar of icon controls is.
When a fixture fails
The failure message tells you what axe actually reported, including the rules it
found instead of the one you expected. That is usually the most interesting
output in the repository — it means your mental model of the rule is wrong.
Investigate before editing anything. For example, axe-core's label rule accepts
a non-empty placeholder as a label, which is why
verify/fixtures/accessible-forms/styled-signup uses visual <p> elements rather
than placeholders to demonstrate a missing label.
Voice
Second person, imperative, no hedging, no "simply" or "just". Prefer the platform
— a native <dialog> or <button> beats an ARIA reimplementation, and say so.
Where a check needs a human, say that rather than implying a pass.
Do not
- Add a dependency to
bin/or to the skills themselves. The shipped product is zero-dependency Markdown and Node;devDependenciesare for the fixture harness and the demo only. - Claim that anything here establishes WCAG conformance. It does not, and saying so is the most damaging thing you could write in this repository.
- Reformat skills you were not asked to touch. They are deliberately uniform and large diffs make review harder.
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.

