accessibility-agents

Accessibility Agents

AI and automated tools are not perfect. They miss things, make mistakes, and cannot replace testing with real screen readers and assistive technology. Always verify with VoiceOver, NVDA, JAWS, and keyboard-only navigation. This tooling is a helpful starting point, not a substitute for real accessibility testing.

A community-driven open-source project automating accessibility, efficiency, and productivity through AI-based agents, skills, custom instructions, and prompts.

A sincere thanks goes out to Taylor Arndt and Jeff Bishop for leading the charge in building this community project. It started because LLMs consistently forget accessibility - skills get ignored, instructions drift out of context, ARIA gets misused, focus management gets skipped, color contrast fails silently. They got tired of fighting it and built an agent team that will not let it slide. Now we want to make more magic together.

We want more contributors! If you care about making software accessible to blind and low vision users, please consider submitting a PR. Every improvement to these agents helps developers ship more inclusive software for the people who need it most.

Support Hub

For troubleshooting, Q&A, and community support across workshop and agent ecosystems, use the Community Access support repository:

• Home: https://github.com/Community-Access/support
• Discussions: https://github.com/Community-Access/support/discussions
• Issues: https://github.com/Community-Access/support/issues

Related repositories:

• Workshop curriculum: https://github.com/Community-Access/git-going-with-github
• Accessibility Agents source: https://github.com/Community-Access/accessibility-agents

---

The Problem

AI coding tools generate inaccessible code by default. They forget ARIA rules, skip keyboard navigation, ignore contrast ratios, and produce modals that trap screen reader users. Even with skills and CLAUDE.md instructions, accessibility context gets deprioritized or dropped entirely.

The Solution

Accessibility Agents provides seventy-nine specialized agents across eight teams and five platforms:

• Web Accessibility team - agents that enforce WCAG AA standards for web code, including i18n/RTL, WCAG AAA coverage, data visualization, email, media, web components, and performance accessibility
• Document Accessibility team - agents for Office (DOCX, XLSX, PPTX), PDF, EPUB, and Markdown accessibility scanning and remediation
• GitHub Workflow team - twenty agents that manage repositories, triage issues, review PRs, manage project boards, CI/CD workflows, security alerts, releases, notifications, and wiki pages
• Developer Tools team - agents for Python, wxPython, desktop accessibility, NVDA addon development, and accessibility tool building
• Education & Standards - screen reader simulation, WCAG 3.0 preview, WCAG AAA auditing
• Cross-cutting - CI/CD accessibility pipelines, compliance mapping, accessibility statements, regression detection, and orchestrators that route work across teams

All agents run on:

• Claude Code - Agents you invoke directly for accessibility evaluation
• GitHub Copilot (VS Code and CLI) - Agents + workspace instructions that ensure accessibility guidance in every conversation
• Gemini CLI - Skills-based extension with always-on WCAG AA context via GEMINI.md
• Codex CLI - Native Codex plugin with small router skills, custom subagents, lazy specialist references, and extension-aware dispatch
• MCP Server - HTTP-based server providing 24 accessibility scanning tools to any MCP-compatible client (Claude Desktop, VS Code, CI/CD pipelines)

System Requirements

CRITICAL: To remain current with Accessibility Agents and ensure proper functionality, you must keep all tools updated to their latest versions. New platform capabilities, API changes, accessibility features, and bug fixes directly impact agent behavior.

Required Tools (Latest Versions)

For GitHub Copilot (VS Code):

• VS Code: Latest stable release and/or VS Code Insiders (Download)
• GitHub Copilot Extension: Latest version from VS Code Marketplace
• GitHub Copilot Chat Extension: Latest version from VS Code Marketplace
• Node.js: v18.0.0 or higher (for CLI tools like axe-core)

For Claude Code:

• Claude Code CLI: Latest version (Installation)
• Claude Subscription: Pro, Max, or Team plan

For Gemini CLI:

• Gemini CLI: Latest version (Installation)
• Google AI Studio API Key: Active key (Get Started)

Operating Systems:

• macOS: 10.15 (Catalina) or later
• Windows: Windows 10/11 with PowerShell 5.1+ (pre-installed)

Why Version Currency Matters

1. Platform API Changes - VS Code Copilot, Claude Code, and other platforms add new capabilities (tool use, context windows, model selection) that agents rely on
2. Accessibility Features - New platform features directly improve agent effectiveness (browser tools, screenshot analysis, DOM inspection)
3. Bug Fixes - Critical fixes for tool invocation, context handling, and agent orchestration
4. Security Updates - Important security patches for API access, authentication, and data handling
5. WCAG Evolution - As standards evolve (WCAG 2.2, 3.0), agents update to reflect current best practices

Keeping Tools Updated

Automatic Updates (Recommended):

# Update the skill itself
gh extension upgrade gh-skill

# Pull latest repository changes when working from source
cd accessibility-agents
git pull origin main

