Agents Overview

Agent Reference

This directory contains detailed documentation for every agent in the A11y Agent Team. Each agent has its own page with full usage examples, behavioral constraints, and what it catches.

How Agents Work - The Mental Model

Think of the A11y Agent Team as a consulting team of accessibility specialists. You do not need to know which specialist to call - that is the lead's job. But you can call any specialist directly when you already know what you need.

The Accessibility Lead is your single point of contact. Tell it what you are building or reviewing, and it will figure out which specialists are needed, invoke them, and compile the findings. If you only remember one agent name, remember this one.

The nine code specialists (ARIA Specialist, Modal Specialist, Contrast Master, Keyboard Navigator, Live Region Controller, Forms Specialist, Alt Text & Headings, Tables Specialist, Link Checker) each own one domain of web accessibility. They write code, review code, and report issues within their area. They do not overlap - each has a clear boundary.

The six document specialists (Word Accessibility, Excel Accessibility, PowerPoint Accessibility, office-scan-config, PDF Accessibility, pdf-scan-config) scan Office and PDF documents for accessibility issues.

The Web Accessibility Wizard runs interactive guided web audits. It walks you through your entire project phase by phase, asks questions to understand your context, invokes the right specialists at each step, and produces a prioritized action plan with an accessibility scorecard.

The Document Accessibility Wizard does the same for Office and PDF documents, with cross-document analysis, severity scoring, remediation tracking, and VPAT/ACR compliance export.

The Markdown Accessibility agent audits Markdown documentation files across 9 accessibility domains: links, alt text, headings, tables, emoji, diagrams, em-dashes, anchor links, and plain language. It runs per-file parallel scans via markdown-scanner and applies fixes via markdown-fixer.

The Testing Coach does not write product code. It teaches you how to test what the other agents built.

The WCAG Guide does not write or review code. It explains the Web Content Accessibility Guidelines in plain language.

Invocation Syntax

Expand invocation syntax reference

Claude Code (Terminal)

Method	Syntax	When to Use
Slash command	/accessibility-lead review this page	Direct invocation from the prompt
At-mention	@accessibility-lead review this page	Alternative syntax, same behavior
List agents	/agents	See all installed agents

Codex CLI (Terminal)

Method	Syntax	When to Use
Automatic	Rules apply to every UI task	No invocation needed — Codex reads .codex/AGENTS.md automatically

Codex CLI does not have named agents or sub-agents. All accessibility rules are condensed into a single AGENTS.md file that Codex loads on every run. There is nothing to invoke — the rules are always active.

GitHub Copilot (VS Code / Editor)

Note: Custom agents must first be selected from the agent picker dropdown (the model/agent selector at the top of the Chat panel). After selecting an agent from the picker once, it will appear in @ autocomplete for future use.

Method	Syntax	When to Use
Agent picker	Select from dropdown at top of Chat panel	First-time activation of any custom agent
At-mention in Chat	@Accessibility Lead review this page	Direct invocation after first picker selection
With file context	Select code, then @ARIA Specialist check this	Review selected code
Workspace instructions	Automatic - loaded on every conversation	Ensures accessibility guidance is always present

Web Accessibility Agents

Expand web accessibility agent reference (16 agents)

Agent	Domain	Documentation
Accessibility Lead	Orchestrator - coordinates all specialists	Full docs
ARIA Specialist	ARIA roles, states, properties, widget patterns	Full docs
Modal Specialist	Dialogs, drawers, popovers, overlays	Full docs
Contrast Master	Color contrast, dark mode, visual design	Full docs
Keyboard Navigator	Tab order, focus management, skip links	Full docs
Live Region Controller	Dynamic content, toasts, loading states	Full docs
Forms Specialist	Forms, labels, validation, errors	Full docs
Alt Text & Headings	Alt text, SVGs, headings, landmarks	Full docs
Tables Specialist	Data tables, grids, sortable columns	Full docs
Link Checker	Ambiguous link text detection	Full docs
Web Accessibility Wizard	Guided web accessibility audit	Full docs
web-csv-reporter	CSV export with Deque University help links (hidden - invoked by orchestrator)	Full docs
scanner-bridge	Bridges GitHub Accessibility Scanner CI data into agent ecosystem (hidden - invoked by orchestrator)	Full docs
lighthouse-bridge	Bridges Lighthouse CI accessibility audit data into agent ecosystem (hidden - invoked by orchestrator)	Full docs
Cognitive Accessibility	Cognitive accessibility, plain language, COGA, WCAG 2.2 new criteria	Full docs
Mobile Accessibility	React Native, iOS/Android accessibility, touch targets	Full docs
Design System Auditor	Design token contrast, focus ring compliance, Tailwind/MUI/shadcn audits	Full docs
Testing Coach	Screen reader and keyboard testing	Full docs
WCAG Guide	WCAG 2.2 criteria reference	Full docs

