GitHub Repository: microsoft/vscode
Path: blob/main/src/vs/sessions/copilot-customizations-spec.md
¹³³⁸³ views

Copilot Agent Runtime — Customization Surface Spec

Purpose: Definitive reference for every customization mechanism that affects agent behavior when a user sends a message. Intended for building a UI that collects all customizations into a single view.
Source: github/copilot-agent-runtime codebase as of 2026-02-25.

Some information has been removed by the human compiling this spec, scoping to what is deemed most relevant for the agent sessions window implementation. For the full details, see the source code (for maintainers likely checked out side-by-side).

Overview

When a user sends a message, the agent assembles its behavior from 10 customization categories, each discovered from well-known file paths, environment variables, or runtime APIs. This document enumerates every source, file pattern, and merge rule.

1. Instructions

System-prompt additions that shape how the agent responds. Multiple sources are discovered and merged in priority order.

1.1 Repo-Level Instruction Files

Each pattern is defined in src/helpers/repo-helpers.ts → instructionPatterns:

Convention	File Pattern	Notes
Copilot	`{repo}/.github/copilot-instructions.md`	Primary repo instructions
Codex / OpenAI	`{repo}/AGENTS.md`	OpenAI model convention
Claude / Anthropic	`{repo}/CLAUDE.md`	Claude model convention
Claude (alt)	`{repo}/.claude/CLAUDE.md`	Secondary Claude location
Gemini / Google	`{repo}/GEMINI.md`	Gemini model convention

1.2 VSCode-Style Instruction Files

Glob-matched instruction files with metadata (applyTo patterns, description).

Scope	File Pattern	Code Reference
Repo	`{repo}/.github/instructions/*/.instructions.md`	`readVSCodeInstructions()`
User	`~/.copilot/instructions/*/.instructions.md`	`readUserCopilotInstructions()`

1.3 User-Level Instructions

Scope	File Pattern	Code Reference
User global	`~/.copilot/copilot-instructions.md`	`hasHomeCopilotInstructions()`

1.4 CWD-Specific Instructions

When the working directory differs from the repo root, the same instruction patterns are re-checked relative to {cwd}:

{cwd}/.github/copilot-instructions.md
{cwd}/CLAUDE.md, {cwd}/.claude/CLAUDE.md
{cwd}/AGENTS.md
{cwd}/GEMINI.md

1.5 Nested / Child Instructions

Breadth-first traversal from {cwd} up to 2 levels deep (CHILD_INSTRUCTIONS_MAX_DEPTH = 2), scanning all instruction patterns in subdirectories.

Ignored directories: node_modules, .git, vendor, dist, build, .next, .nuxt, out, coverage (plus .gitignore patterns when available).

Feature-gated via enableChildInstructions option.

1.6 Additional Sources

Source	Mechanism
Env var	`COPILOT_CUSTOM_INSTRUCTIONS_DIRS` — comma-separated list of additional directories to scan
Organization	`RuntimeContext.organizationCustomInstructions` — injected at runtime via API (not file-based)

1.7 Merge Order

Instructions are concatenated in this order (all additive):

User global (~/.copilot/copilot-instructions.md)
Repo-level instruction files (all patterns above)
VSCode-style instruction files (repo, then user)
CWD-specific overrides (when cwd ≠ repo root)
Child/nested instructions
Organization instructions (API-injected)

Duplicate content is deduplicated by file content hash.

2. Skills

Reusable prompt-based capabilities exposed as /skill-name slash commands.

2.1 Discovery Paths

Source	File Pattern	Code Reference
Repo (Copilot)	`{repo}/.github/skills/*/SKILL.md`	`loader.ts` collectProjectDirs
Repo (Agents)	`{repo}/.agents/skills/*/SKILL.md`	`loader.ts` collectProjectDirs
Repo (Claude)	`{repo}/.claude/skills/*/SKILL.md`	`loader.ts` collectProjectDirs
User (Copilot)	`~/.copilot/skills/*/SKILL.md`	`loader.ts` personalDirs
User (Claude)	`~/.claude/skills/*/SKILL.md`	`loader.ts` personalDirs
Env var	Dirs listed in `COPILOT_SKILLS_DIRS` (comma-separated)	`loader.ts`
Plugins	`{pluginRoot}/skills/*/SKILL.md`	`skills.ts`

