# Appendix V: Accessibility Agents Reference
>
> **Listen to Episode 39:** [Accessibility Agents - Complete Reference](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

## Complete Reference - Agents, Slash Commands, Instructions, Configuration Levels, and All File Formats

> This is your comprehensive reference for Accessibility Agents and the full VS Code Copilot customization system. The ecosystem includes **55 agents** across **3 teams** and **5 platforms**, plus 54+ slash commands, 17 skills, and 6 instruction files. For the lesson, see [Chapter 16: Accessibility Agents](16-accessibility-agents.md). For Copilot keyboard shortcuts and Chat features, see [Appendix W: GitHub Copilot Reference](appendix-w-github-copilot-reference.md).


## Table of Contents

1. [The Full Agent Ecosystem](#1-the-full-agent-ecosystem)
2. [GitHub Workflow Agents - Quick Reference](#2-github-workflow-agents---quick-reference)
3. [Slash Commands and Prompts](#3-slash-commands-and-prompts)
4. [Customization Primitives - Decision Guide](#4-customization-primitives---decision-guide)
5. [Scope and Priority - All Levels](#5-scope-and-priority---all-levels)
6. [Always-On Instructions - All File Types](#6-always-on-instructions---all-file-types)
7. [File-Based Instructions (.instructions.md)](#7-file-based-instructions-instructionsmd)
8. [.agent.md - Complete Format Reference](#8-agentmd---complete-format-reference)
9. [.prompt.md - Complete Format Reference](#9-promptmd---complete-format-reference)
10. [Agent Skills (SKILL.md) - Complete Format Reference](#10-agent-skills-skillmd---complete-format-reference)
11. [Hooks (.json) - Lifecycle Automation](#11-hooks-json---lifecycle-automation)
12. [preferences.md - Accessibility Agents Personal Settings](#12-preferencesmd---accessibility-agents-personal-settings)
13. [Diagnostics and Troubleshooting](#13-diagnostics-and-troubleshooting)
14. [Further Reading](#14-further-reading)


## 1. The Full Agent Ecosystem

Accessibility Agents includes 55 agents organized into three specialized teams, available on five platforms.

### Platforms

| Platform | Agent Format | Installation |
| ----------  | -------------  | -------------  |
| **GitHub Copilot** (VS Code) | `.github/agents/*.agent.md` | Fork repo or run installer |
| **Claude Code** | Per-agent CLAUDE.md + hook enforcement | One-liner installer auto-detects |
| **Gemini CLI** | Gemini skill files | One-liner installer auto-detects |
| **Claude Desktop** | MCP server integration | One-liner installer auto-detects |
| **Codex CLI** | Codex agent files | One-liner installer auto-detects |

### Team 1: Accessibility (26 agents)

| Agent | Type | What It Does |
| -------  | ------  | -------------  |
| `@accessibility-lead` | Orchestrator | Delegates multi-agent accessibility audits to specialist agents |
| `@aria-specialist` | Task | ARIA roles, states, properties, widget patterns (modals, tabs, comboboxes) |
| `@modal-specialist` | Task | Dialog focus trapping, escape behavior, screen reader overlay announcements |
| `@contrast-master` | Task | Color contrast ratios, focus indicators, dark mode, visual presentation |
| `@keyboard-navigator` | Task | Tab order, focus management, keyboard shortcuts, skip links, focus traps |
| `@live-region-controller` | Task | Live region announcements, dynamic content, toasts, loading states |
| `@forms-specialist` | Task | Form labels, error handling, validation, autocomplete, field grouping |
| `@alt-text-headings` | Task | Alt text quality, heading hierarchy, document outline, landmark structure |
| `@tables-specialist` | Task | Table markup, scope, caption, headers, sortable columns, ARIA grid |
| `@link-checker` | Informational | Link text quality, ambiguous links, WCAG 2.4.4 and 2.4.9 compliance |
| `@web-accessibility-wizard` | Orchestrator | Full guided WCAG audit - severity scoring, remediation tracking, action plan |
| `@testing-coach` | Informational | NVDA/JAWS/VoiceOver testing guidance, automated test setup (axe-core, Playwright) |
| `@wcag-guide` | Informational | WCAG 2.2 AA reference, success criteria explanations, conformance levels |
| `@word-accessibility` | Task | Microsoft Word document accessibility auditing and remediation |
| `@excel-accessibility` | Task | Microsoft Excel spreadsheet accessibility auditing and remediation |
| `@powerpoint-accessibility` | Task | Microsoft PowerPoint presentation accessibility auditing |
| `@office-scan-config` | Informational | Office document scan configuration and rule management |
| `@pdf-accessibility` | Task | PDF accessibility auditing (PDF/UA, tagged PDF structure) |
| `@pdf-scan-config` | Informational | PDF scan configuration and rule management |
| `@document-accessibility-wizard` | Orchestrator | Guided document audit wizard for Word, Excel, PowerPoint, and PDF |
| `@cognitive-accessibility` | Informational | Cognitive accessibility, plain language, reading level, content clarity |
| `@mobile-accessibility` | Task | iOS VoiceOver and Android TalkBack native app accessibility |
| `@design-system-auditor` | Task | Design system component accessibility review and pattern library audit |
| `@markdown-a11y-assistant` | Task | Markdown headings, links, alt text, tables, emoji, structure enforcement |
| `@epub-accessibility` | Task | ePub and digital publication accessibility auditing |
| `@epub-scan-config` | Informational | ePub scan configuration and rule management |

### Team 2: GitHub Workflow (12 agents)

| Agent | Type | What It Does |
| -------  | ------  | -------------  |
| `@daily-briefing` | Informational | Morning situation report - issues, PRs, CI, security, community activity |
| `@issue-tracker` | Both | Find, prioritize, triage, draft replies to issues across repositories |
| `@pr-review` | Both | Structured PR reviews with risk assessment, change maps, inline suggestions |
| `@analytics` | Informational | Contribution velocity, review turnaround, code hotspots, workload distribution |
| `@insiders-a11y-tracker` | Both | Monitor accessibility-sensitive changes - WCAG/ARIA, headings, links, keyboard |
| `@template-builder` | Guided | Interactive issue template wizard via VS Code Ask Questions |
| `@github-hub` | Both | Central hub for all GitHub operations and repository management |
| `@repo-admin` | Task | Repository settings, branch protection rules, and rulesets |
| `@team-manager` | Task | Team membership, permissions, organization management |
| `@contributions-hub` | Informational | Contribution tracking, contributor recognition, community metrics |
| `@repo-manager` | Task | Multi-repository operations and cross-repo workflow coordination |
| `@nexus` | Orchestrator | Cross-agent orchestration - coordinates multiple agents for complex workflows |

### Team 3: Developer Tools (6 agents)

| Agent | Type | What It Does |
| -------  | ------  | -------------  |
| `@developer-hub` | Both | Central hub for developer tool operations and project scaffolding |
| `@python-specialist` | Task | Python accessibility patterns, Django/Flask a11y, best practices |
| `@wxpython-specialist` | Task | wxPython GUI accessibility - keyboard, focus, screen reader support |
| `@desktop-a11y-specialist` | Task | Desktop application accessibility across Windows, macOS, and Linux |
| `@desktop-a11y-testing-coach` | Informational | Desktop accessibility testing guidance and automation setup |
| `@a11y-tool-builder` | Task | Build custom accessibility testing tools, linters, and CI checks |

### Supporting Resources

| Resource | Count | Location |
| ----------  | -------  | ---------  |
| Copilot prompts | 54+ | `.github/prompts/*.prompt.md` |
| Copilot skills | 17 | `.github/skills/*/SKILL.md` |
| Copilot instructions | 6 | `.github/instructions/*.instructions.md` |
| Claude Code hooks | 3 | `.claude/hooks/` |
| Example violations | 20+ | `example/` directory |


## 2. GitHub Workflow Agents - Quick Reference

The GitHub Workflow team includes 12 agents that automate common repository operations. These are good starting points if you have completed the Day 1 skills - but explore any agent in the ecosystem that matches your workflow.\n\nInvoke any agent by typing `@agent-name` in Copilot Chat (`Ctrl+Shift+I`).


### `@daily-briefing` - Morning Briefing

**Agent file:** `.github/agents/daily-briefing.agent.md`

| Example Command | What It Does |
| ----------------  | -------------  |
| `@daily-briefing morning briefing` | Full prioritized situation report |
| `@daily-briefing what needs my attention today in accessibility-agents?` | Repo-scoped briefing |
| `@daily-briefing summarize activity from the last week` | Weekly digest |

#### Output sections (H2 headings - navigate with `H`)

- Needs Your Action
  - Pull Requests Waiting for Your Review
  - @Mentions Requiring Response
  - CI Failures on Your Branches
- For Your Awareness
  - Issues Opened Since Yesterday
  - Your PRs With New Activity
  - Security and Dependabot Alerts
- All Clear (confirms checked but empty categories)


### `@issue-tracker` - Issue Management

**Agent file:** `.github/agents/issue-tracker.agent.md`

| Example Command | What It Does |
| ----------------  | -------------  |
| `@issue-tracker find open issues labeled good-first-issue` | Filtered issue search |
| `@issue-tracker find accessibility issues across all my repos` | Cross-repo search |
| `@issue-tracker is there a duplicate of issue #42?` | Duplicate check |
| `@issue-tracker draft a reply to issue #15` | Draft a response (you review before posting) |

**Important:** The agent drafts replies. You post. Always review tone against the [Culture & Etiquette guide](08-culture-etiquette.md).


### `@pr-review` - Pull Request Review

**Agent file:** `.github/agents/pr-review.agent.md`

| Example Command | What It Does |
| ----------------  | -------------  |
| `@pr-review review PR #14` | Full review document |
| `@pr-review what is the risk level of PR #8?` | Risk assessment only |
| `@pr-review generate inline comments for PR #14` | Line-level suggestions only |
| `@pr-review summarize PR #14 in two sentences` | Quick summary |

#### Output sections (H2/H3 headings)

- Summary
- Risk Assessment (High / Medium / Low)
- Files Changed (per-file descriptions)
- Suggested Inline Comments (prefixed: `nit:`, `question:`, `suggestion:`, `important:`, `blocking:`, `praise:`)
- Questions for the Author
- What Looks Good
- Review Verdict Recommendation

**Critical rule:** The agent produces a starting point. Read it, edit it, post it under your own name.


### `@analytics` - Team Analytics

**Agent file:** `.github/agents/analytics.agent.md`

| Example Command | What It Does |
| ----------------  | -------------  |
| `@analytics team velocity in accessibility-agents this month` | Contribution pace |
| `@analytics who are the most active contributors?` | Top contributors by commits and reviews |
| `@analytics which files are changed most often?` | Code hotspot detection |
| `@analytics how long does PR review take on average?` | Review turnaround time |


### `@insiders-a11y-tracker` - Accessibility Change Monitor

**Agent file:** `.github/agents/insiders-a11y-tracker.agent.md`

| Example Command | What It Does |
| ----------------  | -------------  |
| `@insiders-a11y-tracker check recent changes` | Scan last commits for a11y impact |
| `@insiders-a11y-tracker review my PR #14 for accessibility impact` | PR-scoped accessibility review |
| `@insiders-a11y-tracker are there any accessibility regressions in the last 5 commits?` | Regression scan |

#### What it monitors

| Area | What It Checks |
| ------  | ---------------  |
| Markdown / docs | Heading hierarchy skips, non-descriptive link text, missing image alt text, table structure |
| HTML / JSX | ARIA attribute changes, `tabIndex`, `outline: none`, `display: none` on focused elements |
| JavaScript | `onMouseDown` without keyboard equivalent, `onMouseEnter`/`onMouseLeave` without keyboard parallel |
| Semantic HTML | `<div>`/`<span>` used for interactive elements instead of `<button>`, `<a>`, `<input>` |

**Risk levels:** High (regression), Medium (degraded), Low (improvement opportunity)


### `@template-builder` - Issue Template Wizard

**Agent file:** `.github/agents/template-builder.agent.md`

| Example Command | What It Does |
| ----------------  | -------------  |
| `@template-builder create accessibility template` | Guided a11y bug report template |
| `@template-builder create security template` | Guided security vulnerability template |
| `@template-builder build a feature request form` | General feature request template |
| `@template-builder reorder the fields` | Modify existing generated YAML |

#### Guided workflow phases

1. **Metadata:** name, description, title prefix, auto-labels
2. **Fields (one at a time):** type → label → description → required → type-specific options
3. **Review and output:** complete YAML ready to save to `.github/ISSUE_TEMPLATE/`

**Supported field types:** `markdown`, `input`, `textarea`, `dropdown`, `checkboxes`


## 3. Slash Commands and Prompts

The repository includes 54+ slash commands. Type `/` in Copilot Chat to open the command menu. Each command corresponds to a `.prompt.md` file in `.github/prompts/`.

### Workshop Quick Reference

| Command | What It Does |
| ---------  | -------------  |
| `/address-comments` | Address all open review comments on your PR |
| `/a11y-update` | Latest accessibility improvements with WCAG cross-references |
| `/ci-status` | CI/CD health dashboard across your repos |
| `/create-issue` | Create a well-formed issue from a description |
| `/daily-briefing` | Morning activity snapshot across all your repos |
| `/draft-release` | Generate release notes from merged PRs |
| `/explain-code` | Explain selected code in plain language |
| `/issue-reply` | Draft a reply to an issue thread |
| `/manage-branches` | List, compare, and clean up branches |
| `/manage-issue` | Update labels, assignees, or status on an issue |
| `/merge-pr` | Check merge readiness and merge a PR |
| `/my-issues` | Your open issues with priority signals |
| `/my-prs` | Your open PRs with CI and review status |
| `/my-stats` | Your contribution stats across repos |
| `/notifications` | Manage GitHub notifications without opening a browser |
| `/onboard-repo` | First-time scan of a repo - health, quick wins, recommended actions |
| `/pr-author-checklist` | Pre-merge checklist for PR authors |
| `/pr-comment` | Draft a response to a PR comment |
| `/pr-report` | Detailed PR analysis report |
| `/project-status` | GitHub Projects board overview - columns, blocked, stale |
| `/react` | Suggest or add a reaction to an issue or comment |
| `/refine-issue` | Improve issue title, description, and labels |
| `/release-prep` | Complete release preparation workflow |
| `/review-pr` | AI-generated review with inline suggestions |
| `/security-dashboard` | Dependabot alerts and vulnerability status |
| `/sprint-review` | End-of-sprint summary with velocity and retrospective |
| `/team-dashboard` | Team activity and contribution overview |
| `/triage` | Triage a new issue with label and priority suggestions |

### Most Useful During the Workshop

| Command | Example Usage |
| ---------  | -------------  |
| `/my-issues` | `/my-issues` - see all your open issues with priority signals |
| `/review-pr` | `/review-pr #14` - AI-generated review with inline suggestions |
| `/triage` | `/triage #22` - get label and priority suggestions for a new issue |
| `/issue-reply` | `/issue-reply #15` - draft a reply to an issue thread |
| `/a11y-update` | `/a11y-update insiders` - latest a11y improvements with WCAG refs |
| `/daily-briefing` | `/daily-briefing` - same output as `@daily-briefing` |
| `/draft-release` | `/draft-release v2.0` - generate release notes from merged PRs |


## 4. Customization Primitives - Decision Guide

Before creating any file, choose the right primitive for the job. Each primitive is a different file type with a different purpose, scope, and trigger.

| Primitive | File Type | When to Use |
| -----------  | -----------  | -------------  |
| **Always-on instructions** | `copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md` | Standards that apply to every request - coding conventions, project context, tone |
| **File-based instructions** | `*.instructions.md` | Rules that only apply to specific file types or folders - Python style, test conventions, docs standards |
| **Prompts / Slash Commands** | `*.prompt.md` | Single repeatable task invoked with `/command` - scaffolding, triage, PR prep |
| **Agent Skills** | `SKILL.md` in a named folder | Multi-step workflow with bundled scripts and reference files - testing, deployment, auditing |
| **Custom Agents** | `*.agent.md` | Specialized persona with tool restrictions - orchestrates tasks, can invoke subagents |
| **Hooks** | `*.json` | Deterministic lifecycle automation - block dangerous commands, run formatters, enforce policy |
| **Personal Preferences** | `preferences.md` | Accessibility Agents fork-local personal settings - repos, output format, timezone |

### Choosing Between Primitives

#### Instructions vs Agent?

- Instructions guide behavior passively (always-on or file-scoped). Agents perform tasks actively (on-demand, tool-using).

#### Prompt vs Agent?

- Use a prompt for a single focused task you invoke explicitly. Use an agent when the task spans multiple steps, needs different tools, or should work as a subagent for other agents.

#### Prompt vs Skill?

- Both appear as `/` slash commands. Use a prompt for one well-defined task. Use a skill when the workflow bundles scripts, templates, or reference docs alongside the instructions.

#### Instructions vs Hooks?

- Instructions *guide* the agent (non-deterministic). Hooks *enforce* behavior via shell commands at lifecycle events - they run regardless of what the agent was prompted to do.


## 5. Scope and Priority - All Levels

Every customization file exists at one of three scopes. VS Code combines all matching files from all scopes and sends them to the model.

### The Three Scopes

| Scope | Where Files Live | Who Shares It |
| -------  | -----------------  | ---------------  |
| **User / Personal** | VS Code profile folder | You only - follows Settings Sync across devices |
| **Workspace** | `.github/` and related folders in the repo | Everyone who clones the repo |
| **Organization** | GitHub organization settings (Enterprise/Team) | Everyone in the org |

### Priority Order (highest wins in conflicts)

1. **Personal / User-level** - your profile instructions override everything
2. **Workspace / Repository-level** - `.github/copilot-instructions.md`, `AGENTS.md`, `.github/agents/*.agent.md`
3. **Organization-level** - organization-defined custom instructions (lowest priority)

### User-Level File Locations (Personal, Cross-Workspace)

All of these files roam with your VS Code Settings Sync.

| File Type | Location on Windows | Location on macOS/Linux |
| -----------  | ---------------------  | ------------------------  |
| Instructions | `%APPDATA%\Code - Insiders\User\prompts\*.instructions.md` | `~/Library/Application Support/Code - Insiders/User/prompts/` |
| Prompts | Same folder - `*.prompt.md` | Same folder |
| Agents | Same folder - `*.agent.md` | Same folder |

> On this machine: `C:\Users\jeffb\AppData\Roaming\Code - Insiders\User\prompts\`

To sync user instructions/prompts/agents across devices:

1. Enable Settings Sync (`Ctrl+Shift+P` → "Settings Sync: Turn On")
2. `Ctrl+Shift+P` → "Settings Sync: Configure"
3. Check "Prompts and Instructions"

### Workspace-Level File Locations (Repo-Shared)

| File Type | Default Location | Override Setting |
| -----------  | -----------------  | -----------------  |
| Always-on instructions | `.github/copilot-instructions.md` | - (fixed path) |
| Always-on (multi-tool) | `AGENTS.md` (root) or nested per subfolder | `chat.useAgentsMdFile` to enable/disable |
| Always-on (Claude compat) | `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md` (local only) | `chat.useClaudeMdFile` to enable/disable |
| File-based instructions | `.github/instructions/*.instructions.md` | `chat.instructionsFilesLocations` |
| Claude-format instructions | `.claude/rules/*.instructions.md` | - |
| Agents | `.github/agents/*.agent.md` | - |
| Prompts | `.github/prompts/*.prompt.md` | - |
| Skills | `.github/skills/<name>/SKILL.md` | - |
| Hooks | `.github/hooks/*.json` | - |
| Personal preferences | `.github/agents/preferences.md` (gitignored) | - |

### How Multiple Files Are Combined

VS Code collects **all** matching instruction files from all scopes and includes them all in the chat context. There is no single winner - all are combined. Priority only resolves conflicts between contradictory instructions.


## 6. Always-On Instructions - All File Types

Always-on instructions are automatically included in every chat request. You never invoke them - Copilot simply follows them.

### Option A: `.github/copilot-instructions.md` (Recommended)

**Best for:** Most projects. Cross-editor compatible. Version-controlled and team-shared.

```text
.github/
  copilot-instructions.md   ← lives here
```

**File structure:** Plain Markdown. No frontmatter required.

```markdown
# Copilot Instructions for accessibility-agents

## Accessibility Standards
- Include semantic HTML elements in generated markup
- Add ARIA labels to interactive components when no visible text is present
- Never use color as the only indicator of meaning

## Documentation Style
- Write for screen reader users first
- Use active voice: "Press Ctrl+G" not "You can press Ctrl+G"
- Never skip heading levels (H1 → H2 → H3, never H1 → H3)

## Commit Message Format
- Conventional commits: `type: description`
- Types: feat, fix, docs, style, refactor, test, chore
- Reference issues at end: "Fixes #123"

## Tone
- Direct, friendly, professional
- Assume readers are competent but new to this specific tool
```

**Auto-generate with:** Type `/init` in Copilot Chat - VS Code analyzes your workspace and generates a tailored `copilot-instructions.md`.


### Option B: `AGENTS.md` (Multi-Tool / Monorepo)

**Best for:** Projects that use multiple AI tools (Copilot, Claude Code, Gemini CLI, etc.) where a single instruction file should work across all of them. Also best for monorepos where different folders need different rules.

#### Root-level (applies everywhere)

```text
AGENTS.md           ← root of workspace
```

#### Nested (per subfolder - experimental)

```text
AGENTS.md                  ← root defaults
frontend/AGENTS.md         ← frontend-specific rules (overrides root for frontend/)
backend/AGENTS.md          ← backend-specific rules (overrides root for backend/)
```

Enable nested file support: `chat.useNestedAgentsMdFiles: true` in VS Code settings.

**File structure:** Same as `copilot-instructions.md` - plain Markdown, no frontmatter.

**Cross-tool compatibility:** AGENTS.md is an open standard. GitHub Copilot, Claude Code, Gemini CLI, and other AI tools all recognize it. Use it instead of `copilot-instructions.md` when you work with multiple AI tools.

**Rule:** Use either `AGENTS.md` or `copilot-instructions.md` - not both.


### Option C: `CLAUDE.md` (Claude Code Compatibility)

**Best for:** Teams that use Claude Code alongside VS Code. One file, recognized by both.

| Location | Scope |
| ----------  | -------  |
| `CLAUDE.md` (workspace root) | Workspace - shared via git |
| `.claude/CLAUDE.md` | Workspace - shared via git |
| `CLAUDE.local.md` (workspace root) | Workspace - local only, not committed |
| `~/.claude/CLAUDE.md` | User-level - personal, all workspaces |

VS Code recognizes all four locations when `chat.useClaudeMdFile` is enabled (default: on).

For `.claude/rules/*.instructions.md` files using the Claude Rules format, use **`paths`** instead of `applyTo` for glob matching:

```markdown
description: "Python coding standards"
paths: ["**/*.py", "src/**"]
Follow PEP 8. Use type hints. Write docstrings for public functions.
```


### Option D: Settings-Based Instructions (Deprecated)

> **Note:** Settings-based instructions may be removed in a future VS Code version. Use file-based instructions instead for new work.

For specialized scenarios, VS Code settings accept inline instructions or file references:

```json
// .vscode/settings.json or user settings.json
{
  "github.copilot.chat.codeGeneration.instructions": [
    { "text": "Always add error handling for async functions." },
    { "file": ".github/instructions/code-style.instructions.md" }
  ],
  "github.copilot.chat.testGeneration.instructions": [
    { "text": "Always use describe/it test structure." },
    { "text": "Include at least one edge case per function." }
  ],
  "github.copilot.chat.reviewSelection.instructions": [
    { "text": "Check for WCAG 2.2 Level AA compliance in all markup." }
  ],
  "github.copilot.chat.commitMessageGeneration.instructions": [
    { "text": "Use conventional commits format: type(scope): description" }
  ]
}
```

Each entry is an array of objects with either `text` (inline instruction) or `file` (path to an instructions file relative to workspace root).


### Organization-Level Instructions (GitHub Enterprise)

Organization administrators can define custom instructions that apply to all repositories in the organization. Every team member gets these instructions automatically.

#### To enable discovery in VS Code

```json
// User settings.json
{
  "github.copilot.chat.organizationInstructions.enabled": true
}
```

Organization instructions are the lowest priority - workspace and user instructions override them when they conflict.


## 7. File-Based Instructions (`.instructions.md`)

File-based instructions load conditionally - either when the files you are editing match a glob pattern, or when the agent determines the instruction is relevant to the current task.

**Use for:** Language-specific rules, framework conventions, module-specific standards that only apply to part of the codebase.

### File Locations

| Scope | Location |
| -------  | ----------  |
| Workspace | `.github/instructions/*.instructions.md` |
| Additional workspace folders | Configure with `chat.instructionsFilesLocations` setting |
| User / Personal | VS Code profile prompts folder (`*.instructions.md`) |

### Frontmatter Fields

```yaml
name: "Display Name"           # Optional - defaults to filename; shown in UI
description: "Use when..."     # Optional - enables on-demand discovery; be keyword-rich
applyTo: "**/*.py"             # Optional - glob pattern(s) for automatic application
```

### The `applyTo` Glob Pattern

`applyTo` specifies which files trigger automatic inclusion of these instructions. When a file matching the pattern is part of the chat context, the instructions are included automatically.

```yaml
applyTo: "**"                          # ALWAYS included (use carefully - applies everywhere)
applyTo: "**/*.py"                     # All Python files
applyTo: "**/*.{ts,tsx}"               # TypeScript and TSX files
applyTo: "docs/**"                     # Everything under docs/
applyTo: ["src/**", "lib/**"]          # Multiple patterns (OR - either match triggers inclusion)
applyTo: src/**, lib/**                # Same without array syntax
applyTo: "**/*.test.{js,ts}"          # Only test files
applyTo: ".github/ISSUE_TEMPLATE/**"  # Only issue template files
```

**If `applyTo` is omitted:** The instruction is NOT applied automatically. It can still be added manually via the Chat context menu, or picked up by the agent if the `description` semantically matches the current task.

### Discovery Modes

| Mode | Trigger | When to Use |
| ------  | ---------  | -------------  |
| **Automatic** (`applyTo` set) | When matching files are in the chat context | Language rules, framework patterns, folder-specific standards |
| **On-demand** (`description` set, no `applyTo`) | Agent detects task relevance from description keywords | Migration guides, refactoring rules, API design patterns |
| **Manual** | User selects "Add Context → Instructions" in Chat | Ad-hoc attachment for one-off situations |

### Example: Accessibility-Specific Instructions

```markdown
name: "Accessible Markdown Standards"
description: "Use when writing, editing, or reviewing Markdown documentation. Covers heading hierarchy, link text, alt text, and table structure."
applyTo: "**/*.md"

# Markdown Accessibility Standards

- Never skip heading levels (H1 → H2 → H3; H1 → H3 is a WCAG 1.3.1 violation)
- Use descriptive link text: never "click here", "read more", or bare URLs
- Every informational image must have alt text describing what it conveys
- Every decorative image must use empty alt: `![](image.png)` or `alt=""`
- Tables must have header rows using `|---|` Markdown syntax
- Ordered lists (`1.`) only for genuinely sequential steps; use unordered (`-`) otherwise
```

### Example: YAML Issue Template Instructions

```markdown
name: "Issue Template YAML"
description: "Use when writing or reviewing GitHub issue templates in YAML format"
applyTo: ".github/ISSUE_TEMPLATE/**/*.{yml,yaml}"

# Issue Template YAML Standards

- Every field must have a non-empty `label`
- Dropdowns must list at least 2 options
- Use `required: true` only for fields that truly block triage without them
- Prefer `textarea` for free-form text; use `input` only for short identifiers
- Every template must have a `name`, `description`, and `title` prefix
```

### Creating an Instructions File

#### Command Palette method

1. `Ctrl+Shift+P` → "Chat: New Instructions File"
2. Choose Workspace or User Profile scope
3. Enter filename
4. Add `applyTo` and/or `description` frontmatter
5. Write instructions

#### Quick creation method

Type `/instructions` in the Chat input to open the Configure Instructions menu.


## 8. `.agent.md` - Complete Format Reference

### File Locations

| Scope | Location |
| -------  | ----------  |
| Workspace | `.github/agents/*.agent.md` |
| User / Personal | VS Code profile folder `*.agent.md` |

### Complete Frontmatter Reference

```yaml
name: "agent-name"                        # Required - what you type after @ in Chat
description: "Use when..."               # Required - triggers subagent delegation; keyword-rich
tools: ["read", "search", "githubRepo"]  # Optional - tools this agent can use; omit = defaults; [] = none
model: "Claude Sonnet 4.5 (copilot)"     # Optional - specific model to use
agent: "ask"                              # Optional - agent mode: ask | agent | plan | or custom name
argument-hint: "Repo or PR ref..."       # Optional - hint shown in chat input when agent is selected
agents: ["SubagentA", "SubagentB"]       # Optional - restrict which subagents this agent can invoke (omit = all allowed)
user-invocable: true                      # Optional - show in agent picker (default: true); false = subagent only
disable-model-invocation: false          # Optional - prevent other agents from invoking this as subagent (default: false)
handoffs: ["AgentB", "AgentC"]           # Optional - agents this agent can hand off to
```

### Model Fallback Array

```yaml
model: ["Claude Sonnet 4.5 (copilot)", "GPT-5 (copilot)"]
```

The first available model in the array is used. Useful for environments where not all models are licensed.

### Invocation Control

| Setting | Default | Effect |
| ---------  | ---------  | --------  |
| `user-invocable: true` | Default | Agent appears in `@` picker; users can invoke it directly |
| `user-invocable: false` | - | Hidden from picker; only callable as a subagent from another agent |
| `disable-model-invocation: false` | Default | Other agents can delegate to this agent based on description matching |
| `disable-model-invocation: true` | - | This agent cannot be invoked as a subagent; user-invoked only |

### All Tool Names

#### Built-in aliases

| Alias | What It Provides |
| -------  | -----------------  |
| `read` | Read files in the local workspace |
| `edit` | Edit files in the local workspace |
| `search` | Search files and text in the workspace |
| `execute` | Run shell commands in the terminal |
| `agent` | Invoke custom agents as subagents |
| `web` | Fetch URLs and search the web |
| `todo` | Manage task lists |

#### Specific tools (reference by exact name)

| Tool | What It Provides |
| ------  | -----------------  |
| `githubRepo` | GitHub API - search issues, PRs, code |
| `fetch` | HTTP fetch - read external URLs |
| `createFile` | Create new files in the workspace |
| `createDirectory` | Create new directories |
| `editFiles` | Edit multiple files |
| `readFile` | Read specific file contents |
| `codebase` | Search and read the codebase semantically |
| `ask_questions` | VS Code Ask Questions UI (interactive wizard prompts) |
| `github/*` | All GitHub MCP tools (wildcard) |
| `<server>/*` | All tools from a named MCP server |

#### Tool combinations by use case

```yaml
# Read-only research (safest)
tools: ["read", "search", "githubRepo"]

# Documentation / file generation
tools: ["read", "edit", "createFile", "createDirectory"]

# Full GitHub workflow
tools: ["github/*", "read", "edit", "createFile"]

# Terminal access (use carefully)
tools: ["execute", "read", "edit"]

# Conversational only (no file access)
tools: []

# Interactive wizard
tools: ["ask_questions", "createFile"]
```

### Body Structure Template

```markdown
name: my-agent
description: "Use when [specific task/trigger]. Handles [clear purpose]."
tools: ["read", "search"]
user-invocable: true

You are a specialist at [specific role]. Your job is to [clear purpose].

## Constraints
- DO NOT [thing this agent should never do]
- DO NOT post anything without human review
- ONLY [the one thing this agent does]

## Behavior

### [Task Name]
When asked to [task]:
1. [Step one]
2. [Step two]
3. [Step three]

## Output Format

```

## [Section Header]

[Describe the exact output structure here with placeholders]

```text

## Accessibility Requirements
- Use heading level 2 for the document title, level 3 for sections
- Never use tables for lists - ordered or unordered lists are more predictable for screen reader navigation
- Always include "empty state" messages - never omit a section silently

## Scope Boundaries
- You [do X]. You do NOT [do Y].
- The human reviews all output before acting on it.
```

### Creating Your Own Agent

1. Copy an existing `.agent.md` from `.github/agents/`
2. Edit the frontmatter (`name`, `description`, `tools`)
3. Write clear step-by-step instructions in the body
4. Add an Output Format section showing the expected structure
5. Add Constraints and Scope Boundaries sections
6. Save to `.github/agents/your-agent-name.agent.md`
7. Reload VS Code: `Ctrl+Shift+P` → "Reload Window"
8. Type `@your-agent-name` in Copilot Chat

**Tip:** Write keyword-rich descriptions. The description is how other agents decide whether to delegate to yours. "A helpful agent" will never get delegated to. "Use when auditing Markdown files for accessibility violations (missing alt text, heading skips, bare URLs)" will.


## 9. `.prompt.md` - Complete Format Reference

### File Locations

| Scope | Location |
| -------  | ----------  |
| Workspace | `.github/prompts/*.prompt.md` |
| User / Personal | VS Code profile folder `*.prompt.md` |

### Complete Frontmatter Reference

```yaml
name: "command-name"                    # Optional - defaults to filename; the /command name
description: "One-sentence description" # Optional - shown in slash command picker
argument-hint: "PR ref or repo name"   # Optional - hint in chat input when command is selected
agent: "agent"                          # Optional - agent mode: ask | agent | plan | or custom @agent-name
model: "GPT-5 (copilot)"               # Optional - override model for this command
tools: ["github/*", "createFile"]       # Optional - tools this command can use
```

### Model Fallback

```yaml
model: ["GPT-5 (copilot)", "Claude Sonnet 4.5 (copilot)"]
```

### Tool Priority When Agent Is Also Specified

When both the prompt and the referenced agent define tools, VS Code uses this priority:

1. Tools listed in the prompt file's frontmatter (highest priority)
2. Tools from the referenced custom agent
3. Default tools for the selected agent mode

### Input Parameters

```text
${input:parameterName:Prompt text shown to the user}
```

- `parameterName` - internal identifier (no spaces)
- The text after the second `:` is shown to the user as a placeholder or tooltip
- Multiple parameters are supported in one prompt file

```text
${input:repo:Target repository - e.g. owner/repo or leave blank for current workspace}
${input:scope:Optional filter: label name, date range, or org:orgname}
```

### Body - Referencing Tools and Files

```markdown
Use #tool:<tool-name> to explicitly invoke a tool:

Fetch issue #42 with #tool:mcp_github_github_issue_read.

Reference workspace files with Markdown links:
See the configuration in [preferences.md](.github/agents/preferences.md).
```

### Example - Accessibility Update Command

```markdown
name: a11y-update
description: "Get latest accessibility improvements with WCAG cross-references"
agent: insiders-a11y-tracker
tools: ["github/*", "createFile", "ask_questions"]

Show the latest accessibility improvements across tracked repositories.

${input:scope:Optional: 'insiders', 'stable', a repo name, a month, or a WCAG criterion}

## Behavior
Load repo list from `.github/agents/preferences.md`. Group results by: Screen Reader,
Keyboard Navigation, Visual/Contrast, Audio/Motion, Cognitive.

For each finding include:
- WCAG success criterion (e.g., "WCAG 2.4.3 Focus Order (Level A)")
- ARIA design pattern if applicable
- Impact level: Critical / Major / Minor
- Assistive technologies affected
```

### Creating Your Own Slash Command

1. Copy an existing `.prompt.md` from `.github/prompts/`
2. Edit frontmatter (`name`, `description`, `tools`)
3. Write the task instructions in plain English
4. Add `${input:...}` placeholders where the user must provide values
5. Save to `.github/prompts/your-command.prompt.md`
6. Reload VS Code: `Ctrl+Shift+P` → "Reload Window"
7. Type `/your-command` to invoke it

**Both prompts and agent skills appear as `/` slash commands.** The difference: prompts are single-task Markdown files; skills are folders with bundled scripts and references.


## 10. Agent Skills (`SKILL.md`) - Complete Format Reference

A Skill is a folder - not a single file. The folder contains `SKILL.md` plus any scripts, templates, and reference documents the skill needs.

### Folder Structure

```text
.github/skills/
  my-skill/
    SKILL.md              ← Required; name must match folder name
    scripts/
      run-audit.sh        ← Referenced from SKILL.md
    references/
      wcag-criteria.md    ← Reference doc loaded when needed
    assets/
      template.yml        ← Boilerplate files
```

### File Locations

| Scope | Location |
| -------  | ----------  |
| Workspace | `.github/skills/<name>/SKILL.md` |
| Workspace (alternate) | `.agents/skills/<name>/SKILL.md` |
| Workspace (Claude compat) | `.claude/skills/<name>/SKILL.md` |
| User / Personal | `~/.copilot/skills/<name>/SKILL.md` |
| User (alternate) | `~/.agents/skills/<name>/SKILL.md` |
| User (Claude compat) | `~/.claude/skills/<name>/SKILL.md` |

### Complete Frontmatter Reference

```yaml
name: skill-name                      # Required - 1-64 chars; lowercase alphanumeric + hyphens; must match folder name
description: "Use when..."           # Required - keyword-rich trigger phrases for on-demand discovery
argument-hint: "Optional input..."   # Optional - hint shown when skill is selected as slash command
user-invocable: true                  # Optional - appear as slash command (default: true)
disable-model-invocation: false       # Optional - prevent automatic loading by agents (default: false)
```

### Slash Command Behavior

| `user-invocable` | `disable-model-invocation` | Result |
| ------------------  | --------------------------  | --------  |
| true (default) | false (default) | Appears as `/command` AND auto-loads |
| false | false | Does NOT appear as `/command`; auto-loads only |
| true | true | Appears as `/command`; does NOT auto-load |
| false | true | Neither `/command` nor auto-load |

### Progressive Loading - How VS Code Loads Skills

1. **Discovery (~100 tokens):** Reads `name` and `description` to decide if the skill is relevant
2. **Instructions (<5000 tokens):** Loads the full `SKILL.md` body when the skill is relevant
3. **Resources:** Additional files (`scripts/`, `references/`) only load when explicitly referenced from `SKILL.md`

**Keep `SKILL.md` under 500 lines.** Move reference material to `references/` folder files.

### SKILL.md Body Template

```markdown
name: a11y-audit
description: "Audit Markdown files for accessibility violations. Use for heading hierarchy, link text quality, alt text, and WCAG compliance checks."

# Accessibility Audit Skill

## When to Use
- Before opening a PR that modifies Markdown documentation
- When asked to check accessibility compliance of docs
- After generating new documentation content
- During content review for WCAG 1.3.1, 2.4.4, 1.1.1

## Procedure

1. Run the audit script: [audit.sh](./scripts/audit.sh)
2. Review output for heading hierarchy violations (H1→H3 skips)
3. Check all links - flag bare URLs and non-descriptive text
4. Verify alt text on all images
5. Review the [WCAG reference](./references/wcag-quick-ref.md) for remediation guidance
6. Report findings by risk level: High | Medium | Low

## Output Format
- High risk: potential regressions (inaccessible content where it was accessible before)
- Medium risk: degraded accessibility
- Low risk: improvement opportunities
- Include WCAG criterion for each finding
```


## 11. Hooks (`.json`) - Lifecycle Automation

Hooks execute shell commands at specific points in an agent's lifecycle. They are deterministic - they run regardless of what the agent was prompted to do.

**Use hooks for enforcement, not guidance.** For behavior you want to enforce - blocking commands, auto-running formatters, requiring approval - use hooks. For behavior you want to encourage - coding standards, tone, output format - use instructions.

### File Locations

| Scope | Location | Committed? |
| -------  | ----------  | -----------  |
| Workspace (team-shared) | `.github/hooks/*.json` | Yes |
| Workspace (local) | `.claude/settings.local.json` | No (gitignored) |
| Workspace | `.claude/settings.json` | Yes |
| User / Personal | `~/.claude/settings.json` | Personal only |

Hooks from all locations are combined - workspace and user hooks do not override each other.

### Hook Events

| Event | When It Fires |
| -------  | --------------  |
| `SessionStart` | First prompt of a new agent session |
| `UserPromptSubmit` | User submits any prompt |
| `PreToolUse` | Immediately before any tool is invoked |
| `PostToolUse` | After successful tool invocation |
| `PreCompact` | Before context compaction |
| `SubagentStart` | When a subagent begins |
| `SubagentStop` | When a subagent ends |
| `Stop` | When the agent session ends |

### Configuration Format

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": ".github/hooks/validate-before-edit.sh",
        "timeout": 15
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write",
        "windows": "npx.cmd prettier --write",
        "timeout": 30
      }
    ]
  }
}
```

### Hook Command Fields

| Field | Required | Description |
| -------  | ----------  | -------------  |
| `type` | Yes | Must be `"command"` |
| `command` | Yes | Shell command to run (default for all platforms) |
| `windows` | No | Windows-specific override |
| `linux` | No | Linux-specific override |
| `osx` | No | macOS-specific override |
| `cwd` | No | Working directory for the command |
| `env` | No | Environment variable overrides |
| `timeout` | No | Max seconds before killing the process |

### Input/Output Contract

Hooks receive JSON on `stdin`. They can return JSON on `stdout`:

```json
{
  "continue": true,
  "stopReason": "optional message if blocking",
  "systemMessage": "optional context injected into the agent session"
}
```

#### `PreToolUse` permission decisions

```json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Safe read-only operation"
  }
}
```

Permission decisions: `"allow"` | `"ask"` (prompt user) | `"deny"` (block the tool call)

#### Exit codes

- `0` - success; agent continues
- `2` - blocking error; agent stops
- Other - non-blocking warning


## 12. `preferences.md` - Accessibility Agents Personal Settings

Copy `.github/agents/preferences.example.md` to `.github/agents/preferences.md`. The file is in `.gitignore` - your private settings stay only in your local fork.

### Full File Template

```markdown
# My Accessibility Agents Preferences

## My GitHub Username
your-github-username

## Repositories I Work On Most
- community-access/accessibility-agents
- your-org/your-repo

## Preferred Output Format
screen-reader-optimized

## Notification Priority
Accessibility issues first, then review requests assigned to me, then CI failures,
then security alerts, then general activity.

## Review Comment Tone
Direct but constructive. Always explain the "why". Assume good intent from authors.
Warm and encouraging for first-time contributors.

## Time Zone
America/New_York

## Accessibility Context
I use NVDA with Chrome on Windows 11.
```

### `Preferred Output Format` Options

| Value | What It Does |
| -------  | -------------  |
| `"concise"` | Bullet points and short summaries, minimal prose |
| `"detailed"` | Full context and more explanation in every response |
| `"screen-reader-optimized"` | Heading-heavy structure, no tables, explicit empty-state messages |

### `Notification Priority` Options

The `@daily-briefing` agent reads this to sort its output sections. Examples:

```text
Accessibility issues first, then review requests assigned to me, then CI failures, then general activity.
```

```text
Review requests first. CI failures second. Security alerts third. Everything else as a digest at the end.
```

### `Review Comment Tone` Options

The `@pr-review` and `@issue-tracker` agents read this when drafting comments:

```text
Direct but constructive. Always explain the "why" behind a suggestion. Assume good intent from authors.
```

```text
Friendly and encouraging for first-time contributors.
More direct and concise for established contributors.
```

### `Accessibility Context` Options

Tells agents which screen reader and browser you use so they can tailor output and recommendations:

```text
I use NVDA with Chrome on Windows 11.
I use VoiceOver with Safari on macOS Sonoma.
I use JAWS with Firefox on Windows 10.
I use Narrator with Edge on Windows 11.
I use TalkBack on Android.
```


## 13. Diagnostics and Troubleshooting

### View All Loaded Customizations

To see every instruction file, agent, prompt, and skill currently loaded and any errors:

1. In Copilot Chat, select the gear icon (Configure Chat) → **Diagnostics**
2. Or right-click in the Chat view → **Diagnostics**

This shows: which files were found, which were loaded, which have errors, and from which scope (user vs workspace vs organization).

### Common Issues

#### Agent not found when typing `@agent-name`

1. Verify `.github/agents/[name].agent.md` exists in your open workspace folder
2. Check that the YAML frontmatter has no syntax errors (missing quotes, wrong indentation)
3. `Ctrl+Shift+P` → "Reload Window"
4. Check that the `name` field in the frontmatter matches what you are typing

#### Instructions not being applied

1. For `.github/copilot-instructions.md`: file must be at workspace root in the `.github/` folder
2. For `*.instructions.md`: check that `applyTo` glob matches the file you are editing, and that `chat.includeApplyingInstructions` is `true` in VS Code settings
3. For `AGENTS.md`: check that `chat.useAgentsMdFile` is `true`
4. Use Diagnostics view (above) to verify the file was found and loaded

#### Instructions file in wrong place

- Add custom locations: `chat.instructionsFilesLocations` setting accepts an array of additional folder paths

#### Slash command not appearing

1. Verify `.github/prompts/[name].prompt.md` exists
2. `Ctrl+Shift+P` → "Reload Window"
3. File must use `.prompt.md` extension (not just `.md`)


## Accessibility Agents Keyboard Shortcuts

| Action | Shortcut |
| --------  | ----------  |
| Open Copilot Chat | `Ctrl+Shift+I` |
| Invoke an agent | Type `@agent-name` in Chat |
| Use a slash command | Type `/command-name` in Chat |
| Open Accessible View (Chat response or inline suggestion) | `Alt+F2` |
| Insert inline suggestion from Accessible View at cursor | `Ctrl+/` |
| Clear chat history | `Ctrl+L` |
| Reload VS Code window | `Ctrl+Shift+P` → "Reload Window" |
| New instructions file | `Ctrl+Shift+P` → "Chat: New Instructions File" |
| Configure instructions | `Ctrl+Shift+P` → "Chat: Configure Instructions" |
| View diagnostics | Configure Chat gear → Diagnostics |


## 14. Further Reading

For the broader ecosystem - the community plugin marketplace, MCP server integrations, and running agents in the cloud via GitHub Actions - see [Appendix W: GitHub Copilot & Agentic Reference](appendix-w-github-copilot-reference.md).

### Official accessibility.github.com Guides

| Guide | URL |
| -------  | -----  |
| Getting started with custom agents for accessibility | [accessibility.github.com/documentation/guide/getting-started-with-agents/](https://accessibility.github.com/documentation/guide/getting-started-with-agents/) |
| Optimizing Copilot with custom instructions (accessibility) | [accessibility.github.com/documentation/guide/copilot-instructions/](https://accessibility.github.com/documentation/guide/copilot-instructions/) |
| GitHub Copilot for VS Code screen reader guide | [accessibility.github.com/documentation/guide/github-copilot-vsc/](https://accessibility.github.com/documentation/guide/github-copilot-vsc/) |


*Chapter: [Accessibility Agents](16-accessibility-agents.md)*
*Related: [Appendix W: GitHub Copilot Reference](appendix-w-github-copilot-reference.md) | [Issue Templates](15-issue-templates.md) | [Chapter 13: GitHub Copilot](13-github-copilot.md)*