Document Accessibility Agents

Expand document accessibility agent reference (9 agents)

Agent	Domain	Documentation
Word Accessibility	Word (DOCX) scanning	Full docs
Excel Accessibility	Excel (XLSX) scanning	Full docs
PowerPoint Accessibility	PowerPoint (PPTX) scanning	Full docs
office-scan-config	Office scan configuration	Full docs
PDF Accessibility	PDF scanning (PDF/UA)	Full docs
pdf-scan-config	PDF scan configuration	Full docs
ePub Accessibility	ePub (EPUB 2/3) scanning	Full docs
epub-scan-config	ePub scan configuration	Full docs
Document Accessibility Wizard	Guided document audit	Full docs
document-csv-reporter	CSV export with Microsoft Office and Adobe PDF help links (hidden - invoked by orchestrator)	Full docs

Markdown Accessibility Agents

Expand markdown accessibility agent reference (3 agents)

Agent	Domain	Documentation
Markdown Accessibility	Orchestrator — links, alt text, headings, tables, emoji, diagrams, em-dashes, anchors	Full docs
markdown-scanner	Per-file parallel scanning across all 9 domains (hidden — invoked by orchestrator)	Internal
markdown-fixer	Applies auto-fixes and presents human-judgment items (hidden — invoked by orchestrator)	Internal
markdown-csv-reporter	Exports findings to CSV with WCAG help links and markdownlint rule references (hidden — invoked by orchestrator)	Full docs

GitHub Workflow Agents

These agents manage your GitHub repositories, pull requests, issues, and team - the "operating system" layer of a healthy software project. They live alongside the accessibility team but handle an entirely different job: keeping your GitHub world organized, actionable, and fast to navigate.

The Mental Model

GitHub Hub is your single entry point. You never need to know which agent to call. Just describe what you want - "review the PR from this morning," "who's waiting on me?" "onboard our new developer" - and GitHub Hub figures out the rest, asks any clarifying questions intelligently, and routes you to the right specialist with context already loaded.

The ten specialist agents each own a vertical slice of GitHub operations:

• Daily Briefing owns the morning picture - what happened, what needs action
• PR Review owns code review - diffs, comments, merge decisions
• Issue Tracker owns issue work - triage, response, management
• Analytics & Insights owns data - velocity, bottlenecks, health scores
• Accessibility Tracker owns accessibility change tracking - VS Code + your repos
• Repo Admin owns access control - who can do what, branch protection, settings
• Team Manager owns people - onboarding, offboarding, org teams
• Contributions Hub owns community - discussions, health, contributor relationships
• Template Builder owns GitHub templates - issue/PR/discussion templates via guided wizard
• Repo Manager owns repo scaffolding - CI, labels, CONTRIBUTING, SECURITY, README

Invocation

Platform	Syntax
GitHub Copilot (VS Code)	@GitHub Hub what needs my attention today?
GitHub Copilot (VS Code)	@Daily Briefing morning briefing
Claude Code (Terminal)	/github-hub show my open PRs
Claude Code (Terminal)	/pr-review owner/repo#42

You can invoke any agent directly if you know exactly what you need. Or start at @github-hub and let it route you.

When to Use GitHub Workflow Agents vs. Accessibility Agents

Expand decision guide

You want to...	Use
Review a PR's accessibility	@PR Review + @Accessibility Lead
Track a accessibility bug across issues and PRs	@Issue Tracker
Onboard a new developer to the team	@Team Manager
Get a morning status of all open work	@Daily Briefing
Audit who has access to your repos	@Repo Admin
Write a great issue template for a11y bugs	@Template Builder
See velocity metrics and bottlenecks	@Analytics & Insights
Track VS Code a11y changes for the month	@Accessibility Tracker

