Repository navigation
Getting Started
This guide covers installation and setup for all three platforms: Claude Code, GitHub Copilot, and Claude Desktop.
This is for the Claude Code CLI (the terminal tool). If you want the Claude Desktop app extension, skip to Claude Desktop Setup below.
A UserPromptSubmit hook fires on every prompt you send to Claude Code. If the task involves web UI code, the hook instructs Claude to delegate to the accessibility-lead first. The lead evaluates the task and invokes the relevant specialists. The specialists apply their focused expertise and report findings. Code does not proceed without passing review.
The team includes twenty-two agents: nine web code specialists that write and review code, six document accessibility specialists that scan Office and PDF files, one document accessibility wizard that runs guided document audits (with two hidden helper sub-agents for parallel scanning), one orchestrator that coordinates them, one interactive wizard that runs guided web audits (with two hidden helper sub-agents for page crawling and parallel scanning), one testing coach that teaches you how to verify accessibility, and one WCAG guide that explains the standards themselves. Three reusable agent skills provide domain knowledge, and lifecycle hooks enforce quality gates at the start and end of each session.
For tasks that do not involve UI code (backend logic, scripts, database work), the hook is ignored and Claude proceeds normally.
- Claude Code CLI installed and working
- A Claude Code subscription (Pro, Max, or Team)
- macOS/Linux: bash shell (pre-installed)
- Windows: PowerShell 5.1+ (pre-installed on Windows 10/11)
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/taylorarndt/a11y-agent-team/main/install.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/taylorarndt/a11y-agent-team/main/install.ps1 | iexThe installer downloads the repo, copies agents and hooks, configures settings.json, and optionally sets up daily auto-updates and GitHub Copilot agents. It will prompt you to choose project-level or global install.
Non-interactive one-liners:
# macOS/Linux — install globally, no prompts
curl -fsSL https://raw.githubusercontent.com/taylorarndt/a11y-agent-team/main/install.sh | bash -s -- --global
# macOS/Linux — install to current project, no prompts
curl -fsSL https://raw.githubusercontent.com/taylorarndt/a11y-agent-team/main/install.sh | bash -s -- --project
# macOS/Linux — install globally with Copilot agents
curl -fsSL https://raw.githubusercontent.com/taylorarndt/a11y-agent-team/main/install.sh | bash -s -- --global --copilotIf you prefer to clone first:
macOS / Linux:
git clone https://github.com/taylorarndt/a11y-agent-team.git
cd a11y-agent-team
bash install.shPass flags to skip prompts: --global, --project, --copilot.
Windows (PowerShell):
git clone https://github.com/taylorarndt/a11y-agent-team.git
cd a11y-agent-team
powershell -ExecutionPolicy Bypass -File install.ps1The --copilot flag installs the accessibility agents for GitHub Copilot Chat. For global installs, this copies .agent.md files directly into your VS Code user profile so the agents appear in the Copilot Chat agent picker across all workspaces. For project installs, it copies them into the project's .github/agents/ directory.
To remove:
bash uninstall.sh
bash uninstall.sh --global # Non-interactive global uninstall
bash uninstall.sh --project # Non-interactive project uninstallpowershell -ExecutionPolicy Bypass -File uninstall.ps1If you prefer to install manually or need to integrate into an existing configuration:
1. Copy agents
# For project install
mkdir -p .claude/agents
cp -r path/to/a11y-agent-team/.claude/agents/*.md .claude/agents/
# For global install
mkdir -p ~/.claude/agents
cp -r path/to/a11y-agent-team/.claude/agents/*.md ~/.claude/agents/2. Copy the hook
macOS/Linux:
# For project install
mkdir -p .claude/hooks
cp path/to/a11y-agent-team/.claude/hooks/a11y-team-eval.sh .claude/hooks/
chmod +x .claude/hooks/a11y-team-eval.sh
# For global install
mkdir -p ~/.claude/hooks
cp path/to/a11y-agent-team/.claude/hooks/a11y-team-eval.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/a11y-team-eval.shWindows:
# For project install
New-Item -ItemType Directory -Force -Path .claude\hooks
Copy-Item path\to\a11y-agent-team\.claude\hooks\a11y-team-eval.ps1 .claude\hooks\
# For global install
New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.claude\hooks
Copy-Item path\to\a11y-agent-team\.claude\hooks\a11y-team-eval.ps1 $env:USERPROFILE\.claude\hooks\3. Add the hook to settings.json
Merge the hook configuration into your .claude/settings.json (project) or ~/.claude/settings.json (global):
macOS/Linux:
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": ".claude/hooks/a11y-team-eval.sh"
}
]
}
]
}
}For global install, use the absolute path:
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "/Users/yourname/.claude/hooks/a11y-team-eval.sh"
}
]
}
]
}
}Windows:
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "powershell -File '.claude\\hooks\\a11y-team-eval.ps1'"
}
]
}
]
}
}If you already have hooks configured, add the UserPromptSubmit entry alongside your existing hooks.
4. Verify
Start Claude Code and type /agents. You should see all agents listed. If they all show up, you are good to go.
Just write code like you normally would. The hook fires on every prompt. If your task involves web UI code, the accessibility-lead activates automatically and brings in the right specialists.
You: Build a login form with email and password fields
Claude: [Hook fires, accessibility-lead activates]
[accessibility-lead invokes aria-specialist, keyboard-navigator, contrast-master]
The login form includes:
- Labeled inputs with <label> elements and matching for attributes
- Error messages linked via aria-describedby
- Focus moves to first error on invalid submit
- Submit button is a <button type="submit">
- Contrast ratios verified for all text
...
For tasks that do not involve UI code, Claude proceeds normally.
You can invoke any agent by name using the slash command or @ mention:
/accessibility-lead full audit of the checkout flow
/aria-specialist review the ARIA in components/modal.tsx
/contrast-master check all color combinations in globals.css
/keyboard-navigator audit tab order on the settings page
/web-accessibility-wizard run a full guided accessibility audit
/document-accessibility-wizard audit all documents in the docs/ folder
/testing-coach how do I test this modal with NVDA?
/wcag-guide explain WCAG 1.4.11 non-text contrast
To see all installed agents at any time, type /agents in Claude Code.
Project-level (recommended for teams): Install to .claude/ in each web project. Check into version control so your whole team benefits. The agents and hook travel with the repo.
Global (recommended for individuals): Install to ~/.claude/ to have the team available across all your projects automatically. Nothing to configure per-project. One install covers everything.
You can use both. Project-level agents override global agents with the same name, so you could customize an agent for a specific project while keeping the defaults globally.
During global installation, the installer asks if you want to enable auto-updates. When enabled, a daily scheduled job checks GitHub for new agent versions and installs them automatically.
-
macOS: Uses a LaunchAgent (
~/Library/LaunchAgents/com.taylorarndt.a11y-agent-team-update.plist), runs daily at 9:00 AM - Linux: Uses a cron job, runs daily at 9:00 AM
-
Windows: Uses Task Scheduler (
A11yAgentTeamUpdate), runs daily at 9:00 AM
Auto-updates keep both Claude Code agents (~/.claude/agents/) and Copilot agents in your VS Code user profile folder in sync.
Update log is saved to ~/.claude/.a11y-agent-team-update.log.
You can also run updates manually at any time:
macOS/Linux:
bash update.shWindows:
powershell -File update.ps1Auto-updates are fully removed when you run the uninstaller.
This is for GitHub Copilot Chat in VS Code (or other editors that support the .github/agents/ format).
GitHub Copilot supports custom agents via .github/agents/*.agent.md files and workspace-level instructions via .github/copilot-instructions.md. The A11y Agent Team provides:
- Twenty-two specialist agents that you can invoke by name in Copilot Chat
- Workspace instructions that remind Copilot to consider accessibility on every UI task
-
PR review instructions (
.github/copilot-review-instructions.md) that enforce accessibility standards during Copilot Code Review on pull requests -
Commit message instructions (
.github/copilot-commit-message-instructions.md) that guide Copilot to include accessibility context in commit messages -
PR template (
.github/PULL_REQUEST_TEMPLATE.md) with an accessibility checklist for every pull request -
CI workflow (
.github/workflows/a11y-check.yml) that runs automated accessibility checks on PRs -
VS Code configuration (
.vscode/) with recommended extensions, settings, tasks, and MCP server config
Unlike Claude Code's hook system, Copilot does not have a pre-prompt hook. Instead, the workspace instructions in .github/copilot-instructions.md are automatically loaded into every Copilot Chat conversation, serving the same purpose.
- GitHub Copilot subscription (Individual, Business, or Enterprise)
- VS Code with the GitHub Copilot extension installed
- Agent mode and custom agents enabled in VS Code settings
The easiest way to get Copilot agents in every workspace.
git clone https://github.com/taylorarndt/a11y-agent-team.git
cd a11y-agent-team
bash install.sh --global --copilotThis installs Copilot agents to your VS Code user profile folder. After installing, reload VS Code and open Copilot Chat. The agents will appear in the agent picker dropdown across all workspaces.
Copy the .github directory into your project so the agents travel with the repo.
git clone https://github.com/taylorarndt/a11y-agent-team.git
cd a11y-agent-team
cp -r .github /path/to/your/project/Or use the installer with the project flag:
cd /path/to/your/project
bash /path/to/a11y-agent-team/install.sh --project --copilotIf you installed globally with --copilot, run a11y-copilot-init inside any project to copy the agents:
cd /path/to/your/project
a11y-copilot-initIn Copilot Chat, mention an agent to invoke it:
@accessibility-lead full audit of the checkout flow
@aria-specialist review the ARIA in components/modal.tsx
@contrast-master check all color combinations in globals.css
@web-accessibility-wizard run a full guided accessibility audit of this project
@document-accessibility-wizard scan all documents in the docs/ folder
@testing-coach how should I test this component with VoiceOver?
@wcag-guide what changed between WCAG 2.1 and 2.2?
The workspace instructions in .github/copilot-instructions.md are loaded into every Copilot Chat conversation. When you ask Copilot to build or modify UI code, it will automatically consider accessibility requirements.
| Feature | Claude Code | GitHub Copilot |
|---|---|---|
| Agent location | .claude/agents/ |
.github/agents/ |
| Hook/instructions |
UserPromptSubmit hook |
.github/copilot-instructions.md |
| PR review | N/A | .github/copilot-review-instructions.md |
| Commit messages | N/A | .github/copilot-commit-message-instructions.md |
| PR template | N/A | .github/PULL_REQUEST_TEMPLATE.md |
| CI workflow | N/A | .github/workflows/a11y-check.yml |
| VS Code config | N/A |
.vscode/ (extensions, settings, tasks, MCP) |
| Invocation |
/agent-name or @agent-name
|
@agent-name |
| Auto-activation | Hook forces evaluation on every prompt | Workspace instructions provide guidance |
| Global install | ~/.claude/agents/ |
VS Code user profile folder or per-project |
This is for the Claude Desktop app (the standalone application).
The .mcpb file (MCP Bundle) is Claude Desktop's extension format. It is a packaged bundle that adds tools and prompts directly into the Claude Desktop interface. You download one file, double-click it, and Claude Desktop installs it.
The A11y Agent Team extension adds:
Tools (Claude can call these automatically while working):
- check_contrast: Calculate WCAG contrast ratios between two hex colors
- get_accessibility_guidelines: Get detailed WCAG AA guidelines for specific component types
- check_heading_structure: Analyze HTML for heading hierarchy issues
- check_link_text: Scan HTML for ambiguous link text
- check_form_labels: Validate form inputs have proper label associations
- generate_vpat: Generate a VPAT 2.5 / Accessibility Conformance Report template
- run_axe_scan: Run axe-core against a live URL and return violations
- scan_office_document: Scan DOCX, XLSX, PPTX files for accessibility issues
- scan_pdf_document: Scan PDFs for PDF/UA conformance
- extract_document_metadata: Extract document properties and metadata
- batch_scan_documents: Scan multiple documents in one operation
Prompts (you select these from the prompt menu):
- Full Accessibility Audit: Comprehensive WCAG 2.1 AA review
- ARIA Review: Focused review of ARIA roles, states, and properties
- Modal/Dialog Review: Focus trapping, focus return, escape behavior
- Color Contrast Review: Color choices checked against AA requirements
- Keyboard Navigation Review: Tab order, focus management, skip links
- Live Region Review: Dynamic content announcements and screen reader compatibility
- Go to the Releases page
- Download the latest
a11y-agent-team.mcpbfile - Double-click the file (or drag it into Claude Desktop)
- Claude Desktop will open an install dialog. Click Install
- Done. The tools and prompts are now available in every conversation
Tools activate automatically. When you ask Claude to review code or build a component, it can call check_contrast and get_accessibility_guidelines on its own.
Prompts are available from the prompt menu. Click the prompt picker (or type /) and you will see the six review prompts listed.
npm install -g @anthropic-ai/mcpb
git clone https://github.com/taylorarndt/a11y-agent-team.git
cd a11y-agent-team/desktop-extension
npm install
mcpb validate .
mcpb pack . ../a11y-agent-team.mcpbThe output file can be double-clicked to install in Claude Desktop.
- Agents Overview
- Accessibility Lead
- Web Accessibility Wizard
- Document Accessibility Wizard
- Markdown Assistant
- Developer Hub
- GitHub Hub