accessibility-agent-skills

T-Mobile ARC's source-of-truth repo for Claude Code accessibility skills. Each skill is a self-contained SKILL.md file that defines a focused accessibility task — from a fast axe-core scan to a full audit-and-remediate cycle. Skills are designed to work standalone or be composed by an orchestrator into multi-stage workflows.

All skills are MCP-integrated: they query authoritative sources (MagentaA11y, WCAG, ARIA, axe-core, accessibility personas) rather than relying on model knowledge alone.

Layout

Skills live flat under platform-specific folders, prefixed with arc-a11y- so each one stays distinct in a consumer's namespace:

.
├── web/
│   ├── arc-a11y-quick-test/SKILL.md
│   ├── arc-a11y-full-audit/SKILL.md
│   ├── arc-a11y-full-audit-remediate/SKILL.md
│   ├── arc-a11y-orchestrator/SKILL.md
│   ├── arc-a11y-base-web/SKILL.md
│   ├── arc-a11y-web-standards/SKILL.md
│   ├── arc-a11y-tester-basic/SKILL.md
│   ├── arc-a11y-validator/SKILL.md
│   ├── arc-a11y-issue-writer/SKILL.md
│   ├── arc-a11y-remediator/SKILL.md
│   └── install-mcp.sh
└── (native/ — coming soon)

Web skill inventory

| Folder | name: | Purpose | Key triggers | |--------|---------|---------|--------------| | arc-a11y-base-web/ | arc-a11y-base-web | Foundational ARIA, semantic HTML, keyboard, and contrast rules. Load before other skills. | "load a11y base", "accessibility fundamentals" | | arc-a11y-quick-test/ | arc-a11y-quick-test | Fast axe-core scan — critical and serious violations only, no remediation. | "quick test", "quick scan", "just run axe", "fast a11y check" | | arc-a11y-tester-basic/ | arc-a11y-tester-basic | Full WCAG 2.2 AA axe-core run enriched with MagentaA11y acceptance criteria. | "a11y test", "test accessibility", "check for WCAG violations", "audit this URL" | | arc-a11y-web-standards/ | arc-a11y-web-standards | Static HTML/CSS/ARIA analysis without a browser — landmarks, headings, forms, ARIA validity. | "static analysis", "check my HTML", "ARIA analysis", "web standards" | | arc-a11y-remediator/ | arc-a11y-remediator | Generate corrected code for a known list of issues using MCP guidance. | "fix these issues", "remediate", "generate fixes" | | arc-a11y-validator/ | arc-a11y-validator | Re-run tests after fixes and verify against acceptance criteria. | "validate fixes", "confirm fixes work", "verify remediation" | | arc-a11y-issue-writer/ | arc-a11y-issue-writer | Format violations as structured, JIRA-ready issue reports. | "write issues", "format as tickets", "create bug reports from violations" | | arc-a11y-full-audit/ | arc-a11y-full-audit | Two-stage audit (static + runtime). Produces a consolidated report. No code changes. | "full audit", "complete audit", "accessibility report", "audit without fixing" | | arc-a11y-full-audit-remediate/ | arc-a11y-full-audit-remediate | Full audit followed by an auto-fix loop until no critical/serious violations remain. | "full audit and fix", "fix all a11y issues", "audit and remediate" | | arc-a11y-orchestrator/ | arc-a11y-orchestrator | Coordinates the three-stage workflow (analysis → remediation → validation) across all skills. | "full accessibility audit", "a11y audit", "test and fix accessibility" |

Folder name and name: field match 1:1, so a folder name is a reliable identifier wherever you see it.

How skills are consumed

Skills in this repo are source of truth; consumers install them via the published Claude Code plugins:

| Platform | Plugin | Source | |----------|--------|--------| | Web | arc-a11y-web | arc-claude-plugin-web | | Native | arc-a11y-native (scaffold) | arc-claude-plugin-native |

The plugins are managed together in the arc-claude-plugin-manager monorepo, which runs build scripts that sync web/ and native/ from this repo into the plugin distributions.

Once a plugin is installed, skills are invoked with the plugin namespace + skill name:

/arc-a11y-web:arc-a11y-quick-test
/arc-a11y-web:arc-a11y-full-audit-remediate
/arc-a11y-web:arc-a11y-orchestrator

Required MCP servers

| MCP server | Used by | Purpose | |-----------|---------|---------| | playwright | all runtime skills | Browser automation, axe-core injection | | magentaa11y-mcp | arc-a11y-tester-basic, arc-a11y-quick-test, arc-a11y-validator | Component acceptance criteria | | aria-mcp | arc-a11y-web-standards, arc-a11y-remediator | ARIA role and attribute rules | | wcag-mcp | arc-a11y-web-standards, arc-a11y-remediator | WCAG 2.2 success criteria | | a11y-personas-mcp | arc-a11y-remediator | User impact context per disability type | | arc-templated-issues-mcp | arc-a11y-issue-writer | Standardized issue formatting |

Each SKILL.md lists its exact MCP requirements and graceful-degradation behavior when a server is unavailable.