GitHub Workflow Agent Reference

Expand GitHub workflow agent reference (11 agents)

Agent	Role	Documentation
github-hub	Orchestrator - routes GitHub tasks from plain English	Full docs
daily-briefing	Morning overview of issues, PRs, CI, and security alerts	Full docs
pr-review	PR diff analysis, commenting, confidence levels, delta tracking	Full docs
issue-tracker	Issue triage, priority scoring, response, management	Full docs
analytics	Repo health scoring, velocity, bottleneck detection	Full docs
insiders-a11y-tracker	Track accessibility changes with WCAG mapping and delta reports	Full docs
repo-admin	Collaborator access, branch protection, label sync	Full docs
team-manager	Onboarding, offboarding, org team membership	Full docs
contributions-hub	Discussions, community health, first-time contributors	Full docs
template-builder	Guided wizard for issue/PR/discussion template creation	Full docs
repo-manager	Repo scaffolding - CI, labels, contributing guides, SECURITY	Full docs

---

Parallel Agentic Flow

Multi-agent workflows run parallel execution to minimize wait time. Knowing the model helps you understand why responses arrive in bursts.

Web Accessibility Parallel Groups

When web-accessibility-wizard runs a full audit, specialists execute in three simultaneous groups:

Group	Agents Running in Parallel
Group 1	aria-specialist + keyboard-navigator + forms-specialist
Group 2	contrast-master + alt-text-headings + link-checker
Group 3	modal-specialist + live-region-controller + tables-data-specialist

All three groups run simultaneously. cross-page-analyzer then synthesizes results across groups. This is why a full web audit produces all findings at once rather than one specialist at a time.

Document Accessibility Parallel Groups

When document-accessibility-wizard scans a folder, it distributes by type:

Type	Agent
.docx files	word-accessibility
.xlsx files	excel-accessibility
.pptx files	powerpoint-accessibility
.pdf files	pdf-accessibility
.epub files	epub-accessibility

All four type-specialist streams run simultaneously. cross-document-analyzer then runs cross-document pattern detection after all scans complete.

Markdown Accessibility Parallel Groups

When markdown-a11y-assistant runs an audit, it dispatches markdown-scanner for each file simultaneously:

What Runs in Parallel	Details
Per-file markdown-scanner calls	One scanner per .md file, all running concurrently
9 domain checks per file	Links, alt text, headings, tables, emoji, diagrams, em-dashes, anchors, plain language

markdown-fixer then runs sequentially by file, applying auto-fixable items and surfacing human-judgment items for review.

GitHub Workflow Parallel Streams

daily-briefing runs Batch 1 streams simultaneously:

Stream	Agent Function
Issues	Open issues, @mentions, triage queue
PRs	Review requests, authored PRs, CI status
Security/CI	Dependabot alerts, failing checks
A11y	Latest VS Code Insiders accessibility commits

analytics collects its 5 data streams in parallel: PR metrics, issue metrics, contribution activity, code churn, and bottleneck detection.

Progress Announcements

Every long-running agent operation narrates its steps aloud. The pattern is universal across all agent teams:

 Starting [operation]…
 Complete - [N items] found

You will always know what is happening and when each phase finishes. This is required behavior - no agent silently collects data.

---

Skills Reference

Skills are reusable knowledge modules loaded by agents at runtime. Each skill defines domain rules, scoring formulas, or scanning patterns that multiple agents share.

