a11y-devkit-deploy 0.6.4 → 0.7.0

package/README.md

@@ -1,6 +1,8 @@
 # A11y Devkit Deploy
 
-A cross-platform CLI for deploying accessibility skills and MCP servers across Claude Code, Cursor, Codex, and VSCode.
+A **fully config-driven**, cross-platform CLI for deploying accessibility skills and MCP servers across Claude Code, Cursor, Codex, and VSCode.
+
+**Add new skills or MCP servers without writing code** - just edit the JSON config and re-run.
 
 ## Install
 
@@ -21,21 +23,63 @@ a11y-devkit-deploy
 - `--local` / `--global`: Skip the scope prompt.
 - `--yes`: Use defaults (local scope, all IDEs, install skills).
 
+## After Installation
+
+Once installation completes, you'll find a comprehensive usage guide in your IDE's skills directory:
+
+- **Local install**: `.claude/skills/README.md` (or `.cursor/skills/`, `.codex/skills/` depending on your IDE)
+- **Global install**: `~/.claude/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/skills-README.md](templates/skills-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 7 accessibility skill packages
-2. **Configuring MCP servers** - Updates each IDE's MCP config to enable 5 accessibility-focused MCP servers:
-   - **wcag** - WCAG 2.2 guidelines, success criteria, and techniques
-   - **aria** - WAI-ARIA roles, states, properties, and patterns
-   - **magentaa11y** - Component accessibility acceptance criteria
-   - **a11y-personas** - Accessibility personas for diverse user needs
-   - **arc-issues** - Format AxeCore violations into standardized issue templates
+1. **Installing skills from npm** - Downloads and installs accessibility skill packages (configurable in `config/a11y.json`)
+2. **Configuring MCP servers** - Updates each IDE's MCP config to enable accessibility-focused MCP servers (also configurable)
+
+**Default configuration includes:**
+   - **7 accessibility skills** - Testing, remediation, validation, documentation, and orchestration
+   - **5 MCP servers**:
+     - **wcag** - WCAG 2.2 guidelines, success criteria, and techniques
+     - **aria** - WAI-ARIA roles, states, properties, and patterns
+     - **magentaa11y** - Component accessibility acceptance criteria
+     - **a11y-personas** - Accessibility personas for diverse user needs
+     - **arc-issues** - Format AxeCore violations into standardized issue templates
 
-### Skills Installed
+**Fully customizable** - add/remove skills or MCP servers by editing the config file.
 
-The following skill packages are installed from npm:
+### Skills Installed (Default)
+
+The following skill packages are installed from npm by default. **Add your own by editing `config/a11y.json`**:
 
 | Skill | Package | Description |
 |-------|---------|-------------|
@@ -74,11 +118,58 @@ The generated MCP config looks like this:
 
 ## Configuration
 
-Edit `config/a11y.json` to customize the deployment:
+The entire tool is **fully config-driven**. Edit `config/a11y.json` to customize everything without touching code:
+
+### Example: Adding a New Skill
+
+Simply add an object to the `skills` array with a `name` (npm package) and `description`:
+
+```json
+{
+  "skills": [
+    {
+      "name": "a11y-tester-skill",
+      "description": "Run accessibility tests"
+    },
+    {
+      "name": "your-custom-skill",
+      "description": "Your custom skill description"
+    }
+  ]
+}
+```
+
+### Example: Adding a New MCP Server
 
-- `skills` - Array of npm package names to install as skills
+Add an object to the `mcpServers` array with name, description, command, and args:
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "wcag",
+      "description": "WCAG guidelines reference",
+      "command": "npx",
+      "args": ["-y", "wcag-mcp"]
+    },
+    {
+      "name": "your-custom-mcp",
+      "description": "Your custom MCP server",
+      "command": "npx",
+      "args": ["-y", "your-mcp-package"]
+    }
+  ]
+}
+```
+
+### Config Structure
+
+- `skills` - Array of skill objects with `name` (npm package) and `description`
 - `ideSkillsPaths` - IDE-specific skills directories (configurable per IDE)
-- `mcpServers` - MCP server definitions using npx
+- `ideMcpPaths` - IDE-specific MCP config file paths
+- `mcpServers` - MCP server definitions with name, description, command, and args
+
+All changes take effect immediately - just re-run the CLI to deploy your updated config.
 
 ## Directory Structure
 
@@ -106,7 +197,9 @@ MCP configurations are written to each IDE's OS-specific config path:
 - **Windows**: `%APPDATA%\{IDE}\mcp.json`
 - **Linux**: `~/.config/{IDE}/mcp.json`
 
-## MCP Servers Included
+## MCP Servers Included (Default)
+
+**Add your own by editing `config/a11y.json`**:
 
 | Server | Package | Description |
 |--------|---------|-------------|

package/config/a11y.json

