Repository navigation
Troubleshooting
Problems people hit with Accessibility Agents 7.x, grouped by symptom. For the Copilot CLI specifically, see Copilot CLI troubleshooting.
Check the install path against what your client reads.
| Client | Where the skills must be |
|---|---|
| Claude Code | the installed plugin (/plugin install accessibility-agents@community-access), or claude --plugin-dir <checkout>. Claude Code does not read ~/.agents/skills
|
| Codex, Copilot CLI, VS Code, Gemini CLI |
~/.agents/skills (written by npm run setup), or .agents/skills in the workspace (node scripts/dev-link.mjs in a checkout) |
| VS Code, plugin route | Chat: Install Plugin From Source, with chat.plugins.enabled on |
| Antigravity |
~/.gemini/config/skills (written by npm run setup when Antigravity is present), or .agents/skills in the workspace |
A root skills/ folder in a repository you open is not discovered by any of
these clients on its own. A GitHub Codespace on this repository is the
exception in practice: its dev container runs npm run setup on first start,
which copies the skills to ~/.agents/skills.
That is intended. Six routers are model-invocable. 57 specialists are in the
/ menu by name (for example /aria-specialist), and the 45 reference and
helper skills set user-invocable: false, so they appear in no menu; a router
dispatches them.
npm run verify:spec # Agent Skills frontmatter, every skill
npm run verify:conformance # name matches folder, no byte-order mark
npm run verify:skills # package rules: tiers, body size, linksThe gate is working. Dispatch accessibility-lead (describe the change, or
type /accessibility-lead), let it finish, then retry the edit. Build output,
tests, stories and dependencies are exempt. See Hooks.
- Claude Code: the plugin's
hooks/hooks.jsonopens the gate onPostToolUsefor the Skill tool and onSubagentStop, when the skill named isaccessibility-leadorweb-accessibility-wizard. Use the plugin orclaude --plugin-dir <checkout>. If an older installer left~/.claude/a11y-hooks.jsonand you merged it into your settings, remove those entries: on their own they refuse UI edits whenever the skills are not loaded.npm run setup -- --uninstalldeletes the old file. - Codex: the gate opens when Codex reads
accessibility-lead/SKILL.md(orweb-accessibility-wizard/SKILL.md) with a shell command, when the prompt names$accessibility-leador$web-accessibility-wizard, or when a lead subagent stops. This needs the~/.codex/hooks.jsonthatnpm run setupwrites; the Codex plugin route loads no hooks. If setup wrotehooks.a11y.jsonbeside your own file, merge itshooksblock in, including thePostToolUseentry. - Copilot: the gate opens on
postToolUseafter the lead runs. The plugin wires this throughcom.github.copilot/hooks/hooks.json. - Gemini CLI: the gate opens on
AfterToolforactivate_skill, when the skill activated isaccessibility-leadorweb-accessibility-wizard. If you merged an older~/.gemini/a11y-hooks.jsoninto~/.gemini/settings.json, its mark entry usedAfterAgentand never opened the gate: re-runnpm run setupand merge the new entry, or install the extension. - Antigravity: the gate opens when Antigravity reads
accessibility-lead/SKILL.md(orweb-accessibility-wizard/SKILL.md) withview_file. Check that~/.gemini/config/hooks.jsonholds thea11y-*entries; ifnpm run setupwrotehooks.a11y.jsonbeside an existing file, merge them in. This route is tested against the payloads Antigravity documents, not yet in a live Antigravity session.
To test the guard by hand, see "Testing a manifest by hand" in Hooks.
The plugins and .vscode/mcp.json launch mcp-server/dist/stdio.mjs,
which needs no npm install. Run it directly to see any error:
node mcp-server/dist/stdio.mjs # the stdio server the plugins launch
npm install --prefix mcp-server # only for the HTTP server or the unbundled source
node mcp-server/server.js # Streamable HTTP on 127.0.0.1:3100Common errors:
-
ERR_MODULE_NOT_FOUNDfromserver.jsorstdio.js: the source needs its dependencies; run the install above, or use the bundle -
EADDRINUSE: port 3100 is in use; setPORTto a free port - a Node.js version error: use an LTS release (26, 24 or 22)
You may see errors similar to these:
- Cannot find module
playwright-core/lib/cli/program - Cannot find package
playwright-coreimported fromnode_modules/playwright/index.mjs
This usually means npm finished with a partial dependency graph.
playwright brings playwright-core with it, so reinstall it. From
mcp-server/:
cd mcp-server
npm install playwright @axe-core/playwright
npx playwright install chromiumThen verify Chromium resolution, still in mcp-server/:
node -e "import('playwright').then(async ({ chromium }) => { const fs = await import('node:fs'); const exe = chromium.executablePath(); console.log(exe); console.log(fs.existsSync(exe)); }).catch((e) => { console.error(e.message); process.exit(1); })"Expected output ends with true on the second line.
VS Code reads MCP servers from .vscode/mcp.json in the workspace (key
servers) or from the user configuration (MCP: Open User Configuration).
This repository's own .vscode/mcp.json registers the bundle, so a checkout or
codespace of it lists the server. The root mcp.json is the Agent Plugins file,
read only when the repository is installed as a plugin. In another workspace,
add:
{
"servers": {
"a11y-agent-team": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/mcp-server/dist/stdio.mjs"]
}
}
}Then run MCP: List Servers to see its status. If VS Code asked whether to trust the server and you declined, start it again from that list.
Run npm run probe:mcp from the repository root. It connects a real client
and lists the 39 tools. If a Playwright or veraPDF tool reports that its
dependency is missing, install the optional dependency named in
the MCP server README.
npm run verify # every gate
npm run verify:live # what an installed client actually loads- Getting Started: first-time setup
- Configuration: scan configs, preferences, client settings
- Hooks: the enforcement gate
- GitHub Repository Issues: report bugs
- CHANGELOG: what is new in each version, and known issues
- Agents Overview
- Accessibility Lead
- Web Accessibility Wizard
- Document Accessibility Wizard
- Markdown Assistant
- Developer Hub
- GitHub Hub