Skill	Domain	Used By
accessibility-rules	WCAG rule IDs for DOCX, XLSX, PPTX, PDF, EPUB	document-accessibility-wizard, word-accessibility, excel-accessibility, powerpoint-accessibility, pdf-accessibility, epub-accessibility, cross-document-analyzer
document-scanning	File discovery, delta detection, scan profiles	document-accessibility-wizard, document-inventory
report-generation	Severity scoring formulas (0-100/A-F), VPAT/ACR export, scorecard format	document-accessibility-wizard, cross-document-analyzer
web-scanning	Web content discovery, URL crawling, axe-core CLI	web-accessibility-wizard, cross-page-analyzer
web-severity-scoring	Web severity 0-100 scores, confidence levels, delta tracking	web-accessibility-wizard, cross-page-analyzer, accessibility-lead
framework-accessibility	React, Vue, Angular, Svelte, Tailwind fix templates	accessibility-lead, aria-specialist, forms-specialist, keyboard-navigator
cognitive-accessibility	WCAG 2.2 cognitive SC, COGA guidance, plain language, reading level, auth patterns	cognitive-accessibility, web-accessibility-wizard, accessibility-lead, forms-specialist
mobile-accessibility	React Native prop reference, iOS/Android accessibility, touch targets	mobile-accessibility
design-system	Design token contrast formulas, WCAG 2.4.13 focus ring, framework token paths	design-system-auditor, contrast-master
github-workflow-standards	Auth, dual MD+HTML output, HTML accessibility, safety rules, parallel execution	github-hub, daily-briefing, issue-tracker, pr-review, analytics, repo-admin, team-manager, contributions-hub, insiders-a11y-tracker, repo-manager, template-builder
github-scanning	Search query construction, date ranges, cross-repo parallel streams, auto-recovery	github-hub, daily-briefing, issue-tracker, pr-review, analytics, insiders-a11y-tracker
github-analytics-scoring	Repo health 0-100/A-F, priority scoring, bottleneck detection, velocity metrics	daily-briefing, issue-tracker, pr-review, analytics, repo-admin, insiders-a11y-tracker
markdown-accessibility	Ambiguous link/anchor patterns, emoji handling (remove/translate), Mermaid/ASCII diagram replacement, heading rules, severity scoring	markdown-a11y-assistant, markdown-scanner, markdown-fixer
help-url-reference	Deque University, Microsoft Office, Adobe PDF, and WCAG Understanding document URL mappings	web-csv-reporter, document-csv-reporter
github-a11y-scanner	GitHub Accessibility Scanner detection, issue parsing, severity mapping, axe-core correlation, Copilot fix tracking	scanner-bridge, web-accessibility-wizard, insiders-a11y-tracker, daily-briefing, issue-tracker
lighthouse-scanner	Lighthouse CI accessibility audit detection, score interpretation, weight-to-severity mapping, score regression tracking	lighthouse-bridge, web-accessibility-wizard, insiders-a11y-tracker, daily-briefing, issue-tracker

---

Agent Tool Reference

Every agent declares which tools it can use in its YAML frontmatter. This determines what capabilities each agent has at runtime - whether it can read files, edit code, run terminal commands, invoke sub-agents, or interact with GitHub APIs.

Tool Glossary