@@ -1,19 +1,41 @@
 {
+  "skillsFolder": "a11y",
+  "readmeTemplate": "deploy-README.md",
   "skills": [
-    "a11y-base-web-skill",
-    "a11y-issue-writer-skill",
-    "a11y-tester-skill",
-    "a11y-remediator-skill",
-    "a11y-validator-skill",
-    "web-standards-skill",
-    "a11y-audit-fix-agent-orchestrator-skill"
+    {
+      "name": "a11y-base-web-skill",
+      "description": "Core accessibility testing utilities"
+    },
+    {
+      "name": "a11y-issue-writer-skill",
+      "description": "Document accessibility issues"
+    },
+    {
+      "name": "a11y-tester-skill",
+      "description": "Run accessibility tests"
+    },
+    {
+      "name": "a11y-remediator-skill",
+      "description": "Fix accessibility issues"
+    },
+    {
+      "name": "a11y-validator-skill",
+      "description": "Validate accessibility compliance"
+    },
+    {
+      "name": "web-standards-skill",
+      "description": "Web standards reference"
+    },
+    {
+      "name": "a11y-audit-fix-agent-orchestrator-skill",
+      "description": "Orchestrate accessibility audits"
+    }
   ],
   "ideSkillsPaths": {
     "claude": ".claude/skills",
     "cursor": ".cursor/skills",
     "codex": ".codex/skills",
-    "vscode": ".github/skills",
-    "local": ".github/skills"
+    "vscode": ".github/skills"
   },
   "ideMcpPaths": {
     "claude": ".claude/mcp.json",
@@ -24,43 +46,33 @@
   "mcpServers": [
     {
       "name": "wcag",
+      "description": "WCAG guidelines reference",
       "command": "npx",
-      "args": [
-        "-y",
-        "wcag-mcp"
-      ]
+      "args": ["-y", "wcag-mcp"]
     },
     {
       "name": "aria",
+      "description": "ARIA specification reference",
       "command": "npx",
-      "args": [
-        "-y",
-        "aria-mcp"
-      ]
+      "args": ["-y", "aria-mcp"]
     },
     {
       "name": "magentaa11y",
+      "description": "MagentaA11y accessibility acceptance criteria tool",
       "command": "npx",
-      "args": [
-        "-y",
-        "magentaa11y-mcp"
-      ]
+      "args": ["-y", "magentaa11y-mcp"]
     },
     {
       "name": "a11y-personas",
+      "description": "Accessibility personas and user scenarios",
       "command": "npx",
-      "args": [
-        "-y",
-        "a11y-personas-mcp"
-      ]
+      "args": ["-y", "a11y-personas-mcp"]
     },
     {
       "name": "arc-issues",
+      "description": "Pre-formatted a11y issue templates",
       "command": "npx",
-      "args": [
-        "-y",
-        "arc-issues-mcp"
-      ]
+      "args": ["-y", "arc-issues-mcp"]
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a11y-devkit-deploy",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "CLI to deploy a11y skills and MCP servers across IDEs",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,7 @@
     "bin",
     "src",
     "config",
+    "templates",
     "README.md"
   ],
   "keywords": [

package/src/cli.js

@@ -23,24 +23,6 @@ async function loadPackageJson() {
   return JSON.parse(raw);
 }
 
-const skillDescriptions = {
-  "a11y-base-web-skill": "Core accessibility testing utilities",
-  "a11y-issue-writer-skill": "Document accessibility issues",
-  "a11y-tester-skill": "Run accessibility tests",
-  "a11y-remediator-skill": "Fix accessibility issues",
-  "a11y-validator-skill": "Validate accessibility compliance",
-  "web-standards-skill": "Web standards reference",
-  "a11y-audit-fix-agent-orchestrator-skill": "Orchestrate accessibility audits"
-};
-
-const mcpDescriptions = {
-  "wcag": "WCAG guidelines reference",
-  "aria": "ARIA specification reference",
-  "magentaa11y": "MagentaA11y accessibility acceptance criteria tool",
-  "a11y-personas": "Accessibility personas and user scenarios",
-  "arc-issues": "Pre-formatted a11y issue templates"
-};
-
 function parseArgs(argv) {
   const args = new Set(argv.slice(2));
   return {
@@ -69,13 +51,14 @@ async function run() {
 
   console.log("\nSkills to install:");
   config.skills.forEach((skill) => {
-    const description = skillDescriptions[skill] || "No description";
-    console.log(`${skill} - ${description}`);
+    const name = typeof skill === "string" ? skill : skill.name;
+    const description = typeof skill === "string" ? "No description" : (skill.description || "No description");
+    console.log(`${name} - ${description}`);
   });
 
   console.log("\nMCP Servers to install:");
   config.mcpServers.forEach((server) => {
-    const description = mcpDescriptions[server.name] || "No description";
+    const description = server.description || "No description";
     console.log(`${server.name} - ${description}`);
   });
   console.log("");
@@ -179,7 +162,8 @@ async function run() {
         ? ideSelection.map((ide) => idePaths[ide].localSkillsDir)
         : ideSelection.map((ide) => idePaths[ide].skillsDir);
 
-      const result = await installSkillsFromNpm(config.skills, skillTargets, tempDir);
+      const skillNames = config.skills.map((skill) => typeof skill === "string" ? skill : skill.name);
+      const result = await installSkillsFromNpm(skillNames, skillTargets, tempDir, config.skillsFolder, config.readmeTemplate);
       skillsSpinner.succeed(`${result.installed} skills installed to ${skillTargets.length} IDE location(s).`);
     } catch (error) {
       skillsSpinner.fail(`Failed to install skills: ${error.message}`);
@@ -212,7 +196,18 @@ async function run() {
   success("All done. Your skills and MCP servers are ready.");
   info("Skills installed from npm packages.");
   info("MCP servers use npx - no local installation needed!");
+  console.log("");
+  success("Next Steps:");
+  const skillsFolderPath = config.skillsFolder ? `${config.skillsFolder}/` : "";
+  const skillsPath = scope === "local"
+    ? `.claude/skills/${skillsFolderPath}README.md (or your IDE's equivalent)`
+    : `~/.claude/skills/${skillsFolderPath}README.md (or your IDE's global skills directory)`;
+  info(`📖 Check ${skillsPath} for comprehensive usage guide`);
+  info("✨ Includes 70+ example prompts for all skills and MCP servers");
+  info("🚀 Start with the 'Getting Started' section for your first accessibility check");
+  console.log("");
   info("You can re-run this CLI any time to update skills and configs.");
+  info("Documentation: https://github.com/joe-watkins/a11y-devkit#readme");
 }
 
 export {

package/src/installers/skills.js

@@ -1,6 +1,10 @@
 import fs from "fs/promises";
 import path from "path";
 import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 async function pathExists(target) {
   try {
@@ -13,20 +17,32 @@ async function pathExists(target) {
 
 function run(command, args, options = {}) {
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, { stdio: "pipe", shell: true, ...options });
+    const child = spawn(command, args, {
+      stdio: "pipe",
+      shell: true,
+      ...options,
+    });
     let stdout = "";
     let stderr = "";
-    
-    child.stdout?.on("data", (data) => { stdout += data; });
-    child.stderr?.on("data", (data) => { stderr += data; });
-    
+
+    child.stdout?.on("data", (data) => {
+      stdout += data;
+    });
+    child.stderr?.on("data", (data) => {
+      stderr += data;
+    });
+
     child.on("error", reject);
     child.on("close", (code) => {
       if (code === 0) {
         resolve({ stdout, stderr });
         return;
       }
-      reject(new Error(`${command} ${args.join(" ")} failed with code ${code}: ${stderr}`));
+      reject(
+        new Error(
+          `${command} ${args.join(" ")} failed with code ${code}: ${stderr}`,
+        ),
+      );
     });
   });
 }
@@ -39,18 +55,26 @@ async function cleanupTemp(tempDir) {
 
 /**
  * Install skills from npm packages into IDE skills directories.
- * 
+ *
  * 1. Creates temp directory with package.json listing skills as dependencies
  * 2. Runs npm install in temp directory
  * 3. Copies installed skill packages (SKILL.md files) to target directories
  * 4. Returns temp directory path for cleanup
- * 
+ *
  * @param {string[]} skills - Array of npm package names
  * @param {string[]} targetDirs - Array of target directories to install skills to
  * @param {string} tempDir - Temporary directory for npm install
+ * @param {string} skillsFolder - Optional subfolder name to bundle skills (e.g., "a11y")
+ * @param {string} readmeTemplate - README template filename from templates folder
  * @returns {Promise<{installed: number, tempDir: string}>}
  */
-async function installSkillsFromNpm(skills, targetDirs, tempDir) {
+async function installSkillsFromNpm(
+  skills,
+  targetDirs,
+  tempDir,
+  skillsFolder = null,
+  readmeTemplate = "deploy-README.md",
+) {
   // Create temp directory
   await fs.mkdir(tempDir, { recursive: true });
 
@@ -59,7 +83,7 @@ async function installSkillsFromNpm(skills, targetDirs, tempDir) {
     name: "a11y-skills-temp",
     version: "1.0.0",
     private: true,
-    dependencies: {}
+    dependencies: {},
   };
 
   for (const skill of skills) {
@@ -68,7 +92,7 @@ async function installSkillsFromNpm(skills, targetDirs, tempDir) {
 
   await fs.writeFile(
     path.join(tempDir, "package.json"),
-    JSON.stringify(packageJson, null, 2)
+    JSON.stringify(packageJson, null, 2),
   );
 
   // Run npm install
@@ -79,7 +103,12 @@ async function installSkillsFromNpm(skills, targetDirs, tempDir) {
   let installedCount = 0;
 
   for (const targetDir of targetDirs) {
-    await fs.mkdir(targetDir, { recursive: true });
+    // Determine the actual skills directory (with or without bundle folder)
+    const skillsDir = skillsFolder
+      ? path.join(targetDir, skillsFolder)
+      : targetDir;
+
+    await fs.mkdir(skillsDir, { recursive: true });
 
     for (const skill of skills) {
       const skillPackageDir = path.join(nodeModulesDir, skill);
@@ -88,7 +117,7 @@ async function installSkillsFromNpm(skills, targetDirs, tempDir) {
       if (await pathExists(skillMdPath)) {
         // Create skill directory in target (use package name without -skill suffix)
         const skillDirName = skill.replace(/-skill$/, "");
-        const targetSkillDir = path.join(targetDir, skillDirName);
+        const targetSkillDir = path.join(skillsDir, skillDirName);
         await fs.mkdir(targetSkillDir, { recursive: true });
 
         // Copy SKILL.md
@@ -96,15 +125,25 @@ async function installSkillsFromNpm(skills, targetDirs, tempDir) {
         installedCount++;
       }
     }
+
+    // Copy the comprehensive README template to the skills directory
+    const readmeTemplatePath = path.join(
+      __dirname,
+      "..",
+      "..",
+      "templates",
+      readmeTemplate,
+    );
+    const targetReadmePath = path.join(skillsDir, "a11y-devkit-README.md");
+    if (await pathExists(readmeTemplatePath)) {
+      await fs.copyFile(readmeTemplatePath, targetReadmePath);
+    }
   }
 
-  return { 
-    installed: installedCount / targetDirs.length, 
-    tempDir 
+  return {
+    installed: installedCount / targetDirs.length,
+    tempDir,
   };
 }
 
-export {
-  installSkillsFromNpm,
-  cleanupTemp
-};
+export { installSkillsFromNpm, cleanupTemp };

package/templates/deploy-README.md

@@ -0,0 +1,644 @@
+# A11y DevKit - Skills & MCP Guide
+
+Welcome to your comprehensive accessibility testing and remediation toolkit! You now have access to 7 specialized skills and 5 knowledge-rich MCP servers designed to help you build, test, and maintain accessible web applications.
+
+## What Was Installed
+
+### 7 Accessibility Skills
+Your AI assistant can now leverage these specialized capabilities:
+- **a11y-base-web** - Core accessibility patterns and foundational web code
+- **a11y-issue-writer** - Document accessibility violations in standardized formats
+- **a11y-tester** - Automated testing with axe-core and Playwright
+- **a11y-remediator** - Fix accessibility issues in your codebase
+- **a11y-validator** - Validate WCAG compliance and best practices
+- **web-standards** - Reference web standards and specifications
+- **a11y-audit-fix-agent-orchestrator** - Coordinate full accessibility audits
+
+### 5 MCP Knowledge Servers
+These servers provide instant access to accessibility guidelines and specifications:
+- **wcag** - WCAG 2.2 guidelines, success criteria, and techniques
+- **aria** - WAI-ARIA roles, states, properties, and patterns
+- **magentaa11y** - Component accessibility acceptance criteria
+- **a11y-personas** - User personas representing diverse accessibility needs
+- **arc-issues** - Pre-formatted AxeCore violation issue templates
+
+## Quick Start
+
+### Verify Your Installation
+
+Check if everything is working:
+
+```
+Can you verify all accessibility skills and MCP servers are available?
+```
+
+### Your First Accessibility Check
+
+Try this simple example to get started:
+
+```
+Using the a11y-tester skill, scan the homepage at https://example.com for accessibility issues and summarize the findings.
+```
+
+### Understanding the Workflow
+
+1. **Test** - Use a11y-tester to identify issues
+2. **Research** - Query MCP servers (wcag, aria, magentaa11y) for guidance
+3. **Fix** - Use a11y-remediator to implement solutions
+4. **Document** - Use a11y-issue-writer to create issue reports
+5. **Validate** - Use a11y-validator to confirm compliance
+6. **Orchestrate** - Use the orchestrator for comprehensive audits
+
+## Understanding the Tools
+
+### Skills (The Doers)
+
+| Skill | Purpose | When to Use |
+|-------|---------|-------------|
+| **a11y-base-web** | Foundational accessibility code patterns | Building new components with accessibility built-in |
+| **a11y-issue-writer** | Create standardized accessibility reports | Documenting violations for teams or issue trackers |
+| **a11y-tester** | Run automated accessibility scans | Testing pages or components for WCAG violations |
+| **a11y-remediator** | Fix accessibility issues in code | Implementing solutions for identified problems |
+| **a11y-validator** | Validate WCAG compliance | Verifying fixes meet accessibility standards |
+| **web-standards** | Reference web specifications | Understanding semantic HTML and best practices |
+| **a11y-audit-fix-agent-orchestrator** | Coordinate end-to-end audits | Running comprehensive accessibility assessments |
+
+### MCP Servers (The Knowledge Base)
+
+| Server | Provides | Example Query |
+|--------|----------|---------------|
+| **wcag** | WCAG 2.2 guidelines and success criteria | "What are the requirements for WCAG 2.2 Level AA color contrast?" |
+| **aria** | WAI-ARIA specification details | "What attributes are required for the dialog role?" |
+| **magentaa11y** | Component acceptance criteria | "What are the accessibility requirements for a dropdown menu?" |
+| **a11y-personas** | User scenarios and needs | "Show me personas who rely on keyboard navigation" |
+| **arc-issues** | Formatted AxeCore violation templates | "Format this color contrast violation as a GitHub issue" |
+
+## Example Prompts Library
+
+### Getting Started (Beginner)
+
+#### 1. Simple Page Scan
+```
+Use a11y-tester to scan https://mywebsite.com and list the top 5 most critical accessibility issues.
+```
+**Uses**: a11y-tester skill
+**Outcome**: Quick overview of major violations
+
+#### 2. Check WCAG Requirements
+```
+Query the wcag MCP server: What are the Level AA requirements for keyboard accessibility?
+```
+**Uses**: wcag MCP server
+**Outcome**: Specific WCAG 2.2 success criteria and techniques
+
+#### 3. Fix a Specific Issue
+```
+Using a11y-remediator, fix the missing alt text on images in src/components/Gallery.tsx
+```
+**Uses**: a11y-remediator skill
+**Outcome**: Code updated with proper alt attributes
+
+#### 4. Understand ARIA Roles
+```
+Ask the aria MCP server: What's the difference between role="button" and a native button element?
+```
+**Uses**: aria MCP server
+**Outcome**: Explanation of semantic differences and best practices
+
+#### 5. Document an Issue
+```
+Use a11y-issue-writer to create a GitHub issue for the form label violations found in our checkout page.
+```
+**Uses**: a11y-issue-writer skill
+**Outcome**: Formatted issue ready to post
+
+#### 6. Validate a Component
+```
+Use a11y-validator to check if the modal dialog in src/Modal.tsx meets WCAG 2.2 Level AA standards.
+```
+**Uses**: a11y-validator skill
+**Outcome**: Compliance report with pass/fail status
+
+#### 7. Learn Component Patterns
+```
+Query magentaa11y MCP: What are the acceptance criteria for an accessible tabs component?
+```
+**Uses**: magentaa11y MCP server
+**Outcome**: Comprehensive accessibility requirements checklist
+
+---
+
+### Skills-Based Workflows (Intermediate)
+
+#### a11y-base-web Skill
+
+**1. Build an Accessible Form**
+```
+Using a11y-base-web, create a contact form component with proper labels, error messages, and ARIA attributes.
+```
+**Outcome**: Form component with accessibility best practices built-in
+
+**2. Implement Skip Links**
+```
+Use a11y-base-web to add skip navigation links to our main layout component in src/Layout.tsx
+```
+**Outcome**: Skip links added with proper focus management
+
+**3. Create Accessible Tables**
+```
+With a11y-base-web, refactor the data table in src/DataGrid.tsx to use proper table semantics and ARIA where needed.
+```
+**Outcome**: Table with proper headers, scope, and ARIA attributes
+
+#### a11y-issue-writer Skill
+
+**1. Generate Batch Issue Reports**
+```
+Use a11y-issue-writer to create separate GitHub issues for each unique violation type found in our latest accessibility scan.
+```
+**Outcome**: Multiple formatted issues ready for tracking
+
+**2. Document Color Contrast Failures**
+```
+With a11y-issue-writer, create a detailed report of all color contrast violations on our marketing pages, including screenshots and WCAG references.
+```
+**Outcome**: Comprehensive report with remediation guidance
+
+**3. Create Sprint Planning Documentation**
+```
+Use a11y-issue-writer to generate a prioritized list of accessibility fixes for our next sprint, organized by WCAG level and impact.
+```
+**Outcome**: Prioritized backlog items for team planning
+
+#### a11y-tester Skill
+
+**1. Test Component Library**
+```
+Use a11y-tester to scan all components in our Storybook at http://localhost:6006 and generate a summary report.
+```
+**Outcome**: Component-by-component accessibility assessment
+
+**2. Regression Testing**
+```
+With a11y-tester, scan our production site and compare results to the baseline from last week to identify new violations.
+```
+**Outcome**: Diff report showing newly introduced issues
+
+**3. Test User Flows**
+```
+Use a11y-tester to test the complete checkout flow from cart to confirmation, checking each step for accessibility issues.
+```
+**Outcome**: Multi-page accessibility audit of critical path
+
+#### a11y-remediator Skill
+
+**1. Fix Form Validation**
+```
+Using a11y-remediator, update our form validation in src/forms/ to provide accessible error messages with proper ARIA attributes.
+```
+**Outcome**: Forms with screen reader-friendly error handling
+
+**2. Remediate Focus Management**
+```
+Use a11y-remediator to fix focus issues in our modal dialogs, ensuring focus is trapped and returned properly.
+```
+**Outcome**: Modals with proper keyboard trap and focus restoration
+
+**3. Update Images for Accessibility**
+```
+With a11y-remediator, audit and fix all images in src/components/ to have appropriate alt text or aria-hidden.
+```
+**Outcome**: Images properly labeled or marked as decorative
+
+#### a11y-validator Skill
+
+**1. Pre-deployment Validation**
+```
+Use a11y-validator to verify our staging environment at https://staging.mysite.com meets WCAG 2.2 Level AA before we deploy to production.
+```
+**Outcome**: Go/no-go compliance report
+
+**2. Component Certification**
+```
+With a11y-validator, check if our new autocomplete component meets all WCAG success criteria and ARIA authoring practices.
+```
+**Outcome**: Detailed compliance checklist for component
+
+**3. Validate Fixes**
+```
+Use a11y-validator to confirm that the color contrast issues we fixed in PR #123 now meet WCAG requirements.
+```
+**Outcome**: Verification that remediation was successful
+
+#### web-standards Skill
+
+**1. Semantic HTML Review**
+```
+Using web-standards, review src/pages/About.tsx and suggest improvements for proper semantic HTML structure.
+```
+**Outcome**: Recommendations for header hierarchy, landmarks, etc.
+
+**2. Best Practices Audit**
+```
+With web-standards, analyze our navigation component and suggest improvements based on HTML5 and ARIA best practices.
+```
+**Outcome**: Specific recommendations with standards references
+
+**3. Progressive Enhancement Check**
+```
+Use web-standards to evaluate if our interactive components work without JavaScript and follow progressive enhancement principles.
+```
+**Outcome**: Assessment of baseline functionality and enhancement layers
+
+#### a11y-audit-fix-agent-orchestrator Skill
+
+**1. Full Site Audit**
+```
+Using a11y-audit-fix-agent-orchestrator, perform a complete accessibility audit of https://mysite.com and create a remediation plan.
+```
+**Outcome**: Comprehensive audit report with prioritized fix recommendations
+
+**2. Automated Fix Pipeline**
+```
+With a11y-audit-fix-agent-orchestrator, scan our codebase, identify issues, attempt automated fixes, and report what requires manual intervention.
+```
+**Outcome**: Batch of automated fixes plus list of manual tasks
+
+**3. Continuous Monitoring Setup**
+```
+Use a11y-audit-fix-agent-orchestrator to set up a weekly accessibility audit workflow that tests, reports, and suggests fixes.
+```
+**Outcome**: Automated monitoring configuration
+
+---
+
+### MCP-Enhanced Workflows (Intermediate)
+
+#### wcag MCP Server
+
+**1. Research Success Criteria**
+```
+Query wcag MCP: What are all Level AA success criteria related to keyboard accessibility in WCAG 2.2?
+```
+**Outcome**: Complete list of relevant success criteria with descriptions
+
+**2. Understand Techniques**
+```
+Ask wcag MCP: What techniques can I use to meet success criterion 1.4.3 Contrast (Minimum)?
+```
+**Outcome**: List of sufficient techniques and advisory techniques
+
+**3. Compare WCAG Versions**
+```
+Query wcag MCP: What new success criteria were added in WCAG 2.2 compared to 2.1?
+```
+**Outcome**: Changelog of new requirements
+
+#### aria MCP Server
+
+**1. Role Requirements**
+```
+Ask aria MCP: What states and properties are required vs. supported for the combobox role?
+```
+**Outcome**: Complete list of required and optional ARIA attributes
+
+**2. Pattern Implementation**
+```
+Query aria MCP: Show me the keyboard interaction pattern for an accordion widget.
+```
+**Outcome**: Detailed keyboard navigation requirements
+
+**3. Attribute Values**
+```
+Ask aria MCP: What are the valid values for aria-live and when should I use each?
+```
+**Outcome**: Explanation of polite, assertive, and off values with use cases
+
+#### magentaa11y MCP Server
+
+**1. Component Acceptance Criteria**
+```
+Query magentaa11y MCP: What are the accessibility acceptance criteria for a date picker component?
+```
+**Outcome**: Comprehensive checklist of requirements
+
+**2. Testing Scenarios**
+```
+Ask magentaa11y MCP: What should I test when validating an accessible navigation menu?
+```
+**Outcome**: List of test scenarios and expected behaviors
+
+**3. Implementation Guidance**
+```
+Query magentaa11y MCP: What are the developer notes for implementing an accessible tooltip?
+```
+**Outcome**: Code examples and implementation guidance
+
+#### a11y-personas MCP Server
+
+**1. Understand User Needs**
+```
+Query a11y-personas MCP: Show me personas who use screen readers and their primary challenges.
+```
+**Outcome**: Detailed persona profiles with assistive tech usage
+
+**2. Test Perspective**
+```
+Ask a11y-personas MCP: What would a user with motor disabilities experience when using our navigation?
+```
+**Outcome**: User scenario highlighting potential issues
+
+**3. Design Validation**
+```
+Query a11y-personas MCP: Which personas would be affected by small click targets and how?
+```
+**Outcome**: Impact analysis across different disability types
+
+#### arc-issues MCP Server
+
+**1. Format Violations**
+```
+Query arc-issues MCP: Format this AxeCore color-contrast violation as a GitHub issue with all details.
+```
+**Outcome**: Ready-to-post issue with title, description, and remediation steps
+
+**2. Batch Issue Creation**
+```
+Ask arc-issues MCP: Convert these 5 AxeCore violations into separate Jira tickets with appropriate labels.
+```
+**Outcome**: Multiple formatted tickets for issue tracking
+
+**3. Standardized Reporting**
+```
+Query arc-issues MCP: Create a markdown report from this AxeCore scan result that I can add to our PR.
+```
+**Outcome**: Formatted report suitable for version control
+
+---
+
+### Combined Workflows (Advanced)
+
+#### 1. Research-Driven Remediation
+```
+First, query wcag MCP for the requirements of success criterion 4.1.2. Then use a11y-remediator to fix the name/role/value issues in src/components/CustomButton.tsx based on those requirements.
+```
+**Uses**: wcag MCP + a11y-remediator
+**Outcome**: Standards-compliant fix with proper justification
+
+#### 2. Persona-Based Testing
+```
+Query a11y-personas MCP to understand keyboard-only users' needs, then use a11y-tester to specifically test keyboard navigation on our dashboard, documenting findings with a11y-issue-writer.
+```
+**Uses**: a11y-personas MCP + a11y-tester + a11y-issue-writer
+**Outcome**: User-centered test results with documented issues
+
+#### 3. Pattern-Based Development
+```
+Ask magentaa11y MCP for the acceptance criteria for an accessible carousel, then use a11y-base-web to implement it, and a11y-validator to confirm compliance.
+```
+**Uses**: magentaa11y MCP + a11y-base-web + a11y-validator
+**Outcome**: Fully accessible component built to specification
+
+#### 4. Standards-Based Audit
+```
+Use web-standards to review our semantic HTML, query aria MCP for proper ARIA usage, then use a11y-validator to confirm everything meets WCAG 2.2 Level AA.
+```
+**Uses**: web-standards + aria MCP + a11y-validator
+**Outcome**: Multi-faceted standards compliance check
+
+#### 5. Comprehensive Issue Documentation
+```
+Use a11y-tester to scan our site, query wcag MCP to get the relevant success criteria for each violation, then use a11y-issue-writer to create detailed GitHub issues with WCAG references.
+```
+**Uses**: a11y-tester + wcag MCP + a11y-issue-writer
+**Outcome**: Well-documented issues with standards citations
+
+#### 6. Component Library Validation
+```
+For each component in src/components/, query magentaa11y MCP for acceptance criteria, use a11y-validator to test against those criteria, and generate a compliance matrix.
+```
+**Uses**: magentaa11y MCP + a11y-validator
+**Outcome**: Component library accessibility certification report
+
+#### 7. Fix Verification Workflow
+```
+Use a11y-tester to identify issues, a11y-remediator to fix them, then a11y-validator to confirm the fixes meet requirements, documenting the changes with a11y-issue-writer.
+```
+**Uses**: a11y-tester + a11y-remediator + a11y-validator + a11y-issue-writer
+**Outcome**: Complete test-fix-verify-document cycle
+
+#### 8. ARIA Pattern Implementation
+```
+Query aria MCP for the disclosure widget pattern requirements, use a11y-base-web to implement it, test with a11y-tester, and validate with a11y-validator.
+```
+**Uses**: aria MCP + a11y-base-web + a11y-tester + a11y-validator
+**Outcome**: Spec-compliant ARIA widget with test verification
+
+#### 9. User-Centered Design Review
+```
+Query a11y-personas MCP for diverse user needs, use web-standards to ensure semantic HTML foundation, then a11y-remediator to enhance with proper ARIA where semantics fall short.
+```
+**Uses**: a11y-personas MCP + web-standards + a11y-remediator
+**Outcome**: User-focused accessible implementation
+
+#### 10. Regression Prevention
+```
+Use a11y-tester to scan before merging PR, query wcag MCP for any new violations' requirements, use a11y-remediator to fix them, then a11y-validator to confirm before deployment.
+```
+**Uses**: a11y-tester + wcag MCP + a11y-remediator + a11y-validator
+**Outcome**: Automated accessibility gate in CI/CD
+
+#### 11. Documentation-First Development
+```
+Query magentaa11y MCP for component requirements, use a11y-base-web to scaffold the component, document expected behavior with a11y-issue-writer, then validate with a11y-validator.
+```
+**Uses**: magentaa11y MCP + a11y-base-web + a11y-issue-writer + a11y-validator
+**Outcome**: Well-documented, specification-driven component
+
+#### 12. Cross-Reference Validation
+```
+Use a11y-tester to find violations, query both wcag MCP and aria MCP to understand the requirements, then use a11y-remediator to implement fixes that satisfy both specifications.
+```
+**Uses**: a11y-tester + wcag MCP + aria MCP + a11y-remediator
+**Outcome**: Fixes validated against multiple standards
+
+#### 13. Issue Triage Pipeline
+```
+Use a11y-tester to scan multiple pages, query wcag MCP to determine WCAG level for each issue, use arc-issues MCP to format them, then a11y-issue-writer to add prioritization and assignment.
+```
+**Uses**: a11y-tester + wcag MCP + arc-issues MCP + a11y-issue-writer
+**Outcome**: Prioritized, formatted issue backlog
+
+#### 14. Accessibility Training Material
+```
+Query a11y-personas MCP for user scenarios, wcag MCP for requirements, magentaa11y MCP for component patterns, and use a11y-issue-writer to create training documentation.
+```
+**Uses**: a11y-personas MCP + wcag MCP + magentaa11y MCP + a11y-issue-writer
+**Outcome**: Educational materials for team onboarding
+
+#### 15. Third-Party Component Audit
+```
+Use web-standards to evaluate semantic foundation of a library component, query aria MCP for proper ARIA usage, use a11y-tester to scan it, and a11y-validator to certify compliance.
+```
+**Uses**: web-standards + aria MCP + a11y-tester + a11y-validator
+**Outcome**: Vendor component accessibility assessment
+
+---
+
+### Complete Audit Workflows (Advanced)
+
+#### 1. Full Site Accessibility Audit
+```
+Using a11y-audit-fix-agent-orchestrator, perform a comprehensive audit of https://mysite.com, querying wcag MCP for requirements, aria MCP for patterns, and generating a complete remediation roadmap with prioritized issues documented via a11y-issue-writer.
+```
+**Outcome**: End-to-end audit report with actionable remediation plan
+
+#### 2. Pre-Launch Compliance Check
+```
+Use the orchestrator to scan our staging environment, validate against WCAG 2.2 Level AA with a11y-validator, cross-reference findings with magentaa11y MCP acceptance criteria, and create a go/no-go report with all issues documented.
+```
+**Outcome**: Deployment readiness assessment with compliance status
+
+#### 3. Automated Remediation Pipeline
+```
+Run the orchestrator to scan the codebase with a11y-tester, automatically fix common issues with a11y-remediator, validate fixes with a11y-validator, document remaining issues with a11y-issue-writer, and create PRs for manual review.
+```
+**Outcome**: Batch fixes applied, remaining work itemized and tracked
+
+#### 4. Component Library Certification
+```
+Use the orchestrator to audit every component in src/components/, query magentaa11y MCP for each component type's requirements, validate with a11y-validator, and generate a comprehensive certification report showing compliance status.
+```
+**Outcome**: Component library accessibility certification matrix
+
+#### 5. Continuous Accessibility Monitoring
+```
+Set up the orchestrator to run weekly scans with a11y-tester, compare results to previous baselines, query wcag MCP for any new violation types, automatically create issues via a11y-issue-writer for regressions, and alert the team.
+```
+**Outcome**: Automated accessibility monitoring and regression detection
+
+---
+
+## Quick Reference Cheat Sheet
+
+| Task | Tool to Use | Example |
+|------|-------------|---------|
+| Scan a page for issues | a11y-tester | `Scan https://example.com with a11y-tester` |
+| Fix missing alt text | a11y-remediator | `Fix alt text in src/Gallery.tsx` |
+| Document violations | a11y-issue-writer | `Create GitHub issue for form errors` |
+| Check WCAG requirements | wcag MCP | `Query wcag: color contrast requirements` |
+| Understand ARIA roles | aria MCP | `Query aria: button role requirements` |
+| Get component patterns | magentaa11y MCP | `Query magentaa11y: tabs acceptance criteria` |
+| Validate compliance | a11y-validator | `Validate modal meets WCAG 2.2 AA` |
+| Review semantics | web-standards | `Review HTML structure in src/Nav.tsx` |
+| Understand user needs | a11y-personas MCP | `Query a11y-personas: screen reader users` |
+| Format AxeCore violations | arc-issues MCP | `Format this violation as Jira ticket` |
+| Run full audit | orchestrator | `Audit https://mysite.com with orchestrator` |
+
+---
+
+## MCP Setup Verification
+
+### How to Verify MCP Servers Are Working
+
+Your MCP servers run via `npx`, which means they're fetched on-demand and don't require local installation. To verify they're working, try these test prompts:
+
+#### Test wcag MCP
+```
+Query the wcag MCP server: What is success criterion 2.1.1?
+```
+**Expected**: Details about keyboard accessibility requirements
+
+#### Test aria MCP
+```
+Query the aria MCP server: What attributes does the button role support?
+```
+**Expected**: List of ARIA attributes applicable to buttons
+
+#### Test magentaa11y MCP
+```
+Query the magentaa11y MCP server: List all available component types.
+```
+**Expected**: List of components with acceptance criteria
+
+#### Test a11y-personas MCP
+```
+Query the a11y-personas MCP server: Show me all available personas.
+```
+**Expected**: List of user personas with disabilities
+
+#### Test arc-issues MCP
+```
+Query the arc-issues MCP server: What issue formats are available?
+```
+**Expected**: List of supported formats (GitHub, Jira, etc.)
+
+### Basic Troubleshooting
+
+If MCP servers aren't responding:
+
+1. **Restart your IDE** - MCP servers initialize when the IDE starts
+2. **Check npx connectivity** - Run `npx --version` in your terminal to ensure npx is working
+3. **Verify MCP configuration** - Check that your IDE's `mcp.json` file exists and includes the 5 servers
+4. **Check network** - MCP servers using npx need internet access for first-time package downloads
+5. **Look for errors** - Check your IDE's output panel for MCP-related error messages
+
+### MCP Configuration Locations
+
+Your MCP configuration was written to one of these locations (depending on your OS and IDE):
+
+- **macOS**: `~/Library/Application Support/{IDE}/mcp.json`
+- **Windows**: `%APPDATA%\{IDE}\mcp.json`
+- **Linux**: `~/.config/{IDE}/mcp.json`
+
+Where `{IDE}` is one of: `Claude`, `Cursor`, `Codex`, or `Code` (for VSCode)
+
+---
+
+## Getting Help
+
+### Resources
+
+- **Report Issues**: [GitHub Issues](https://github.com/joe-watkins/a11y-devkit/issues)
+- **Full Documentation**: Check the main README.md in the parent directory
+- **Community**: Share your prompts and workflows with the community
+
+### Common Issues
+
+**"Skill not found"**
+- Verify skills are installed in your IDE's skills directory
+- Check that the skill name matches exactly (e.g., `a11y-tester`, not `a11y-testing`)
+- Restart your IDE to reload skills
+
+**"MCP server not responding"**
+- Ensure you're querying the MCP server explicitly (e.g., "Query wcag MCP:")
+- Restart your IDE to reinitialize MCP servers
+- Check that npx is installed and working
+
+**"Permission denied"**
+- MCP servers run via npx and may need permission to execute
+- Check your system's security settings for CLI tool execution
+
+### Tips for Best Results
+
+1. **Be specific** - Instead of "check accessibility", try "Use a11y-tester to scan the login form for WCAG violations"
+2. **Combine tools** - Leverage both skills and MCP servers together for comprehensive workflows
+3. **Reference files** - Provide specific file paths when asking for fixes or reviews
+4. **Iterate** - Start with testing, then research, then fix, then validate
+5. **Document** - Use a11y-issue-writer to track what you find and fix
+
+---
+
+## Next Steps
+
+Now that you have this powerful toolkit, here are some suggested next steps:
+
+1. **Run your first scan** - Use a11y-tester on your main page
+2. **Explore the MCP servers** - Query wcag, aria, and magentaa11y to learn what they offer
+3. **Try a combined workflow** - Pick one from the Advanced section and adapt it to your project
+4. **Set up monitoring** - Use the orchestrator to establish regular accessibility checks
+5. **Train your team** - Share example prompts with teammates to build accessibility into your workflow
+
+**Remember**: Accessibility is a journey, not a destination. These tools help you continuously improve your web applications for all users.
+
+Happy building!