arc-skills-deploy

A fully config-driven, cross-platform CLI for deploying accessibility skills and MCP servers across multiple IDEs: Claude Code, Cursor, Codex, VSCode, Windsurf, and Factory.

Add new skills, MCP servers, or entire IDEs without writing code - just edit the JSON config and re-run.

Install

npm install -g arc-skills-deploy
# or
npx arc-skills-deploy@latest

Usage

arc-skills-deploy

Flags

| Flag | Description | |------|-------------| | --skill <name> | Install a single skill by npm package name and prompt to wire its required MCPs. Bypasses the profile selector entirely. | | --local / --global | Skip the scope prompt for skill installation. | | --yes | Auto-confirm all prompts (local scope, all IDEs). | | --uninstall | Remove skills and MCP entries installed by this tool. |

Note: MCP configs are always written globally (AppData/Application Support). The scope flag only affects skills.

Single-Skill Install

Use --skill to install exactly one skill without going through the full profile flow:

# Install the minimal accessibility tester for agent stacks
npx arc-skills-deploy@latest --skill arc-a11y-tester-basic

# Skip all prompts, auto-confirm
npx arc-skills-deploy@latest --skill arc-a11y-tester-basic --yes

# Invalid name → error listing all valid skill names
npx arc-skills-deploy@latest --skill foo

The CLI validates the skill name, prompts for host application selection, then asks whether to install the skill's required MCP servers. Invalid names print an error listing all available skills.

After Installation

Once installation completes, you'll find a comprehensive usage guide in your IDE's skills directory:

• Local install: .claude/skills/a11y/arc-skills-README.md (or .cursor/skills/a11y/, .codex/skills/a11y/ depending on your IDE)
• Global install: ~/.claude/skills/a11y/arc-skills-README.md (or your IDE's global skills directory)

What's in the Guide

The bundled README includes:

• 70+ example prompts organized by complexity level (beginner to advanced)
• Quick reference cheat sheet for common tasks
• Skill descriptions explaining when to use each of the 7 skills
• MCP server guides with verification steps and example queries
• Combined workflows showing how to use skills and MCP servers together
• Complete audit examples using the orchestrator for end-to-end accessibility testing

Preview the Guide

You can preview the guide here: templates/deploy-README.md

Next Steps

1. Open the README in your IDE's skills directory
2. Try the "Getting Started" prompts to verify everything is working
3. Explore the example prompts library to find workflows that match your needs
4. Use the MCP verification section to test all 5 MCP servers

MCP Servers

All MCP servers are configured to run via npx, which means:

• No local installation or cloning required
• Automatically fetches the latest version when needed
• No disk space used for local copies
• Just restart your IDE and the servers will be available

What It Does

This CLI automates the setup of accessibility tooling by:

1. Installing skills from npm - Downloads and installs accessibility skill packages (configurable in config/settings.json)
2. Configuring MCP servers - Updates each IDE's MCP config to enable accessibility-focused MCP servers (also configurable)

Default configuration includes:

• 10 accessibility skills from the arc-a11y-skills npm bundle — testing, remediation, validation, documentation, full audits, and orchestration
• 6 MCP servers (all installed under an arc-a11y- prefix so they group together in your IDE's MCP list):
  • arc-a11y-wcag - WCAG 2.2 guidelines, success criteria, and techniques
  • arc-a11y-aria - WAI-ARIA roles, states, properties, and patterns
  • arc-a11y-magentaa11y - Component accessibility acceptance criteria
  • arc-a11y-personas - Accessibility personas for diverse user needs
  • arc-a11y-issues - Format AxeCore violations into standardized issue templates
  • arc-a11y-playwright - Browser automation for runtime accessibility testing

Fully customizable - add/remove skills, MCP servers, or entire IDEs by editing the config file.

Why This Tool?

Zero Hardcoded Values - Every aspect of the tool is driven by config/settings.json:

• IDE paths and configuration files
• Skills to install
• MCP servers to configure
• Even the IDE list itself

Adding Support for a New IDE takes just 5 lines of JSON:

{
  "id": "new-ide",
  "displayName": "New IDE",
  "mcpServerKey": "servers",
  "skillsFolder": ".new-ide/skills",
  "mcpConfigFile": ".new-ide/mcp.json"
}

Safe by Default - Won't overwrite your existing:

• Custom MCP servers in your IDE configs
• Other skills in your skills directories
• Creates backups if it encounters JSON parsing errors

Skills Installed (Default)

All skills ship from a single npm bundle: arc-a11y-skills. The deploy CLI installs that package once and copies the selected SKILL.md folders into each host application's skills directory. Pick and choose by editing config/settings.json:

| Skill ID | Description | |----------|-------------| | arc-a11y-base-web | Foundational accessibility patterns for web code | | arc-a11y-web-standards | Static HTML/CSS/ARIA analysis without a browser | | arc-a11y-tester-basic | Lightweight axe-core + Playwright tester for agent stacks | | arc-a11y-quick-test | Fast axe-core scan reporting critical and serious violations | | arc-a11y-remediator | Generate accessibility fixes using MCP-informed guidance | | arc-a11y-validator | Verify accessibility fixes against acceptance criteria | | arc-a11y-issue-writer | Format violations into JIRA-ready issue reports | | arc-a11y-orchestrator | Coordinate analysis, remediation, and validation across skills | | arc-a11y-full-audit | Complete audit with static + runtime testing and issue reports | | arc-a11y-full-audit-remediate | Audit then auto-fix all critical and serious issues |

arc-a11y-tester-basic vs arc-a11y-quick-test

Both run axe-core via Playwright, filter to critical + serious violations, and enrich each violation type with MagentaA11y acceptance criteria. They exist for different callers:

• arc-a11y-quick-test — for humans asking "give me a quick a11y check." Friendlier output, knows how to handle local files (spins up a local HTTP server), and finishes with a "next steps" pointer to the full-audit skills. Pick this when you're driving the scan yourself.
• arc-a11y-tester-basic — for other agents or orchestrators calling out for a structured, parseable scan. Stricter output contract (no preamble, no commentary, no recommendations) and ships with its own embedded MCP install instructions so it's portable into agent stacks that don't have the full ARC bundle installed. Pick this when an orchestrator or downstream agent will consume the output.

If you're not sure which to use, start with arc-a11y-quick-test.

No Local MCP Installation Required!

MCP servers are configured to use npx, which means:

• No cloning of MCP server repositories
• No building or npm install steps
• No disk space used for local copies
• Always up-to-date - npx fetches the latest version automatically

The generated MCP config looks like this:

{
  "mcpServers": {
    "arc-a11y-wcag": {
      "command": "npx",
      "args": ["-y", "wcag-guidelines-mcp"]
    },
    "arc-a11y-aria": {
      "command": "npx",
      "args": ["-y", "aria-mcp"]
    }
  }
}

Configuration

The entire tool is fully config-driven. Edit config/settings.json to customize everything without touching code.

Adding a New Skill

Each entry in the skills array describes one skill to deploy. Skills bundled inside a multi-skill npm package share an npmName and use subPath to point at the folder containing their SKILL.md:

{
  "skills": [
    {
      "id": "arc-a11y-tester-basic",
      "name": "Arc A11y Tester (Basic)",
      "npmName": "arc-a11y-skills",
      "subPath": "web/arc-a11y-tester-basic",
      "description": "Lightweight axe-core + Playwright tester for agent stacks",
      "mcpServers": ["arc-a11y-playwright", "arc-a11y-magentaa11y"]
    },
    {
      "id": "your-custom-skill",
      "name": "Your Custom Skill",
      "npmName": "your-custom-skill-package",
      "description": "Your custom skill description",
      "mcpServers": []
    }
  ]
}

Skill entry properties:

• id — Unique identifier used as the installed folder name and in profile/--skill references
• name — Human-readable display name shown in prompts
• npmName — npm package to install
• subPath — Optional. Path inside the package containing SKILL.md (used when one package bundles multiple skills)
• description — Short summary shown in selection menus
• mcpServers — MCP server names this skill depends on (used by --skill to offer matching MCP installs)

Adding a New MCP Server

Add an object to the mcpServers array with name, description, command, and args:

{
  "mcpServers": [
    {
      "name": "arc-a11y-wcag",
      "description": "WCAG guidelines reference",
      "command": "npx",
      "args": ["-y", "wcag-guidelines-mcp"]
    },
    {
      "name": "your-custom-mcp",
      "description": "Your custom MCP server",
      "command": "npx",
      "args": ["-y", "your-mcp-package"]
    }
  ]
}

Adding a New Host Application

Add an object to the hostApplications array with the host application's configuration:

{
  "hostApplications": [
    {
      "id": "windsurf",
      "displayName": "Windsurf",
      "mcpServerKey": "servers",
      "skillsFolder": ".codeium/windsurf/skills",
      "mcpConfigFile": ".codeium/windsurf/mcp_config.json"
    },
    {
      "id": "vscode",
      "displayName": "VSCode",
      "mcpServerKey": "servers",
      "skillsFolder": ".github/skills",
      "mcpConfigFile": "Code/User/mcp.json"
    }
  ]
}

Host Application Configuration Properties:

• id - Unique identifier for the host application
• displayName - Human-readable name shown in prompts
• mcpServerKey - MCP config key name ("servers", "mcpServers", or "mcp_servers" for TOML)
• skillsFolder - Path to skills directory (relative to home/project root)
• mcpConfigFile - Path to MCP config file relative to the chosen base. Supports both JSON (.json) and TOML (.toml) formats. TOML format is auto-detected by file extension (used by Codex).
• mcpConfigBase - Base directory the mcpConfigFile is resolved against. One of:
  • "home" (default) — user's home directory. Use for Claude Code (~/.claude.json), Cursor, Codex, Windsurf, Factory, and most editors that put their config under $HOME.
  • "appSupport" — platform-specific user config directory. Use for editors like VSCode whose config lives under:
    • Windows: %APPDATA% (e.g., C:\Users\name\AppData\Roaming)
    • macOS: ~/Library/Application Support
    • Linux: $XDG_CONFIG_HOME or ~/.config

Note: Codex uses TOML format for its MCP configuration (~/.codex/config.toml), which requires the mcpServerKey to be "mcp_servers" and generates config entries like:

[mcp_servers.arc-a11y-magentaa11y]
command = "npx"
args = ["-y", "magentaa11y-mcp"]

Config Structure

• skillsFolder - Subfolder name to bundle skills under (e.g., "a11y")
• readmeTemplate - README template file to copy into skills directories
• skills - Array of skill objects (id, name, npmName, optional subPath, description, mcpServers)
• hostApplications - Array of host application configuration objects
• mcpServers - MCP server definitions with name, description, command, and args
• profiles - Predefined skill + MCP bundles selectable at install time; reference skills by their id

All changes take effect immediately - just re-run the CLI to deploy your updated config.

Safe Merging

The CLI safely merges with existing configurations:

• MCP configs - Adds/updates only the specified servers, preserves others
• Skills - Installs only the configured skills, preserves other skills in the directory
• Backups - Creates .bak files if JSON parsing fails

Directory Structure

Local Install (Project-Specific)

your-project/
├── .claude/
│   └── skills/             # Claude Code skills
├── .cursor/
│   └── skills/             # Cursor skills
├── .codex/
│   └── skills/             # Codex skills
├── .github/
│   └── skills/             # VSCode skills
├── .codeium/windsurf/
│   └── skills/             # Windsurf skills
└── .factory/
    └── skills/             # Factory skills

Global Install (User-Wide)

~/.claude/
  └── skills/               # Claude Code global skills
~/.cursor/
  └── skills/               # Cursor global skills
~/.codex/
  └── skills/               # Codex global skills
~/.github/
  └── skills/               # VSCode global skills
~/.codeium/windsurf/
  └── skills/               # Windsurf global skills
~/.factory/
  └── skills/               # Factory global skills

# MCP config files live in AppData/Application Support:
# Windows: %APPDATA%/.claude.json
# Windows: %APPDATA%/.cursor/mcp.json
# Windows: %APPDATA%/.codex/config.toml
# Windows: %APPDATA%/Code/User/mcp.json
# Windows: %APPDATA%/.codeium/windsurf/mcp_config.json
# Windows: %APPDATA%/.factory/mcp.json
# macOS:   ~/Library/Application Support/<same paths as above>
# Linux:   $XDG_CONFIG_HOME/<same paths as above> (or ~/.config)

Note: Paths are fully customizable per IDE in config/settings.json

MCP Servers Included (Default)

Add your own by editing config/settings.json:

All servers are installed under the arc-a11y- prefix so they group together in your IDE's MCP list.

| Server | Package | Description | |--------|---------|-------------| | arc-a11y-wcag | wcag-guidelines-mcp | WCAG 2.2 guidelines, success criteria, techniques | | arc-a11y-aria | aria-mcp | WAI-ARIA roles, states, properties | | arc-a11y-magentaa11y | magentaa11y-mcp | Component accessibility acceptance criteria | | arc-a11y-personas | a11y-personas-mcp | Accessibility personas for diverse users | | arc-a11y-issues | arc-issues-mcp | AxeCore violation formatting | | arc-a11y-playwright | @playwright/mcp | Browser automation for runtime accessibility testing |

Complete Config Example

Here's what a complete config/settings.json looks like:

{
  "skillsFolder": "a11y",
  "readmeTemplate": "deploy-README.md",
  "skills": [
    {
      "id": "arc-a11y-base-web",
      "name": "Arc A11y Base Web",
      "npmName": "arc-a11y-skills",
      "subPath": "web/arc-a11y-base-web",
      "description": "Foundational accessibility patterns for web code",
      "mcpServers": []
    },
    {
      "id": "arc-a11y-quick-test",
      "name": "Arc A11y Quick Test",
      "npmName": "arc-a11y-skills",
      "subPath": "web/arc-a11y-quick-test",
      "description": "Fast axe-core scan reporting critical and serious violations",
      "mcpServers": ["arc-a11y-playwright"]
    }
  ],
  "profiles": [
    {
      "id": "developer-web",
      "displayName": "Developer (Web)",
      "description": "For Web developers building accessible applications",
      "skills": ["arc-a11y-base-web", "arc-a11y-quick-test"],
      "mcpServers": ["arc-a11y-wcag", "arc-a11y-aria", "arc-a11y-magentaa11y", "arc-a11y-playwright"]
    }
  ],
  "hostApplications": [
    {
      "id": "claude",
      "displayName": "Claude Code",
      "mcpServerKey": "servers",
      "skillsFolder": ".claude/skills",
      "mcpConfigFile": ".claude/mcp.json"
    },
    {
      "id": "cursor",
      "displayName": "Cursor",
      "mcpServerKey": "mcpServers",
      "skillsFolder": ".cursor/skills",
      "mcpConfigFile": ".cursor/mcp.json"
    },
    {
      "id": "windsurf",
      "displayName": "Windsurf",
      "mcpServerKey": "servers",
      "skillsFolder": ".codeium/windsurf/skills",
      "mcpConfigFile": ".codeium/windsurf/mcp_config.json"
    }
  ],
  "mcpServers": [
    {
      "name": "arc-a11y-wcag",
      "description": "WCAG guidelines reference",
      "command": "npx",
      "args": ["-y", "wcag-guidelines-mcp"]
    },
    {
      "name": "arc-a11y-aria",
      "description": "ARIA specification reference",
      "command": "npx",
      "args": ["-y", "aria-mcp"]
    }
  ]
}

Everything is customizable - add, remove, or modify any section to match your needs.