# Appendix W: GitHub Copilot & Agentic Reference
>
> **Listen to Episode 40:** [GitHub Copilot - 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.

## Keyboard Shortcuts, Chat, Screen Reader Workflow, Plugin Ecosystem, and GitHub Agentic Workflows

> Quick-reference card for GitHub Copilot in VS Code and the broader agentic ecosystem - plugins, MCP servers, and cloud-based automation. For the Copilot lesson, see [Chapter 13: GitHub Copilot](13-github-copilot.md). For Accessibility Agents specifically, see [Appendix V: Accessibility Agents Reference](appendix-v-accessibility-agents-reference.md).


## Table of Contents

1. [Keyboard Shortcuts](#1-keyboard-shortcuts)
2. [Chat Participants](#2-chat-participants)
3. [Chat Slash Commands](#3-chat-slash-commands)
4. [Chat Modes](#4-chat-modes)
5. [Custom Instructions - All Levels](#5-custom-instructions---all-levels)
6. [Accessible View Workflow](#6-accessible-view-workflow)
7. [Configuration Scope Reference](#7-configuration-scope-reference)
8. [Instruction Priority and Conflicts](#8-instruction-priority-and-conflicts)
9. [All File Types Quick Reference](#9-all-file-types-quick-reference)
10. [VS Code Settings Reference](#10-vs-code-settings-reference)
11. [Diagnostics and Troubleshooting](#11-diagnostics-and-troubleshooting)
12. [Screen Reader Workflow - Official Guide](#12-screen-reader-workflow---official-guide)
13. [awesome-copilot - Plugin Ecosystem](#13-awesome-copilot---plugin-ecosystem)
14. [GitHub Agentic Workflows - Agents in the Cloud](#14-github-agentic-workflows---agents-in-the-cloud)


## 1. Keyboard Shortcuts

### Inline Suggestions (Ghost Text)

| Action | Windows / Linux | macOS |
| --------  | ----------------  | -------  |
| Accept entire suggestion | `Tab` | `Tab` |
| Reject suggestion | `Escape` | `Escape` |
| Accept one word at a time | `Ctrl+Right Arrow` | `Cmd+Right Arrow` |
| Show next alternative suggestion | `Alt+]` | `Option+]` |
| Show previous alternative suggestion | `Alt+[` | `Option+[` |
| Open full suggestion list | `Ctrl+Enter` | `Cmd+Enter` |
| Open suggestion in Accessible View | `Alt+F2` | `Option+F2` |
| Insert suggestion from Accessible View at cursor | `Ctrl+/` | `Cmd+/` |

**Word-by-word acceptance (`Ctrl+Right Arrow`) is recommended for screen reader users** - it lets you review the suggestion incrementally before committing to it.

**Accessible View workflow for screen reader users:** Press `Alt+F2` when a suggestion appears to hear the full text without streaming noise, then press `Ctrl+/` to insert it directly from the Accessible View without closing the panel first.

### Copilot Chat

| Action | Windows / Linux | macOS |
| --------  | ----------------  | -------  |
| Open Chat panel | `Ctrl+Shift+I` | `Cmd+Shift+I` |
| Open inline chat (in-file, at cursor) | `Ctrl+I` | `Cmd+I` |
| Open Quick Chat (floating dialog) | `Ctrl+Shift+Alt+I` | `Cmd+Shift+Ctrl+I` |
| Send message | `Ctrl+Enter` | `Cmd+Enter` |
| Clear chat history | `Ctrl+L` | `Cmd+L` |

### Accessibility

| Action | Windows / Linux | macOS |
| --------  | ----------------  | -------  |
| Open Accessible View | `Alt+F2` | `Option+F2` |
| Open Accessible Help | `Alt+H` | `Option+H` |
| Close Accessible View | `Escape` | `Escape` |

**Use Accessible View (`Alt+F2`) every time Copilot responds.** It provides the complete response in a readable pane - no streaming, no live region noise, proper heading structure.


## 2. Chat Participants

Type these in the Copilot Chat input to give Copilot context from a specific source.

### `@` Participants - Scope Context

| Participant | What It Does |
| -------------  | -------------  |
| `@workspace` | Searches your entire VS Code workspace for relevant context |
| `@github` | Accesses GitHub.com data - search issues, PRs, code across the platform |
| `@terminal` | Provides context from the VS Code integrated terminal |

#### Example prompts

```text
@workspace find all places where heading hierarchy is documented

@github search community-access/accessibility-agents for issues labeled accessibility

@terminal what did the last command output mean?
```

### `#` Variables - Specific Context

| Variable | What It Attaches |
| ----------  | -----------------  |
| `#file` | Opens a file picker - attach any file from your workspace |
| `#selection` | Attaches your currently selected text |
| `#codebase` | Searches the full codebase for relevant snippets |
| `#terminalLastCommand` | Attaches the last terminal command and its output |

#### Example prompts

```text
Review #selection for heading hierarchy violations

Explain what #file does (then pick a file from the picker)

What does this error mean? #terminalLastCommand

Search #codebase for all screen reader navigation instructions
```


## 3. Chat Slash Commands

Type `/` in Copilot Chat to see the available built-in commands.

| Command | What It Does | Example |
| ---------  | -------------  | ---------  |
| `/explain` | Explains the selected code or text in plain language | Select a complex block → `/explain` |
| `/fix` | Suggests fixes for problems in the selected code | Select broken code → `/fix` |
| `/tests` | Generates unit tests for the selected function (code files) | Select a function → `/tests` |
| `/doc` | Generates documentation (JSDoc, docstring) for parsed code | Select a function → `/doc` |
| `/new` | Scaffolds a new file or project structure | `/new React component for notifications` |
| `/help` | Shows all available Copilot commands and participants | `/help` |
| `/clear` | Clears the current chat history | `/clear` |

### Workspace management slash commands

| Command | What It Does | Example |
| ---------  | -------------  | --------  |
| `/init` | Analyzes your workspace and auto-generates a `.github/copilot-instructions.md` tailored to your project | `/init` |
| `/savePrompt` | Saves the current chat conversation as a reusable `.prompt.md` slash command file | After a useful exchange, type `/savePrompt` |

**Note:** These are Copilot's built-in chat slash commands. Accessibility Agents adds 28 additional workspace-level slash commands from `.github/prompts/` - see [Appendix V](appendix-v-accessibility-agents-reference.md) for the full list.

### Using Slash Commands for Documentation Work

```text
Select a section of Markdown → /explain
→ Copilot explains the purpose and structure of that section

Select a complex code example → /explain
→ Copilot explains what the code does in plain language

Select a broken YAML template → /fix
→ Copilot suggests what is wrong and how to correct it
```


## 4. Chat Modes

Copilot Chat has four modes. Select the current mode from the dropdown at the bottom of the Chat input area.

| Mode | What It Does | Best For |
| ------  | -------------  | ----------  |
| **Ask** | Conversational Q&A. Copilot explains, suggests, and answers but does not directly edit files. | Questions, explanations, discussion, exploring ideas |
| **Edit** | You define a working set of files; Copilot proposes edits as a diff that you approve or reject. | Targeted, controlled multi-file edits |
| **Agent** | Copilot works autonomously - it decides which files to touch, reads/writes code, runs terminal commands. | Larger end-to-end tasks |
| **Plan** | Copilot writes an implementation plan first; no code is written until you approve the plan. (Public preview) | Complex features where you want to validate the approach first |

**Screen reader note:** The mode selector is in the Chat panel toolbar at the bottom. Tab through the bottom of the Chat view to find it. The current mode name is its accessible label. Press `Space` or `Enter` to open the dropdown.

**Model selection** is a separate control, also at the bottom of the Chat input. See [Appendix X: AI Models Reference](appendix-x-copilot-models.md) for a complete guide to choosing models.


## 5. Custom Instructions - All Levels

GitHub Copilot supports multiple ways to provide custom instructions. They differ by scope, priority, trigger mechanism, and which tools recognize them. This section documents every supported approach.


### 4A. Always-On Instructions - `.github/copilot-instructions.md`

**What it is:** The primary VS Code Copilot instruction file. Content is automatically included in every chat request and inline suggestion context - you never need to invoke it.

**When to use:** Project-wide conventions everyone on the team should follow: coding standards, documentation style, commit message format, tone, accessibility requirements.

**Location:** `.github/copilot-instructions.md` (fixed path; workspace-level only)

**Format:** Plain Markdown - no frontmatter, no special syntax required.

```markdown
# Copilot Instructions for accessibility-agents

## Accessibility Standards
- Include semantic HTML elements in generated markup
- Never use color as the only indicator of meaning
- Ensure all interactive elements are keyboard accessible

## Documentation Style
- Write for screen reader users first
- Use active voice and imperative mood
- Never skip heading levels (H1 → H2 → H3 only)

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

## Code Quality
- Prefer explicit over implicit
- Write self-documenting code; add comments only where logic is non-obvious
- Error handling must be intentional - no silent catch blocks
```

### Auto-generate with `/init`

1. Open Copilot Chat
2. Type `/init`
3. VS Code analyzes your workspace and generates a tailored `copilot-instructions.md`
4. Review and edit the result before committing


### 4B. Always-On Instructions - `AGENTS.md` (Multi-Tool / Monorepo)

**What it is:** An open standard instruction file recognized by multiple AI tools - GitHub Copilot, Claude Code, Gemini CLI, and others. Use this instead of `copilot-instructions.md` when you want one instruction file that works across all AI coding assistants.

**When to use:** Multi-tool teams, or when you want monorepo-level granularity where different subdirectories have different rules.

**Location:** `AGENTS.md` at the workspace root. For monorepos, also supported nested in subdirectories (closest file to the current directory wins).

```text
repo-root/
  AGENTS.md               ← applies everywhere
  frontend/
    AGENTS.md             ← overrides root for frontend/ and below
  backend/
    AGENTS.md             ← overrides root for backend/ and below
```

**Enable nested files:** In VS Code settings, set `chat.useNestedAgentsMdFiles: true`.

**Enable/disable AGENTS.md:** Set `chat.useAgentsMdFile: true` (default: on).

**Format:** Identical to `copilot-instructions.md` - plain Markdown, no frontmatter.

**Rule:** Choose either `copilot-instructions.md` OR `AGENTS.md` for your project - not both.


### 4C. Always-On Instructions - `CLAUDE.md` (Cross-Tool Compatibility)

**What it is:** Instructions file originally from Claude Code that VS Code Copilot also recognizes. Useful when your team uses both.

**When to use:** Mixed AI tool environments where Claude Code and VS Code Copilot are both used. Uses the same format as the other always-on files.

#### Supported locations

| File | Scope | Committed? |
| ------  | -------  | -----------  |
| `CLAUDE.md` (workspace root) | All requests in workspace | Yes |
| `.claude/CLAUDE.md` | All requests in workspace | Yes |
| `CLAUDE.local.md` (workspace root) | All requests; local only | No - gitignored |
| `~/.claude/CLAUDE.md` | All workspaces; user-level | Personal |

**Enable/disable:** Set `chat.useClaudeMdFile: true` (default: on).

**Claude Rules format** (for `.claude/rules/` and `~/.claude/rules/`):

Use `.instructions.md` files under `.claude/rules/` using `paths:` instead of `applyTo:` for glob matching:

```markdown
description: "Python coding standards"
paths: ["**/*.py"]

Follow PEP 8. Use type hints on all function signatures.
Write docstrings for all public functions and classes.
```


### 4D. Conditional / Scoped Instructions - `.instructions.md`

**What it is:** Instructions that apply only when specific file types or folders are involved in the chat. More targeted than always-on instructions.

**When to use:** Language-specific rules (Python style, TypeScript patterns), framework conventions, folder-specific standards (docs/, tests/, src/api/).

#### Locations

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

#### Frontmatter

```yaml
name: "Display Name"          # Optional - shown in UI and diagnostics; defaults to filename
description: "Use when..."    # Optional - enables on-demand matching; make keyword-rich
applyTo: "**/*.py"            # Optional glob - auto-attach when matching files are in context
```

#### `applyTo` glob patterns

```yaml
applyTo: "**"                            # Always included (careful - applies to everything)
applyTo: "**/*.py"                       # All Python files
applyTo: "**/*.{ts,tsx}"                 # TypeScript and TSX
applyTo: "docs/**"                       # Everything under docs/
applyTo: ["src/**", "lib/**"]            # Multiple patterns - OR logic
applyTo: "**/*.test.{js,ts}"            # Test files only
applyTo: ".github/ISSUE_TEMPLATE/**"    # Issue template files only
```

#### How files are triggered

| Discovery Mode | How It Works |
| ---------------  | -------------  |
| **Automatic** (via `applyTo`) | Instruction loads automatically when a matching file is in the chat context |
| **On-demand** (via `description`) | Agent detects from the description that this instruction is relevant to the task |
| **Manual** | User selects "Add Context → Instructions" in the Chat panel |

#### Example - test file conventions

```markdown
name: "Test File Standards"
description: "Use when writing, generating, or reviewing test files. Covers test structure, naming, and coverage expectations."
applyTo: "**/*.test.{js,ts}"

# Test Standards

- Use `describe`/`it` structure (not `test()` directly)
- Test names must describe behavior: "returns null when input is empty" not "test case 1"
- Each `it` tests exactly one behavior
- Include at least one edge case and one error case per function
- Avoid snapshot tests for logic; use explicit assertions
- Mock external dependencies; do not test third-party libraries
```

## Create an instructions file

- `Ctrl+Shift+P` → "Chat: New Instructions File" → choose scope (Workspace or User)
- Or create the file manually in `.github/instructions/`


### 4E. Organization-Level Instructions (GitHub Enterprise and Teams)

**What it is:** Organization administrators define custom instructions that apply to all repositories in the organization. Every team member automatically gets these instructions added to their Copilot context.

**Priority:** Lowest - workspace and user instructions both override these. However, they are additive - they are appended to, not replacing, other instructions.

#### Requirements

- GitHub Enterprise or Teams plan with Copilot enabled
- Admin configures instructions in organization settings on GitHub.com
- Each user must enable discovery in VS Code:

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

**Use for:** Organization-wide coding standards, security policies, legal disclaimers (open source license obligations), toolchain conventions.


### 4F. Settings-Based Instructions (Deprecated - Use Files Instead)

> **Note:** These settings-based instructions are deprecated and may be removed in a future VS Code release. For new work, use `copilot-instructions.md` or `.instructions.md` files.

VS Code settings can inject instructions for specific task types:

```json
// settings.json (workspace .vscode/settings.json or user settings)
{
  "github.copilot.chat.codeGeneration.instructions": [
    { "text": "Always add JSDoc comments to exported functions." },
    { "file": ".github/instructions/code-style.instructions.md" }
  ],
  "github.copilot.chat.testGeneration.instructions": [
    { "text": "Use describe/it structure. Include edge cases." }
  ],
  "github.copilot.chat.reviewSelection.instructions": [
    { "text": "Check for WCAG 2.2 Level AA compliance in HTML markup." }
  ],
  "github.copilot.chat.commitMessageGeneration.instructions": [
    { "text": "Use conventional commits: type(scope): description" }
  ]
}
```

Each setting accepts an array of `{ text: "..." }` (inline) or `{ file: "relative/path.md" }` (from file).


### 4G. Comparison - When to Use Each Approach

| Approach | Scope | Always-on? | Multi-tool? | Best For |
| ----------  | -------  | ------------  | -------------  | ---------  |
| `copilot-instructions.md` | Workspace | Yes | VS Code only | Primary project instructions |
| `AGENTS.md` | Workspace + monorepo | Yes | All AI tools | Multi-tool teams or large monorepos |
| `CLAUDE.md` | Workspace + user | Yes | Copilot + Claude | Claude Code compatibility |
| `.instructions.md` | Workspace or user | Conditional | VS Code only | Scoped rules for file types |
| Organization setting | All repos in org | Yes | GitHub Copilot | Org-wide policy |
| Settings-based | Workspace or user | Per-task | VS Code only | Deprecated - avoid for new work |


## 6. Accessible View Workflow

Copilot Chat responses stream in token by token, which can fragment screen reader announcements. **Accessible View** (`Alt+F2`) gives you a complete, static, properly structured version of the response.

### Recommended Workflow - Every Copilot Interaction

```text
1. Open Copilot Chat: Ctrl+Shift+I
2. Type your prompt
3. Press Ctrl+Enter to send
4. Press Alt+F2 to open Accessible View (open immediately - no need to wait)
5. Follow as the response streams in the Accessible View in real-time
6. Read or re-read any part with Arrow keys at your own pace
7. Press Escape to close Accessible View
```

> **VS Code December 2025:** The Accessible View now streams dynamically. You can open it immediately after sending a prompt and follow the response as it arrives - no need to wait for the response to finish before pressing `Alt+F2`.

### Why Accessible View Is Better for Screen Reader Users

| Without Accessible View | With Accessible View (`Alt+F2`) |
| ------------------------  | --------------------------------  |
| Responses announced in fragments as tokens arrive | Full, complete response in one readable pane |
| Live region updates may interrupt or overlap | No streaming, no live region noise |
| Difficult to re-read specific sections | Navigate with `Up/Down Arrow` at your own pace |
| Context can be lost in streaming | Full context preserved from start to finish |
| Code blocks may run together | Code blocks formatted as `<pre>` elements, line-by-line |

### Screen Reader Navigation in Accessible View

#### NVDA / JAWS

- `Up/Down Arrow` - read line by line
- `Ctrl+Home` - jump to start
- `H` - navigate by headings (if response has sections)
- `Escape` - close Accessible View, return to Chat

#### VoiceOver

- `VO+Shift+Down` - interact with the Accessible View content
- `Down Arrow` - read line by line
- `VO+Escape` - stop interacting
- `Escape` - close Accessible View

### Accessible View for Inline Suggestions

When a multi-line ghost text suggestion appears in the editor:

```text
1. Do not accept immediately
2. Press Alt+F2
3. Accessible View shows: "Suggestion: [full text]"
4. Read the complete suggestion at your own pace
5. Press Escape to close
6. Press Tab to accept, or Escape to reject
```

This is especially important for multi-line suggestions where ghost text is hard to review incrementally.

### Accessible View for Code Blocks

- Code blocks appear inside `<pre>` elements in Accessible View
- Screen readers announce "code block" or "pre-formatted text" at the start
- Each line is on its own line (not run together)
- Indentation is preserved


## 7. Configuration Scope Reference

Every Copilot customization file lives at one of three scopes. VS Code **combines all** matching files from all scopes - it is additive, not winner-takes-all.

### Workspace (Repository) - Team-Shared

Files committed to your repository. Everyone who clones the repo gets them.

| File Type | Location |
| -----------  | ----------  |
| Always-on instructions | `.github/copilot-instructions.md` |
| Always-on (multi-tool) | `AGENTS.md` (root), `<folder>/AGENTS.md` (nested) |
| Always-on (Claude compat) | `CLAUDE.md`, `.claude/CLAUDE.md` |
| Local only (not committed) | `CLAUDE.local.md`, `.claude/settings.local.json` |
| Scoped instructions | `.github/instructions/*.instructions.md` |
| Claude rules (scoped) | `.claude/rules/*.instructions.md` |
| Custom agents | `.github/agents/*.agent.md` |
| Prompts / slash commands | `.github/prompts/*.prompt.md` |
| Agent skills | `.github/skills/<name>/SKILL.md` |
| Hooks (team-shared) | `.github/hooks/*.json` |
| Claude hooks/settings | `.claude/settings.json` |
| Personal preferences | `.github/agents/preferences.md` (gitignored) |

### User / Personal - Follows You Across Workspaces

Files in your VS Code profile folder. Syncs with Settings Sync. Available in every workspace you open.

**Path on Windows:** `C:\Users\<you>\AppData\Roaming\Code - Insiders\User\prompts\`
**Path on macOS:** `~/Library/Application Support/Code - Insiders/User/prompts/`

| File Type | Location |
| -----------  | ----------  |
| Instructions | `<profile>/prompts/*.instructions.md` |
| Agents | `<profile>/prompts/*.agent.md` |
| Prompts | `<profile>/prompts/*.prompt.md` |
| Claude instructions | `~/.claude/CLAUDE.md` |
| Claude rules | `~/.claude/rules/*.instructions.md` |
| Claude settings | `~/.claude/settings.json` |
| Agent skills | `~/.copilot/skills/<name>/`, `~/.agents/skills/<name>/`, `~/.claude/skills/<name>/` |

### Organization - GitHub-Configured (Enterprise/Teams)

Configured by administrators in GitHub organization settings. Automatically applied to all organization members.

- Enable discovery: `github.copilot.chat.organizationInstructions.enabled: true`
- Lowest priority - workspace and user instructions override when there is a conflict


## 8. Instruction Priority and Conflicts

When multiple instruction sources give conflicting guidance, VS Code uses this priority order:

```text
1. Personal / User-level    - HIGHEST - overrides all others
2. Workspace / Repository   - middle priority
3. Organization-level       - LOWEST - overridden by workspace and user
```

**Important:** This priority applies to conflicts. All non-conflicting instructions from all scopes are combined and sent together. More instructions is not a problem - Copilot handles them additively.

### How Instructions Are Combined

Say you have:

- Organization: "Use British English spellings"
- Workspace: "Use TypeScript strict mode"
- User: "Use British English spellings - but use Z spellings (organize, not organise) for technical terms"

Result: Copilot follows TypeScript strict mode (from workspace), British English (from org), AND the Z-spelling override (from user, which overrides the org instruction on that specific point).

### Priority Within the Same Scope

Within a single scope (e.g., workspace), all matching instructions files are combined with no inherent priority. If two workspace-level `.instructions.md` files contradict each other, the behavior is undefined - avoid conflicting workspace instructions.


## 9. All File Types Quick Reference

| Purpose | File Name Pattern | Location | How It Activates |
| ---------  | ------------------  | ----------  | -----------------  |
| Always-on instructions | `copilot-instructions.md` | `.github/` | Automatic - every request |
| Always-on (multi-tool) | `AGENTS.md` | Repo root or subfolders | Automatic - every request |
| Always-on (Claude compat) | `CLAUDE.md` | Repo root, `.claude/`, `~/.claude/` | Automatic - every request |
| Scoped instructions | `*.instructions.md` | `.github/instructions/`, profile folder | Auto (via `applyTo`) or on-demand |
| Claude scoped rules | `*.instructions.md` | `.claude/rules/`, `~/.claude/rules/` | Auto (via `paths:`) or on-demand |
| Custom agents | `*.agent.md` | `.github/agents/`, profile folder | `@agent-name` in Chat |
| Prompt / slash command | `*.prompt.md` | `.github/prompts/`, profile folder | `/command-name` in Chat |
| Agent skill | `SKILL.md` in named folder | `.github/skills/<name>/`, profile folder | `/skill-name` or auto on-demand |
| Lifecycle hook | `*.json` | `.github/hooks/`, `.claude/settings*.json` | Automatic at lifecycle events |
| Personal preferences | `preferences.md` | `.github/agents/` (gitignored) | Read by agents when mentioned |

### Create any new customization file

`Ctrl+Shift+P` → "Chat: New Instructions File" (or "New Prompt File", "New Agent File")


## 10. VS Code Settings Reference

All Copilot customization-related settings. Set in VS Code Settings (`Ctrl+,`) or `settings.json`.

### Core Instruction Settings

| Setting | Default | Description |
| ---------  | ---------  | -------------  |
| `chat.instructionsFilesLocations` | - | Array of additional folder paths to search for `*.instructions.md` files |
| `chat.useAgentsMdFile` | `true` | Enable/disable `AGENTS.md` recognition |
| `chat.useClaudeMdFile` | `true` | Enable/disable `CLAUDE.md`/`CLAUDE.local.md` recognition |
| `chat.useNestedAgentsMdFiles` | `false` | Enable subfolder `AGENTS.md` hierarchy for monorepos |
| `chat.includeApplyingInstructions` | `true` | Apply instructions files whose `applyTo` pattern matches current files |
| `chat.includeReferencedInstructions` | `true` | Apply instruction files referenced via Markdown links in chat |
| `chat.restoreLastPanelSession` | `true` | Restore the previous chat session when VS Code starts; set to `false` to always start with an empty Chat |
| `chat.useAgentSkills` | `false` | Enable Agent Skills (experimental) - allows `.github/skills/<name>/SKILL.md` bundles to be discovered and invoked |

### Organization Instructions

| Setting | Default | Description |
| ---------  | ---------  | -------------  |
| `github.copilot.chat.organizationInstructions.enabled` | `false` | Enable discovery of organization-level custom instructions |

### Deprecated Task-Specific Instructions

> Prefer file-based instructions over these settings for new work.

| Setting | What It Augments |
| ---------  | -----------------  |
| `github.copilot.chat.codeGeneration.instructions` | All code generation |
| `github.copilot.chat.testGeneration.instructions` | Test file generation |
| `github.copilot.chat.reviewSelection.instructions` | Code review via Chat |
| `github.copilot.chat.commitMessageGeneration.instructions` | Git commit messages |

Each accepts an array with items: `{ "text": "..." }` (inline) or `{ "file": "relative/path" }` (from file).

### Settings Sync

To sync your personal prompts, instructions, and agents across devices:

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

Your personal `*.instructions.md`, `*.agent.md`, and `*.prompt.md` files will sync to all signed-in VS Code instances.


## 11. Diagnostics and Troubleshooting

### View All Loaded Customizations

To see which instruction files, agents, prompts, and skills are currently loaded - and check for errors:

1. **Configure Chat Gear:** Click the gear () icon in the Copilot Chat header → "Diagnostics"
2. **Right-click method:** Right-click in the Chat view → "Diagnostics"

The Diagnostics panel shows:

- All agents found and whether they loaded successfully
- All prompt/instruction files and their source (workspace vs user vs organization)
- All skills and their discovery status
- Any parse errors or invalid frontmatter

### Common Issues

#### `copilot-instructions.md` not being followed

1. Confirm the file is at exactly `.github/copilot-instructions.md` (relative to workspace root)
2. Check the file is plain Markdown with no frontmatter syntax errors
3. Open Diagnostics to confirm it appears in the loaded files list
4. Some instructions work better with specific phrasing; use imperative mood ("Always use...")

#### `.instructions.md` file not loading automatically

1. Verify `chat.includeApplyingInstructions` is not set to `false`
2. Check the `applyTo` glob - test with `"**"` temporarily to confirm the file loads at all
3. Confirm the file is in `.github/instructions/` or a folder listed in `chat.instructionsFilesLocations`
4. File extension must be `.instructions.md` exactly - not `.md`, not `.instruction.md`

#### Custom agent (`@agent-name`) not appearing

1. File must be named `<agent-name>.agent.md` and placed in `.github/agents/`
2. Check YAML frontmatter for syntax errors - use a YAML validator
3. Confirm `user-invocable` is not set to `false` (which hides it from the picker)
4. Run `Ctrl+Shift+P` → "Reload Window" after any changes to agent files

#### Slash command (`/command`) not appearing

1. File must be at `.github/prompts/<command-name>.prompt.md`
2. Extension must be `.prompt.md` exactly
3. Reload VS Code: `Ctrl+Shift+P` → "Reload Window"

#### Instructions from different files conflicting

1. Open Diagnostics to see all loaded instruction files
2. Remove or edit conflicting instructions - they are not automatically de-duplicated
3. User-level instructions override workspace instructions for the same topic

#### `chat.instructionsFilesLocations` not working

- Path must be a folder path, not a file path
- Use forward slashes or escaped backslashes
- Relative paths are relative to the workspace root


## Quick Reference Card

### Opening Copilot

| What | Windows / Linux | macOS |
| ------  | ----------------  | -------  |
| Chat panel | `Ctrl+Shift+I` | `Cmd+Shift+I` |
| Inline chat (in file) | `Ctrl+I` | `Cmd+I` |
| Quick Chat (floating) | `Ctrl+Shift+Alt+I` | `Cmd+Shift+Ctrl+I` |

### Reading Copilot Responses

| What | How |
| ------  | -----  |
| Complete response (streams live in Accessible View) | `Alt+F2` - open anytime, including while response is still generating |
| Close Accessible View | `Escape` |
| Read current inline suggestion | `Alt+F2` while ghost text is showing |

### Accepting/Rejecting Suggestions

| What | Windows / Linux | macOS |
| ------  | ----------------  | -------  |
| Accept | `Tab` | `Tab` |
| Reject | `Escape` | `Escape` |
| Accept word by word (recommended) | `Ctrl+Right Arrow` | `Cmd+Right Arrow` |
| Next suggestion | `Alt+]` | `Option+]` |
| Previous suggestion | `Alt+[` | `Option+[` |
| Open full suggestion list | `Ctrl+Enter` | `Cmd+Enter` |
| Open suggestion in Accessible View | `Alt+F2` | `Option+F2` |
| Insert from Accessible View at cursor | `Ctrl+/` | `Cmd+/` |

### Instructions Management

| What | How |
| ------  | -----  |
| Auto-generate instructions from workspace | Type `/init` in Chat |
| New instructions file | `Ctrl+Shift+P` → "Chat: New Instructions File" |
| New prompt/slash command file | `Ctrl+Shift+P` → "Chat: New Prompt File" |
| Configure instructions | `Ctrl+Shift+P` → "Chat: Configure Instructions" |
| View all loaded files and errors | Chat gear → Diagnostics |



## 12. Screen Reader Workflow - Official Guide

> Source: [accessibility.github.com/documentation/guide/github-copilot-vsc/](https://accessibility.github.com/documentation/guide/github-copilot-vsc/)
>
> **Contributors:** @mlama007, zersiax  |  **Community:** [GitHub Accessibility Discussions](https://github.com/orgs/community/discussions/categories/accessibility)

### Prerequisites

- VS Code with **GitHub Copilot Chat** extension installed
- A GitHub account with Copilot access (Free tier or paid)
- A screen reader (NVDA recommended for this guide)

### Step 1: Enable VS Code Screen Reader Mode

1. Press `Shift+Alt+F1` to toggle Screen Reader Accessibility Mode
2. Or use Command Palette: `Ctrl+Shift+P` → "Toggle Screen Reader Accessibility Mode"
3. VS Code announces: "Screen Reader Accessibility Mode enabled"

When Screen Reader Mode is on, VS Code changes how it announces suggestions (full text instead of streaming), adjusts live regions, and enables accessible navigation patterns throughout the editor.

### Step 2: Configure Accessibility Signals (Optional but Recommended)

1. Open Settings: `Ctrl+,`
2. Search "accessibility signals"
3. Enable the Copilot-specific signals:

| Signal Setting | What It Signals |
| -------------------  | -----------------  |
| `accessibility.signals.lineHasInlineSuggestion` | A suggestion is available on the current line |
| `accessibility.signals.chatRequestSent` | Your prompt has been sent |
| `accessibility.signals.chatResponsePending` | Copilot is generating a response |
| `accessibility.signals.chatResponseReceived` | Response is complete and ready to read |

Recommended JSON config for Copilot accessibility signals:

```json
{
  "accessibility.signals.lineHasInlineSuggestion": "on",
  "accessibility.signals.chatRequestSent": "on",
  "accessibility.signals.chatResponsePending": "auto",
  "accessibility.signals.chatResponseReceived": "on"
}
```

### Step 3: Official Shortcut Table (from accessibility.github.com)

This is the complete table of Copilot screen reader shortcuts as published by the GitHub Accessibility team:

| Action | Shortcut |
| --------  | ----------  |
| Accept Inline Suggestion | `Tab` |
| Dismiss Inline Suggestion | `Escape` |
| Show next suggestion in Suggestions Panel | `Alt+]` |
| Show previous suggestion in Suggestions Panel | `Alt+[` |
| Open GitHub Copilot Suggestions (loads ~10 suggestions side by side) | `Ctrl+Enter` |
| Opens suggestion in Accessible View panel | `Alt+F2` |
| Inserts suggestion from Accessible View at cursor | `Ctrl+/` |
| Opens Inline Chat (in-file, at cursor) | `Ctrl+I` |
| Opens dedicated Chat view | `Ctrl+Shift+I` |

### Step 4: Recommended Workflow for Inline Suggestions

#### The screen reader-optimized workflow for every inline suggestion

```text
1. Type your code or documentation
2. Copilot generates a suggestion (audio cue sounds if enabled)
3. DO NOT press Tab immediately
4. Press Alt+F2 - Accessible View opens with the full suggestion text
5. Read the suggestion at your own pace with Arrow keys
6. Decision:
   a. Insert it: Press Ctrl+/ - suggestion is inserted at cursor position
   b. Skip it: Press Escape to close Accessible View, then Escape again to dismiss
   c. See alternatives: Close Accessible View, press Alt+] for next suggestion
```

This workflow avoids the streaming announcement problem (where suggestions are read out in fragments as tokens arrive) and gives you full, uninterrupted access to the suggestion text before committing.

### Step 5: Recommended Workflow for Chat Responses

```text
1. Open Chat: Ctrl+Shift+I
2. Type your prompt, press Ctrl+Enter to send
3. Press Alt+F2 - Accessible View opens immediately; the response streams live into it
4. Navigate with Arrow keys - no streaming noise, follow along in real-time
5. Headings, code blocks, and lists are fully structured
6. Press Escape to close - focus returns to Chat input
```

### Reading the Suggestions Panel (Ctrl+Enter)

Pressing `Ctrl+Enter` opens a **Suggestions Panel** - a separate editor tab that shows up to 10 alternative suggestions simultaneously. This is useful when the default suggestion isn't quite right and you want to compare options.

```text
1. Ctrl+Enter - opens "GitHub Copilot" editor tab
2. Screen Reader Mode is active: navigate with Browse Mode
3. H key to navigate headings (each suggestion may be under a heading)
4. Press Alt+F2 on a focused suggestion to read it in Accessible View
5. Tab to "Accept" button for a suggestion you want to use
6. Close the tab when done (Ctrl+W)
```

### Resources

| Resource | URL |
| ----------  | -----  |
| VS Code Copilot Cheat Sheet | [code.visualstudio.com/docs/copilot/reference/copilot-vscode-features](https://code.visualstudio.com/docs/copilot/reference/copilot-vscode-features) |
| VS Code Accessibility Features | [code.visualstudio.com/docs/editor/accessibility](https://code.visualstudio.com/docs/editor/accessibility) |
| GitHub Accessibility Discussions | [github.com/orgs/community/discussions/categories/accessibility](https://github.com/orgs/community/discussions/categories/accessibility) |
| Official screen reader guide | [accessibility.github.com/documentation/guide/github-copilot-vsc/](https://accessibility.github.com/documentation/guide/github-copilot-vsc/) |
| Optimizing Copilot with custom instructions (accessibility) | [accessibility.github.com/documentation/guide/copilot-instructions/](https://accessibility.github.com/documentation/guide/copilot-instructions/) |
| 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/) |


## 13. awesome-copilot - Plugin Ecosystem

**awesome-copilot** is a GitHub repository (`github/awesome-copilot`) - not a VS Code Marketplace extension. It is GitHub's curated ecosystem of Copilot plugins, prompts, instructions, agents, skills, and hooks that can be shared and discovered by anyone.

> **Stars:** 21.6k  |  **Forks:** 2.5k  |  **Contributors:** 247+  |  **Repository:** [github.com/github/awesome-copilot](https://github.com/github/awesome-copilot)

### Repository Structure

| Directory | Contents |
| -----------  | ----------  |
| `prompts/` | Community-contributed `.prompt.md` slash command files |
| `instructions/` | Community-contributed `.instructions.md` guidance files |
| `agents/` | Community-contributed `.agent.md` agent definitions |
| `plugins/` | Community-contributed plugin packages (MCP and CLI) |
| `skills/` | Community-contributed `SKILL.md` bundles |
| `hooks/` | Community-contributed lifecycle hook `.json` configs |
| `cookbook/` | Worked examples and usage patterns |

**LLM discovery:** `https://github.github.io/awesome-copilot/llms.txt` - a machine-readable index of all available resources.


### The `/plugin` Command - Browse and Install from Chat

The easiest way to explore awesome-copilot from VS Code:

1. Open Copilot Chat (`Ctrl+Shift+I`)
2. Type `/plugin` and press `Enter`
3. Copilot Chat opens an interactive plugin marketplace browser
4. Browse plugins by category, read descriptions, and install with a single command

#### Key plugins available via `/plugin`

| Plugin | What It Does |
| --------  | -------------  |
| **Awesome Copilot** | The meta-plugin - browse and install any resource from the full ecosystem |
| **Copilot SDK** | Official SDK for C#, Go, Node.js, and Python development patterns |
| **Partners** | 20+ partner agents from Azure, JetBrains, MongoDB, and others |


### CLI Plugin Installation

From any terminal with GitHub CLI (`gh`) installed:

```bash
# Browse the marketplace
gh copilot plugin marketplace list

# Add the awesome-copilot collection
gh copilot plugin marketplace add github/awesome-copilot

# Install a specific plugin
gh copilot plugin install @awesome-copilot/accessibility-toolkit

# List what you have installed
gh copilot plugin list
```


### MCP Server Integration (Docker required)

awesome-copilot also ships as an **MCP (Model Context Protocol) Server** - a Docker-based tool server that extends Copilot with additional capabilities beyond file-based customizations.

Install in VS Code by clicking the button at `https://aka.ms/awesome-copilot/mcp/vscode`, or add manually to `settings.json`:

```json
{
  "mcp": {
    "servers": {
      "awesome-copilot": {
        "type": "stdio",
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "ghcr.io/github/awesome-copilot-mcp:latest"
        ]
      }
    }
  }
}
```

**Also available for:** VS Code Insiders and Visual Studio.

> **Screen reader note:** The install buttons on the awesome-copilot page are standard links. Navigate with `K` in Browse Mode to find them. Each is labeled with the target IDE.


### awesome-copilot vs. Accessibility Agents

| Feature | Accessibility Agents (`.github/agents/`) | awesome-copilot |
| ---------  | --------------------------------  | ----------------  |
| **Scope** | Your repo and fork | Community-wide ecosystem |
| **Distribution** | Clone the repo; agents travel with it | Plugin marketplace - install on demand |
| **Customization** | Edit `.agent.md` files directly | Use as-is or fork and modify |
| **Storage** | Your version-controlled repository | GitHub-hosted public repository |
| **Best for** | Project-specific workflows | Reusable templates and cross-project tools |


## 14. GitHub Agentic Workflows - Agents in the Cloud

> **Status: Technical Preview** - GitHub Agentic Workflows entered technical preview on **February 13, 2026**. The feature is in early development and may change significantly. Use with careful human supervision. See the [official documentation](https://github.github.com/gh-aw/) and [source repository](https://github.com/github/gh-aw) (open source, MIT).

**GitHub Agentic Workflows** run AI coding agents as part of GitHub Actions pipelines - no VS Code, no local setup required. The key differentiator: you write automation goals in **plain Markdown**, and the `gh aw` CLI compiles them into standard GitHub Actions workflows. The AI agent interprets your natural language description and executes the task.

### What This Enables

| Workflow Category | Trigger | Example |
| ------------------  | ---------  | ---------  |
| Issue & PR Management | `issues: opened` | Auto-triage, label, and assign new issues |
| Continuous Documentation | `push` to main | Keep README and docs in sync with code changes |
| Metrics & Analytics | `schedule: daily` | Daily status report posted as a new issue |
| Quality & Testing | `pull_request` | CI failure analysis posted as PR comment |
| Continuous Improvement | `schedule: weekly` | Automated refactoring and code simplification PRs |
| Multi-Repository | `workflow_dispatch` | Sync features and track changes across repos |

Browse 50+ community-built workflows at [Peli's Agent Factory](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/).

### How It Works

The `gh aw` CLI (a `gh` extension) compiles `.md` workflow files into `.lock.yml` GitHub Actions workflows:

```text
.github/workflows/daily-report.md  ← you write this (Markdown + frontmatter)
        ↓  gh aw compile
.github/workflows/daily-report.lock.yml  ← generated, runs as standard GitHub Actions
```

The AI agent (GitHub Copilot, Claude, or OpenAI Codex) reads your repository context and the natural language instructions, then performs the task using the GitHub MCP Server and other available tools.

### Workflow Format - Markdown with Frontmatter

Unlike standard GitHub Actions (YAML), agentic workflows are Markdown files:

```markdown
on:
  schedule: daily
permissions:
  contents: read
  issues: read
  pull-requests: read
safe-outputs:
  create-issue:
    title-prefix: "[team-status] "
    labels: [report, daily-status]
    close-older-issues: true

## Daily Issues Report

Create an upbeat daily status report for the team as a GitHub issue.

## What to include

- Recent repository activity (issues, PRs, discussions, releases, code changes)
- Progress tracking, goal reminders and highlights
- Project status and recommendations
- Actionable next steps for maintainers
```

The body is natural language - describe what you want the AI agent to do. The frontmatter controls triggers, permissions, and what write operations are allowed.

### Key Frontmatter Properties

| Property | Purpose |
| ----------  | ---------  |
| `on: schedule: daily` | Runs once per day (also: `weekly`, `cron` expressions, `issues: opened`, `pull_request`) |
| `on: issue_comment: created` | Trigger from a comment command in an issue or PR |
| `on: workflow_dispatch` | Manual run via the Actions tab "Run workflow" button |
| `permissions:` | Read-only scopes by default - only request what you need |
| `safe-outputs:` | Pre-approved write operations (e.g., `create-issue`, `pr-comment`) - the security guardrail |

### Security Model - "Safe Outputs"

Workflows run **read-only by default** with sandboxed execution, network isolation, and SHA-pinned dependencies. Write operations require explicit declaration in `safe-outputs` - a set of pre-approved, sanitized GitHub operations. There is no arbitrary filesystem or API write access.

This means: the AI agent cannot push code, delete branches, or modify arbitrary files unless you explicitly declare those `safe-outputs` and they are on the approved list.

### Supported AI Engines

| Engine | Notes |
| --------  | -------  |
| GitHub Copilot CLI | Default engine |
| Claude (Anthropic) | Alternative engine |
| OpenAI Codex | Alternative engine |
| Custom agents | Bring your own coding agent |

### Getting Started with `gh aw`

```bash
# Install the CLI extension
gh extension install github/gh-aw

# Create a new workflow interactively (from github.com or VS Code also works)
gh aw create

# Compile your Markdown workflow to a GitHub Actions .lock.yml
gh aw compile .github/workflows/daily-report.md

# Commit both the .md and .lock.yml files - GitHub Actions runs the .lock.yml
```

### Monitoring Agentic Workflow Runs

1. Navigate to the **Actions** tab of your repository (`D` → Repository navigation → `K` to Actions)
2. Find the workflow by name (h3 headings, navigate with `3`)
3. Press `Enter` to open a specific run
4. Expand job steps to read the agent output log and any safe-outputs created

### Resources

| Resource | URL |
| ----------  | -----  |
| Official documentation | `github.github.com/gh-aw/` |
| Source repository (open source) | `github.com/github/gh-aw` |
| Peli's Agent Factory (50+ examples) | `github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/` |
| Community feedback & discussion | `github.com/orgs/community/discussions/186451` |
| Changelog announcement (Feb 13, 2026) | `github.blog/changelog/2026-02-13-github-agentic-workflows-are-now-in-technical-preview` |

> **Relationship to Accessibility Agents:** Accessibility Agents agents (`.agent.md` files) are designed for interactive use inside VS Code. GitHub Agentic Workflows are a separate, cloud-native system that uses its own Markdown workflow format and the `gh aw` CLI - they are complementary tools, not the same mechanism. See [Appendix V](appendix-v-accessibility-agents-reference.md) for the full Accessibility Agents reference.


*Chapter: [GitHub Copilot](13-github-copilot.md)*
*Related: [Appendix V: Accessibility Agents Reference](appendix-v-accessibility-agents-reference.md) | [Appendix M: VS Code Accessibility Reference](appendix-m-vscode-accessibility-reference.md) | [Appendix X: AI Models Reference](appendix-x-copilot-models.md)*