One-shot install (macOS / Linux)

cd web
./install-mcp.sh

The script checks for claude and npx, skips servers already configured, and reports a per-server summary. Pass --force to reinstall everything, replacing existing entries:

./install-mcp.sh --force

After it finishes, verify with claude mcp list — each server should report ✓ Connected.

Manual install commands

If you'd rather install individually (or you're on Windows where the shell script doesn't run), use the claude mcp add commands below. Run them once at user scope (--scope user) so the servers are available across all projects. All are stdio servers launched via npx, so no global install is required.

# Browser automation (axe-core injection, runtime tests)
claude mcp add --transport stdio --scope user playwright -- npx -y @playwright/mcp@latest

# Component acceptance criteria (MagentaA11y)
claude mcp add --transport stdio --scope user magentaa11y-mcp -- npx -y magentaa11y-mcp

# ARIA roles, states, and attribute validation
claude mcp add --transport stdio --scope user aria-mcp -- npx -y aria-mcp

# WCAG 2.2 success criteria and techniques
claude mcp add --transport stdio --scope user wcag-mcp -- npx -y wcag-mcp

# Accessibility user personas (impact context per disability type)
claude mcp add --transport stdio --scope user a11y-personas-mcp -- npx -y a11y-personas-mcp

# Standardized issue templates (JIRA-ready output)
claude mcp add --transport stdio --scope user arc-templated-issues-mcp -- npx -y arc-templated-issues-mcp

Verify with claude mcp list — each server should report ✓ Connected.

Equivalent server JSON config

The commands above write the following entries into your ~/.claude.json mcpServers block. You can also paste this directly if you prefer editing the config file by hand:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "env": {}
    },
    "magentaa11y-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "magentaa11y-mcp"],
      "env": {}
    },
    "aria-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "aria-mcp"],
      "env": {}
    },
    "wcag-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "wcag-mcp"],
      "env": {}
    },
    "a11y-personas-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "a11y-personas-mcp"],
      "env": {}
    },
    "arc-templated-issues-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "arc-templated-issues-mcp"],
      "env": {}
    }
  }
}

Server sources

| Server | Source | |--------|--------| | playwright | npmjs.com/package/@playwright/mcp | | magentaa11y-mcp | npmjs.com/package/magentaa11y-mcp | | aria-mcp | npmjs.com/package/aria-mcp | | wcag-mcp | npmjs.com/package/wcag-mcp | | a11y-personas-mcp | npmjs.com/package/a11y-personas-mcp | | arc-templated-issues-mcp | npmjs.com/package/arc-templated-issues-mcp |

Workflow at a glance

Most users only need to invoke one of three entry-point skills:

| Goal | Skill | Time | |------|-------|------| | "What's broken right now?" | arc-a11y-quick-test | Fast | | "Give me a full report" | arc-a11y-full-audit | Moderate | | "Fix everything automatically" | arc-a11y-full-audit-remediate | Thorough |

arc-a11y-full-audit-remediate runs a continuous loop — audit → fix → retest — until all critical and serious violations are resolved or the 5-iteration limit is reached. All fixes are code-only; visual appearance and content are never changed.

The remaining skills (arc-a11y-orchestrator, arc-a11y-web-standards, arc-a11y-tester-basic, arc-a11y-remediator, arc-a11y-validator, arc-a11y-issue-writer, arc-a11y-base-web) are specialists — invoked by the entry-point skills, or directly for targeted work.

Adding a new skill

1. Create a folder: web/arc-a11y-<skill-slug>/ (folder name must match the name: field).
2. Add a SKILL.md with this frontmatter:

---
name: arc-a11y-<skill-slug>  # must match the folder name 1:1
description: <description>   # one paragraph; include trigger phrases for auto-routing
---

3. Structure the body with at minimum:

   • ## Required MCP Servers — list every MCP the skill calls
   • ## Workflow — numbered steps with code blocks for tool invocations
   • ## Constraints — hard rules, no-ops, and graceful-degradation behavior

4. Add a row to the web skill inventory table above.

Keep skills single-responsibility. If a skill needs to coordinate multiple steps across different tool types, prefer delegating to existing skills from an orchestrator rather than growing a single skill file.

Branch convention

tmo/main is the active branch. Plugin distributions track this branch and rebuild on demand via the manager monorepo's build scripts.

Philosophy

• ARIA-last — semantic HTML always wins; ARIA only when no native element fits
• Arrow first for T-Mobile UI — when .tdds-* fingerprints appear, the Arrow component is authoritative
• WCAG 2.2 AA is the default — AAA only when explicitly requested
• Validator always reviews — no remediation ships without arc-a11y-validator
• MCP over memory — query authoritative sources every time; don't recite

Related

• MagentaA11y — component acceptance criteria used for enrichment
• WCAG 2.2 — success criteria reference
• axe-core — automated rule engine (pinned to v4.10.2)
• Claude Code plugins — plugin spec

Owner

T-Mobile Accessibility Resource Center · [email protected]