Tool Name	What It Does
read / readFile	Read file contents from the workspace
search / textSearch	Search for text patterns across the workspace
fileSearch	Search for files by name or glob pattern
edit / editFiles	Modify existing files in the workspace
createFile	Create new files
createDirectory	Create new directories
listDirectory	List directory contents
runInTerminal / getTerminalOutput	Execute terminal commands and read output
runSubagent / agent	Invoke sub-agents for delegation
askQuestions / ask_questions	Prompt the user for clarification or input
fetch	Fetch content from URLs
codebase	Semantic search across the codebase
github/*	GitHub API operations (issues, PRs, repos, teams, etc.)

Web Accessibility Specialists

Expand tool matrix (15 agents)

Agent	read	search	edit	terminal	askQuestions	subagent
accessibility-lead	yes	yes	yes	yes	yes	yes
alt-text-headings	yes	yes	yes	yes	yes	--
aria-specialist	yes	yes	yes	yes	yes	--
cognitive-accessibility	yes	yes	yes	yes	yes	--
contrast-master	yes	yes	yes	yes	yes	--
design-system-auditor	--	--	--	--	--	--
forms-specialist	yes	yes	yes	yes	yes	--
keyboard-navigator	yes	yes	yes	yes	yes	--
link-checker	yes	yes	yes	--	yes	--
live-region-controller	yes	yes	yes	yes	yes	--
mobile-accessibility	yes	yes	yes	yes	yes	--
modal-specialist	yes	yes	yes	yes	yes	--
tables-data-specialist	yes	yes	yes	yes	yes	--
testing-coach	yes	yes	--	yes	yes	--
wcag-guide	yes	yes	--	--	yes	--

Notes:

• accessibility-lead is the only web specialist with runSubagent - it orchestrates the others.
• testing-coach has no edit - it teaches testing techniques but does not write product code.
• wcag-guide has no edit or runInTerminal - it is a pure reference agent.
• link-checker has no runInTerminal - it works by reading and searching source files only.
• design-system-auditor has no tools declared in frontmatter (likely an omission - it references askQuestions in its body).

Web Audit Orchestrators and Helpers

Expand tool matrix (4 agents)

Agent	read	search	edit	terminal	askQuestions	subagent	fetch	fileSearch	listDir	createFile
web-accessibility-wizard	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
cross-page-analyzer	yes	yes	--	--	--	--	--	--	--	--
web-issue-fixer	yes	yes	yes	yes	--	--	--	--	--	--
web-csv-reporter	yes	yes	yes	--	--	--	--	--	--	--

Notes:

• web-accessibility-wizard has the widest tool set of any accessibility agent - it needs full workspace access for guided audits.
• cross-page-analyzer is read-only - it synthesizes data but never modifies files.
• Internal helpers (user-invokable: false) are marked in the agent listing tables above.

Document Accessibility Specialists

Expand tool matrix (5 agents)

Agent	read	search	edit	terminal	askQuestions
word-accessibility	yes	yes	yes	yes	yes
excel-accessibility	yes	yes	yes	yes	yes
powerpoint-accessibility	yes	yes	yes	yes	yes
pdf-accessibility	yes	yes	yes	yes	yes
epub-accessibility	yes	yes	yes	yes	yes

All five document specialists have identical tool sets.

Document Audit Orchestrators and Helpers

Expand tool matrix (4 agents)

Agent	read	search	edit	terminal	askQuestions	subagent
document-accessibility-wizard	yes	yes	yes	yes	yes	yes
document-inventory	yes	yes	--	yes	--	--
cross-document-analyzer	yes	yes	--	--	--	--
document-csv-reporter	yes	yes	yes	--	--	--

Notes:

• document-inventory needs terminal access for running file discovery commands.
• cross-document-analyzer is read-only, like its web counterpart.

Scan Config Managers

Expand tool matrix (3 agents)

Agent	read	edit	askQuestions
office-scan-config	yes	yes	yes
pdf-scan-config	yes	yes	yes
epub-scan-config	yes	yes	yes

Config managers only need to read and write config files, and ask the user about scan preferences. None have search or runInTerminal.

Markdown Accessibility Agents

Expand tool matrix (4 agents)

Agent	read	search	edit	terminal	askQuestions	subagent	fileSearch	listDir	createFile
markdown-a11y-assistant	yes	yes	yes	yes	yes	yes	yes	yes	yes
markdown-scanner	yes	--	--	yes	--	--	--	--	--
markdown-fixer	yes	--	yes	yes	--	--	--	--	--
markdown-csv-reporter	yes	yes	yes	--	--	--	--	--	--

Notes:

• markdown-scanner is read-only plus terminal (for running lint checks).
• markdown-fixer can edit files but cannot search - it receives file paths from the orchestrator.

GitHub Workflow Agents

Expand tool matrix (12 agents)

Agent	github	read	search	edit	terminal	askQuestions	fetch	codebase	fileSearch	listDir	createFile	createDir
nexus	yes	yes	--	yes	--	yes	yes	--	--	yes	yes	yes
github-hub	yes	yes	--	yes	--	yes	yes	--	--	yes	yes	yes
daily-briefing	yes	yes	yes	yes	yes	yes	yes	yes	--	yes	yes	yes
issue-tracker	yes	yes	yes	yes	yes	yes	yes	yes	--	yes	yes	yes
pr-review	yes	yes	yes	yes	yes	yes	yes	yes	--	yes	yes	yes
analytics	yes	yes	yes	yes	yes	yes	yes	yes	--	yes	yes	yes
insiders-a11y-tracker	yes	--	--	yes	--	yes	yes	--	--	yes	yes	yes
contributions-hub	yes	yes	--	yes	--	yes	yes	--	--	yes	yes	yes
repo-admin	yes	yes	--	yes	--	yes	yes	--	--	yes	yes	yes
repo-manager	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
team-manager	yes	yes	--	yes	--	yes	yes	--	--	yes	yes	yes
template-builder	yes	yes	--	yes	--	yes	--	--	--	yes	yes	yes

Notes:

• All GitHub agents have github/* (GitHub API access), createFile, createDirectory, and listDirectory for report output.
• repo-manager has the widest tool set - it needs full workspace access for scaffolding repos.
• nexus and github-hub are functionally identical orchestrators (nexus is the canonical name).
• template-builder is the only GitHub agent without fetch - it works with local template files only.

Sub-Agent Delegation Map

Orchestrator agents delegate work to specialist sub-agents. This map shows which agents each orchestrator can invoke:

Orchestrator	Sub-Agents
accessibility-lead	alt-text-headings, aria-specialist, contrast-master, forms-specialist, keyboard-navigator, link-checker, live-region-controller, modal-specialist, tables-data-specialist
web-accessibility-wizard	alt-text-headings, aria-specialist, contrast-master, cross-page-analyzer, forms-specialist, keyboard-navigator, lighthouse-bridge, link-checker, live-region-controller, modal-specialist, scanner-bridge, tables-data-specialist, testing-coach, wcag-guide, web-csv-reporter, web-issue-fixer
document-accessibility-wizard	cross-document-analyzer, document-csv-reporter, document-inventory, epub-accessibility, excel-accessibility, pdf-accessibility, powerpoint-accessibility, word-accessibility
markdown-a11y-assistant	markdown-csv-reporter, markdown-fixer, markdown-scanner
nexus / github-hub	analytics, contributions-hub, daily-briefing, insiders-a11y-tracker, issue-tracker, pr-review, repo-admin, repo-manager, team-manager, template-builder
daily-briefing	analytics, insiders-a11y-tracker, issue-tracker, pr-review, scanner-bridge, lighthouse-bridge
issue-tracker	daily-briefing, pr-review, scanner-bridge, lighthouse-bridge
pr-review	daily-briefing, issue-tracker
analytics	daily-briefing, issue-tracker, pr-review
repo-manager	github-hub, repo-admin, template-builder

---

Environment Parity

Agents exist in three environments. Claude Code and Copilot have full multi-agent support. Codex CLI uses a single condensed ruleset.

Property	GitHub Copilot	Claude Code	Codex CLI
Agent directory	.github/agents/*.agent.md	.claude/agents/*.md	.codex/AGENTS.md (single file)
Team config	.github/agents/AGENTS.md	.claude/agents/AGENTS.md	N/A
Frontmatter model	model: [Claude Sonnet 4 (copilot)]	model: inherit	N/A
Handoffs declaration	handoffs: block in frontmatter	Described in agent body text	N/A (no sub-agents)
Agent cross-calling	agents: frontmatter list	Agent body text describes delegation	N/A (no sub-agents)
Skills path	../skills/[skill]/SKILL.md	../../.github/skills/[skill]/SKILL.md	N/A
Shared instructions	shared-instructions.md (relative)	../../.github/agents/shared-instructions.md	N/A

Both environments share:

• Identical agent body content (behavioral rules, capabilities, workflows)
• The same 9 .github/skills/ knowledge files
• The same preferences.md format for user configuration
• The same dual .md + .html output requirement
• The same / progress announcement pattern
• The same High / Medium / Low confidence level system
• The same / / / delta tracking notation

---

Tips for Getting the Best Results

Expand tips for effective agent use

Be specific about context. Instead of "review this file," say "review the modal in this file for focus trapping and escape behavior." Specific prompts activate the right specialist knowledge.

Name the component type. Instead of "check this code," say "check this combobox" or "review this sortable data table." Component type maps directly to specialist expertise.

Ask for audits when you want breadth. Use the accessibility-lead for broad reviews. Use individual specialists when you know exactly what domain you are concerned about.

Chain specialists for complex components. A modal with a form inside it? Invoke modal-specialist for the overlay behavior and forms-specialist for the form content. Or just use accessibility-lead and let it coordinate.

Use testing-coach after building. The code specialists help you write correct code. Testing-coach helps you verify it actually works. These are different activities.

Use wcag-guide when debating. If your team disagrees about what WCAG requires, ask wcag-guide. It gives definitive answers with criterion references, not opinions.