Manual Updates:

# Update Accessibility Agents
cd accessibility-agents
git pull origin main

# Update VS Code
# Help → Check for Updates (or auto-updates if enabled in settings)

# Update GitHub Copilot Extensions
# Extensions → @installed → Click update icon next to GitHub Copilot extensions

# Update Claude Code CLI
claude code update

# Update Node.js tools
npm update -g @axe-core/cli
npm update -g pa11y

Version Checks:

# Check current versions
code --version                    # VS Code
claude code --version            # Claude Code CLI
node --version                   # Node.js
npm list -g --depth=0            # Global npm packages

Compatibility Note

Accessibility Agents are tested against the latest stable releases of all supported platforms. While older versions may work, we cannot guarantee compatibility or support issues arising from outdated tooling. If you encounter unexpected behavior, update all tools before reporting issues.

VS Code 1.113 Highlights

VS Code 1.113 is currently the most relevant baseline for GitHub Copilot users of this repo. The release added several changes that improve Accessibility Agents workflows directly:

• MCP across agent types - MCP servers configured in VS Code now bridge into Copilot CLI and Claude agents, which makes this repo's MCP guidance more consistent across local, CLI, and Claude workflows.
• Chat Customizations editor - Chat: Open Chat Customizations gives you one place to inspect and manage instructions, prompt files, agents, skills, MCP servers, and plugins.
• Broader Agent Debug coverage - Agent Debug Logs now cover Copilot CLI and Claude agent sessions in addition to local sessions.
• Integrated browser improvements - local HTTPS testing with self-signed certificates is easier, and browser tab management is better for accessibility testing workflows.
• Nested subagents - VS Code now supports nested subagent delegation. For this repo, that is treated as an optional platform capability, not a default architecture choice. We favor explicit coordinator-worker flows and keep nested subagents disabled by default.

Subagent stance for this repo:

• Reward: bounded subagents improve specialization, parallel analysis, and audit structure.
• Risk: unrestricted or nested subagents can increase duplicate findings, wrong-agent selection, token cost, and debugging complexity.
• Recommendation: use explicit, allowlisted specialist delegation; avoid recursive subagent chains unless a workflow is intentionally designed for them.

For official details, see the VS Code 1.113 release notes: https://code.visualstudio.com/updates/v1_113.

Authoritative Sources and Currency

This project bases platform-specific guidance on official vendor documentation and release notes, not secondary summaries.

Primary references:

• VS Code release notes: https://code.visualstudio.com/updates
• VS Code Copilot customization docs: https://code.visualstudio.com/docs/copilot/customization/custom-instructions
• VS Code custom agents docs: https://code.visualstudio.com/docs/copilot/customization/custom-agents
• VS Code prompt files docs: https://code.visualstudio.com/docs/copilot/customization/prompt-files
• GitHub Copilot product docs: https://docs.github.com/copilot

Attribution policy:

• Platform claims in this repo should cite at least one official source link.
• New behavior tied to a specific release should include the release note URL.
• When settings keys are documented, link to the official settings/docs page where possible.

Optional Customization

GitHub Skills Rollout Guides

For the GitHub Skills specification rollout and release-readiness workflows, see:

• docs/guides/GITHUB-SKILLS-CLI-READINESS.md
• docs/guides/SKILLS-RELEASE-READINESS-TEST-PLAN.md
• .github/workflows/skills-cli-readiness.yml
• .github/workflows/skills-release-readiness.yml

VS Code 1.113 Workflow Tips

If you are using Accessibility Agents in VS Code 1.113, these settings and commands are the most useful starting point:

{
  "chat.useCustomizationsInParentRepositories": true,
  "github.copilot.chat.agentDebugLog.enabled": true,
  "github.copilot.chat.agentDebugLog.fileLogging.enabled": true,
  "chat.imageSupport.enabled": true
}

• Run Chat: Open Chat Customizations to inspect loaded instructions, agents, skills, MCP servers, and plugins.
• Use /troubleshoot when a customization is not loading or an expected tool is missing.
• Keep chat.subagents.allowInvocationsFromSubagents disabled unless you are intentionally experimenting with recursive orchestration patterns.

That last point is a repo recommendation, not a VS Code limitation.

Custom Thinking Phrases (VS Code 1.110+)

VS Code users: Personalize the loading text that appears while agents think with accessibility-themed phrases.

Add to VS Code Settings (settings.json):

{
  "chat.agent.thinking.phrases": {
    "mode": "append",  // Adds to default phrases
    "phrases": [
      "Checking contrast ratios...",
      "Testing with screen readers...",
      "Verifying keyboard navigation...",
      "Reviewing ARIA patterns...",
      "Scanning for accessibility barriers...",
      "Consulting WCAG 2.2..."
    ]
  }
}

Options:

• "mode": "append" - Adds your phrases to VS Code's default list (recommended)