2.2 File Structure

Each skill is a directory containing a SKILL.md file with YAML frontmatter:

.github/skills/
  my-skill/
    SKILL.md       ← markdown with frontmatter

Or a flat SKILL.md directly in the skills directory (single-skill mode).

2.3 Frontmatter Schema

---
name: skill-name                      # Optional; derived from folder name if absent
description: "What this skill does"   # Optional; derived from first 3 lines of body
allowed-tools: grep,view              # Comma-separated tool whitelist (optional)
user-invocable: true                  # Whether user can invoke via slash command (default: true)
disable-model-invocation: false       # Whether model can invoke autonomously (default: false)
---

Skill prompt content here...

3. Commands

A variant of skills, loaded from .claude/commands/ only.

Source	File Pattern	Code Reference
Project	`{repo}/.claude/commands/*.md`	`loader.ts` getCommandDirectories
User	`~/.claude/commands/*.md`	`loader.ts` getCommandDirectories

Note: Commands use only the .claude/ convention — not .github/ or .agents/.

Any .md file in the directory is treated as a command. Same frontmatter schema as skills. Treated internally as skills with isCommand: true. Skills take priority over commands on name conflicts.

4. Custom Agents

Sub-agent definitions available via the task tool or direct user selection.

4.1 Discovery Paths

Source	File Pattern	Code Reference
Repo (Copilot)	`{repo}/.github/agents/.md`, `.agent.md`	`useCustomAgents.ts`
Repo (Claude)	`{repo}/.claude/agents/.md`, `.agent.md`	`useCustomAgents.ts`
User (Copilot)	`~/.github/agents/.md`, `.agent.md`	`useCustomAgents.ts`
User (Claude)	`~/.claude/agents/.md`, `.agent.md`	`useCustomAgents.ts`
Plugins	`{pluginRoot}/agents/.md`, `.agent.md`	`agent-loader.ts`
Builtin	`src/agents/definitions/*.agent.yaml`	YAML agent loader

4.2 Priority Rules

*.agent.md takes precedence over *.md when both exist for the same base name.
.github/agents/ sources have higher priority than .claude/agents/.

4.3 Frontmatter Schema

---
name: agent-name
displayName: "Human-Readable Name"
description: "What this agent does"
tools: ["*"]                          # or ["tool1", "tool2"] — required
model: claude-sonnet-4-20250514                  # Optional model override
disableModelInvocation: false         # Cannot be auto-invoked as a tool
userInvocable: true                   # User can select it
mcp-servers:                          # Inline MCP server config (optional)
  server-name:
    command: "npx"
    args: ["@some/mcp-server"]
---

Agent system prompt content here...
Supports {{cwd}} placeholder.

5. MCP Servers

Model Context Protocol servers that expose additional tools and resources.

5.1 Config Sources (merge order, last wins)

Priority	Source	File Pattern	Code Reference
1 (lowest)	User	`~/.copilot/mcp-config.json`	`mcp-config.ts`
2	Workspace	`{cwd}/.mcp.json`	`mcpConfigMerger.ts`
3	VSCode	`{cwd}/.vscode/mcp.json`	`vsCodeWorkspaceMcpConfig.ts`
4	Plugins	`{pluginRoot}/.mcp.json`, `{pluginRoot}/.github/mcp.json`	`mcp-loader.ts`
5	Windows ODR	Registry `HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Mcp`	`odrMcpRegistry.ts`
6 (highest)	CLI flag	`--additional-mcp-config <json\|@filepath>`	`mcpConfigMerger.ts`

5.2 Config Schema

{
  "mcpServers": {
    "server-name": {
      "type": "local | http | sse",
      "command": "path/to/server",
      "args": ["--flag"],
      "cwd": "/optional/working/dir",
      "env": {
        "KEY": "$ENV_VAR",
        "URL": "https://${HOST}:${PORT}",
        "WITH_DEFAULT": "${VAR:-fallback}"
      },
      "url": "https://remote-server/endpoint",
      "headers": { "Authorization": "Bearer ${TOKEN}" },
      "tools": ["*"],
      "timeout": 30000,
      "filterMapping": "hidden_characters | markdown | none",
      "displayName": "My Server",
      "oauthClientId": "client-id",
      "oauthPublicClient": false
    }
  }
}

