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 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:

1.2 VSCode-Style Instruction Files

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

1.3 User-Level Instructions

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

1.7 Merge Order

Instructions are concatenated in this order (all additive):

1. User global (~/.copilot/copilot-instructions.md)
2. Repo-level instruction files (all patterns above)
3. VSCode-style instruction files (repo, then user)
4. CWD-specific overrides (when cwd ≠ repo root)
5. Child/nested instructions
6. 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

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.

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

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)

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

6.2 Hook Events

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:

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:

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