agentleFS
MuhnadMuhnad/a11y-checker/skills/a11y-fix/SKILL.md

a11y-fix

Skill117 starsChanged 35 days agoMITView on GitHub

Find and fix accessibility problems in a web page or codebase (React, Next.js, React Native, Angular, plain HTML/JS), or in just the files or directories the user names. Use when asked to audit, check or fix accessibility (a11y, WCAG, axe, screen reader, alt text, labels, contrast).

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. badass-courses/a11y-agent★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 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.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do both for a web app when you can: source first, then the URL.

    line 16
  2. Very specific:

    Use fixHint as the starting point.

    line 34
  3. Very specific:

    Prefer native HTML (<button>, <label>, <nav>) over adding ARIA.

    line 35

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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
SKILL.md

a11y-fix

Scan, fix, rescan, report. Uses the a11y-checker MCP tools (scan_page, explain_rule); if they are not available, use the CLI: npx a11y-checker <target> --json. The CLI prints a bare JSON array of findings and exits 1 when there are any (that is not a crash).

1. Pick the target

Scope first. Scan only what the user named: a file, several files, a directory or a URL. Pass them all in one call (target can be a list; the CLI takes several arguments). If they named nothing, ask which files or directories; scan the whole project only when they ask for the whole codebase. Only edit files inside that scope, and report (do not fix) findings that point outside it.

  • Source code: scan the directory or file. A directory scan covers JS/TS/JSX/TSX (React, Next.js, React Native), Vue (.vue), Astro (.astro, needs eslint-plugin-astro; if a Warning: says it was skipped, run npx a11y-checker init), Angular templates (.html fragments and inline template: strings in *.component.ts), and full HTML pages (rendered and checked with axe). Svelte, template engines and DOM code built in plain JS (document.createElement) are not linted statically; scan the running page's URL instead. Findings carry file and line. Works without a running app and is the only option for React Native.
  • Running app or page: scan the URL (start the dev server first if needed). Findings carry a CSS selector and html. Use this too for Next.js, because it checks the rendered result (e.g. next/image alt, page title, contrast), which source scanning cannot.
  • Do both for a web app when you can: source first, then the URL.

An .html file path is rendered directly, no server needed. A directory or any other file is linted as source.

Next.js and multi-page apps have many routes. Scan each important route's URL.

2. Scan

Call scan_page with the target. If the result (or the CLI's stderr) carries a Warning: about skipped files or nothing to scan, those files were not checked. Never report a clean result for them: say so, and scan the running app's URL instead (or ask for it). Add tags: ["wcag2aa", "wcag22aa"] for a specific WCAG level. For client-rendered pages, pass waitFor with a selector that appears once the app has rendered.

3. Fix

Work through findings, most severe first (critical, serious, moderate, minor). Source findings are all serious, so order those by file.

Fix the root cause, then rescan: one change often clears several findings (a clickable <div> turned into a <button>, one missing <main>).

  • Source findings: open file at line and fix it there.
  • Web findings: locate the element in source. Search for distinctive text from html, the id, class or data-testid in selector. Fix the component that renders it, not just one instance.
  • Use fixHint as the starting point; call explain_rule for a web ruleId when the hint is not enough.
  • Prefer native HTML (<button>, <label>, <nav>) over adding ARIA. Add lang to <html>, an alt to images (alt="" only if decorative), a name to every control.

Do not guess content. These need the real content and count as not fixable by you: alt text, link text, button names, page <title> and <h1>. If you cannot tell what something is for, ask; if you cannot ask, leave it and list it in the report.

4. Rescan

Scan the same target again. Repeat steps 3 and 4 until only findings that need real content remain, at most three rounds.

5. Report

Give: what was fixed (rule, file), what remains, and why. Always call out these as needing a human:

  • Color contrast (color-contrast): needs a design decision.
  • Meaningful alt text, captions and transcripts.
  • Anything automated tools cannot judge. Automated scanning finds only part of the problems; say so, and recommend a keyboard and screen reader pass.

Known gaps

  • Source scanning does not check Next.js <Image> alt text. The URL scan does.
  • Source findings have no WCAG tags and are all reported as serious.
  • Source scanning does not cover Svelte, template engines or markup built by plain JS; use the URL scan for those.

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.