Environment variable expansion: $VAR, ${VAR}, ${VAR:-default} are all supported in env, args, url, and headers fields.

6. Hooks

Scripts that execute at specific agent lifecycle events, with the ability to approve/deny/modify behavior.

6.1 Config Sources

Source	File Pattern	Code Reference
Config dirs	`{configDir}/*/.json`	`hookConfigLoader.ts`
Plugins	`{pluginRoot}/hooks.json`	`hooks.ts`
Plugins (alt)	`{pluginRoot}/hooks/hooks.json`	`hooks.ts`
Plugin manifest	Inline in `plugin.json` → `hooks` field (object)	`hooks.ts`

6.2 Hook Events

Event	Trigger	Can Modify?
`sessionStart`	Session begins	No (informational)
`sessionEnd`	Session ends	No (informational)
`userPromptSubmitted`	User sends a message	Yes (can modify prompt)
`preToolUse`	Before tool execution	Yes (allow / deny / modify args)
`postToolUse`	After tool execution	Yes (can modify result)
`errorOccurred`	Error happens	Yes (retry / skip / abort)
`agentStop`	Main agent finishes	Yes (can force continuation)
`subagentStop`	Sub-agent completes	Yes (can force continuation)

6.3 Config Schema

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "command": "bash",
        "args": ["-c", "echo checking"],
        "cwd": "/optional/cwd",
        "env": { "KEY": "value" },
        "timeout": 30000
      }
    ]
  }
}

7. Plugins

Bundles that install combinations of skills, agents, hooks, and MCP servers.

7.1 Plugin Manifest Locations

Within a plugin repository, the manifest is searched at:

File Pattern	Code Reference
`plugin.json`	`marketplace-loader.ts` PLUGIN_JSON_PATHS
`.github/plugin/plugin.json`	`marketplace-loader.ts` PLUGIN_JSON_PATHS
`.claude-plugin/plugin.json`	`marketplace-loader.ts` PLUGIN_JSON_PATHS

Each field (skills, agents, hooks) can be a string path, array of paths, or (for hooks) an inline object.

Appendix A: XDG Base Directory Compliance

All ~/.copilot/ paths respect XDG overrides:

Type	Default	XDG Override
Config files	`~/.copilot/`	`$XDG_CONFIG_HOME/.copilot/`
State/cache	`~/.copilot/`	`$XDG_STATE_HOME/.copilot/`

The base directory name is always .copilot (APP_DIRECTORY in path-helpers.ts).

Appendix B: Complete Discovery Summary

Message received
 │
 ├─ Feature flags resolved
 │   ├─ Tier defaults
 │   ├─ config.json → feature_flags.enabled
 │   └─ Env vars (COPILOT_CLI_ENABLED_FEATURE_FLAGS, individual)
 │
 ├─ System prompt assembled
 │   ├─ Base agent prompt
 │   ├─ User instructions      ~/.copilot/copilot-instructions.md
 │   ├─ Repo instructions       .github/copilot-instructions.md, AGENTS.md, CLAUDE.md, GEMINI.md
 │   ├─ VSCode instructions     .github/instructions/**/*.instructions.md
 │   ├─ CWD instructions        (when cwd ≠ repo root)
 │   ├─ Child instructions      (depth=2 traversal)
 │   └─ Org instructions        (API-injected)
 │
 ├─ Tools assembled
 │   ├─ Built-in tools
 │   ├─ MCP servers             ~/.copilot/mcp-config.json + .mcp.json + .vscode/mcp.json + plugins
 │   └─ Content exclusion       (org API restrictions applied)
 │
 ├─ Skills listed               .github/skills/ + .agents/skills/ + .claude/skills/ + personal + plugins
 ├─ Commands listed             .claude/commands/ + personal
 ├─ Custom agents listed        .github/agents/ + .claude/agents/ + personal + plugins
 │
 ├─ userPromptSubmitted hooks fire
 │
 ├─ Model selected              config.json → model, agent override, or default
 │
 ├─ For each tool call:
 │   ├─ preToolUse hooks        (allow / deny / modify)
 │   ├─ Permission check
 │   ├─ Firewall policy
 │   ├─ Tool executes
 │   └─ postToolUse hooks       (modify result)
 │
 └─ Session telemetry emitted