alexandrsurkov/copilot-vscode

SKILL: VS Code Copilot Platform

Load when the task concerns custom agent files (.agent.md), tool selection, context strategy, subagents, handoffs, MCP servers in VS Code, SKILL.md configuration, or any VS Code Copilot feature.

Official documentation: https://code.visualstudio.com/docs/copilot GitHub source: https://github.com/microsoft/vscode-docs/tree/main/docs/copilot Use #fetch <url> in chat to read any page listed in the index at the bottom of this skill.

When to Load This Skill

• Creating or reviewing a .agent.md file
• Choosing which tools to include (least-privilege applies — see ai-security SKILL)
• Designing a subagent workflow or handoff chain
• Configuring MCP servers in .vscode/mcp.json
• Setting up custom instructions or copilot-instructions.md
• Context engineering: what VS Code puts in the context window, and how to control it
• Any question about VS Code Copilot agent types, modes, or settings

---

.agent.md Frontmatter — All Valid Fields

---
description: <string>          # shown as placeholder in Chat input; one-sentence role summary
name: <string>                 # agent id; VS Code may infer from file name if omitted, but this repo sets it explicitly
tools: [<tool-name>, ...]      # allowed tools — see Built-in Tool Names below
agents: [<agent-name>, ...]    # allowed subagents; '*' = all, [] = none
model: <string | string[]>     # model name or priority list; if omitted = user's current picker
user-invokable: <bool>         # show in agents dropdown (default: true)
disable-model-invocation: <bool>  # prevent being called as subagent (default: false)
argument-hint: <string>        # hint text in chat input field
handoffs:                      # guided transitions to other agents
  - label: <string>            # button text
    agent: <agent-name>        # target agent id
    prompt: <string>           # pre-filled prompt for target
    send: <bool>               # auto-submit prompt (default: false)
    model: <string>            # model for the handoff (format: 'Model Name (vendor)')
target: vscode | github-copilot  # deployment target (default: vscode)
---

Key rules:

• Repo convention (A1.1): set name: and keep it identical to the file base name (kebab-case) to avoid drift.
• Agent discovery depends on VS Code settings (commonly chat.agentFilesLocations includes .github/agents). If agents don't show up, verify discovery/diagnostics.
• user-invokable: false hides from dropdown but still allows subagent invocation
• disable-model-invocation: true blocks subagent invocation but keeps it in dropdown
• These two fields replace the deprecated infer: field

---

Tool Names for tools: List (Framework-Aligned)

This framework standardizes on the tool names used in the canonical spec (e.g. readFile, fileSearch, textSearch). VS Code/Copilot may expose additional tools depending on version/extension; when in doubt, consult the official “Agent tools reference”.

File & code tools

| Tool name | What it does | |---|---| | readFile | Read file contents | | editFiles | Edit existing files | | createFiles | Create new files | | fileSearch | Search files by name/glob | | textSearch | Full-text search across workspace | | codebase | Optional: semantic workspace search (often invoked via #codebase) | | usages | Optional: find symbol usages and references (if available) |

Execution tools

| Tool name | What it does | |---|---| | runTerminal | Run terminal commands | | problems | Access Problems panel (linting, compiler errors) | | changes | Access current source control changes |

Network tools

| Tool name | What it does | |---|---| | fetch | Fetch URL content | | webSearch | Web search |

Agent tools

| Tool name | What it does | |---|---| | agent | Required when using agents: field (spawn subagents) |

Tool sets: some Copilot versions support referencing predefined groups (e.g. #edit, #search). If unsupported, list tools explicitly.

MCP tools: reference as <server-name>/<tool-name> or <server-name>/* for all tools of a server.

Least-privilege rule (A1.6): give each agent only the tools required for its specific role. Critics: read-only only (readFile, fileSearch, textSearch).

---

Tool Approval & Auto-Approve (chat.tools.autoApprove)

VS Code Copilot can require user confirmation for tool usage. The setting below can allow specific tools to run without prompting.

Architect guidance:

• Prefer no auto-approve by default.
• If you enable auto-approve, scope it to the lowest-risk, read-only tools.
• Never auto-approve anything that can make irreversible changes (deleting resources, sending messages, writing to remote systems).

Threat model reminder (A1.6): tool auto-approval increases the blast radius of prompt injection and mis-scoped agent permissions.

---

Tool Sets (illustrative: toolsets.jsonc)

Tool sets let you reference a named bundle of tools instead of listing each tool repeatedly. This helps keep .agent.md files short and makes least-privilege reviews easier.

Architect guidance:

• Use tool sets to encode role capabilities (e.g., docs-readonly, repo-editor) and keep them stable.
• Review tool sets like an API surface: changes can silently widen agent permissions.
• Prefer multiple small tool sets over one broad “kitchen sink” set.

Note: some VS Code setups support a toolsets.jsonc (or equivalent) config for named tool bundles. This ForgentFramework repo does not ship a toolsets.jsonc; treat this section as conceptual guidance. Use #fetch on the official docs index at the bottom of this skill when you need the precise schema and lookup rules.

---

Agent Types (VS Code)

| Type | Where it runs | When to use | |---|---|---| | Local — Agent | VS Code, interactive | Complex multi-file tasks, iterative work, needs editor/terminal context | | Local — Plan | VS Code, interactive | Breaking down complex tasks before implementation; generates structured plan | | Local — Ask | VS Code, interactive | Questions about codebase; read-only research | | Background agent | VS Code, background | Well-defined tasks while you keep working | | Cloud agent | GitHub, remote | Automated PRs, tasks requiring team collaboration, CI-style jobs | | Third-party agent | External provider / extension / service | When a non-Microsoft agent workflow is required (policy-approved), e.g., vendor-specific capabilities or integrations not available via built-in agents | | Custom agent | Local or cloud | Specialized persona: security reviewer, planner, architect, etc. |

Selection guide (architect-facing):

Pick the execution surface first:

• Needs continuous back-and-forth, live editor state, stack traces, linting → Local — Agent
• Needs a plan artifact first, before any changes → Local — Plan
• Needs read-only investigation / explanation → Local — Ask
• Needs autonomy while the user keeps coding in VS Code → Background agent
• Needs a PR-oriented workflow (review + CI), or work should continue without the user's machine → Cloud agent

Then pick the persona:

• Needs a specialized, stable role with least-privilege tools (critic, architect, compliance reviewer) → Custom agent (.agent.md)

Use third-party agents only when necessary:

• If the requirement is “a tool/integration”, prefer adding an MCP tool over introducing a new agent provider.
• If a third-party agent is required, confirm it is policy-approved and treat it as a trust-boundary crossing (A1.6): minimize shared context, avoid secrets, and prefer read-only tasks.

Quick decision checklist (copy into your recommendation):

• Output: chat answer vs code changes vs PR
• Context need: current editor state vs repo-only context
• Runtime need: terminal/linters/tests required?
• Collaboration: needs CI + review trail?
• Risk: any irreversible actions? → require explicit confirmation
• Trust boundary: any external/third-party processing? → minimize context and verify approvals

---

Subagents

What they are: child agents with isolated context windows. Main agent waits for result, receives only the summary — not the full subagent conversation.

When to use:

• Offload research so main agent context stays focused
• Run multiple analyses in parallel (VS Code runs subagents concurrently)
• Isolate experimental work (dead ends don't pollute main context)
• Apply specialized behavior (use a security-reviewer custom agent as subagent)

How to invoke in a prompt:

Use a subagent to research OAuth 2.0 patterns for Node.js. Return a recommendation.

In .agent.md:

tools: ['agent', 'readFile', 'fileSearch']
agents: ['forgent-docs-critic', 'forgent-process-critic']  # or '*' for all

Key properties:

• Synchronous: main agent blocks until subagent returns
• Parallel: multiple subagents can run concurrently
• Subagents start with a clean context window — they do NOT inherit main agent instructions
• user-invokable: false + subagent-only agents: used for internal pipeline steps

Ref: https://code.visualstudio.com/docs/copilot/agents/subagents

---

Handoffs

Transition from one agent to another with context and a pre-filled prompt. Handoff buttons appear after a response completes.

handoffs:
  - label: "Start Implementation"
    agent: forgent-spec-editor
    prompt: "Now implement the plan outlined above."
    send: false           # user reviews before submitting
  - label: "Review Changes"
    agent: forgent-process-critic
    prompt: "Review the changes made in the previous step."
    send: true            # auto-submits
    model: "Claude Sonnet 4.5 (copilot)"

Use for: plan → implement → review pipelines; multi-step workflows where human reviews each step.

---

Context Engineering in VS Code

How VS Code assembles context

1. System prompt — agent body from .agent.md
2. Custom instructions — from copilot-instructions.md + any *.instructions.md
3. Conversation history — compressed when context window fills
4. Explicit #-mentions — #file, #codebase, #web, #changes, etc.
5. Automatic context — current editor, workspace index, git state
6. Tool outputs — added per iteration in the agent loop

Context sources reference

| #-mention | What it adds | |---|---| | #file:<path> | Specific file contents | | #codebase | Semantic workspace search result | | #changes | Current source control diff | | #problems | Problems panel contents | | #web | Web search result | | #fetch <url> | URL content | | #githubRepo <owner/repo> | GitHub repository search |

Workspace index

• Remote index: built from committed state on GitHub/Azure DevOps — best for large codebases
• Local index: uncommitted changes, hybrid with remote
• Build index: Build Remote Workspace Index command in Command Palette
• .gitignore files are excluded from index (unless opened)

Ref: https://code.visualstudio.com/docs/copilot/reference/workspace-context

---

Custom Instructions vs SKILL.md

| | Custom instructions (copilot-instructions.md) | SKILL.md | |---|---|---| | Purpose | Coding standards, guidelines, always-on rules | Specialized capabilities, lazy-loaded knowledge | | When loaded | Always (every chat interaction) | On-demand when relevant | | Content | Instructions only | Instructions + scripts + examples + resources | | Standard | VS Code-specific | Open standard (agentskills.io), portable | | Location | .github/copilot-instructions.md | .github/skills/, .agents/skills/, ~/.copilot/skills/ |

Rule: keep copilot-instructions.md short (~300 words). Move domain-specific knowledge to SKILL.md.

SKILL.md detection locations

VS Code searches for skills in:

• .github/skills/<name>/SKILL.md
• .agents/skills/<name>/SKILL.md ← this repo's convention
• .claude/skills/<name>/SKILL.md
• User profile: ~/.copilot/skills/<name>/SKILL.md

To add more locations: configure chat.agentSkillsLocations in VS Code settings.

---

MCP Server Configuration (.vscode/mcp.json)

{
  "servers": {
    "<server-name>": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@scope/mcp-server"],
      "env": { "API_KEY": "${input:api-key}" }
    },
    "<remote-server>": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:token}" }
    }
  },
  "inputs": [
    { "id": "api-key", "type": "promptString", "description": "API Key", "password": true }
  ]
}

Key rules:

• type: stdio — server runs in foreground, communicates via stdin/stdout (no -d for Docker)
• type: http — VS Code tries HTTP Stream transport first, falls back to SSE
• Secrets via ${input:...} — never hardcode credentials
• Tools available as <server-name>/<tool-name> in tools: lists
• Supply chain risk: every MCP server is a new attack surface (OWASP LLM06)

Ref: https://code.visualstudio.com/docs/copilot/reference/mcp-configuration

---

.vscode/settings.json — Agent Registration

{
  "chat.agentFilesLocations": {
    ".github/agents": true        // scan this folder for .agent.md files
  },
  "chat.agentSkillsLocations": [
    ".agents/skills"              // additional SKILL.md search path
  ],
  "chat.agent.enabled": true,     // must be true for agent mode
  "chat.tools.autoApprove": {}    // per-tool auto-approval config
}

Architect guidance (minimal safe defaults):

• Keep chat.tools.autoApprove empty unless you have a clear reason and a documented safety boundary.
• If you must add entries, prefer read-only tools first (search/read) and keep the list explicit.

---

Coverage Checklist — Upstream customization/ Docs

This skill now includes explicit coverage for every page currently in: https://github.com/microsoft/vscode-docs/tree/main/docs/copilot/customization

Upstream pages (folder contents):

• overview.md
• custom-instructions.md
• prompt-files.md
• agent-skills.md
• custom-agents.md
• hooks.md
• language-models.md
• mcp-servers.md

Design intent for multi-agent systems (A1.2): treat custom instructions as baseline constraints, prompt files as repeatable task macros, custom agents as tool-scoped personas, skills as portable capability packages, MCP as external tool surface, hooks as deterministic guardrails.

---

Customization Overview — Choosing the Right Mechanism

Use this as a decision table when designing your agent system.

| Goal | Prefer | Why | |---|---|---| | Enforce global repo conventions | Custom instructions | Always included; low operational overhead | | Different rules per language/folder | File-based instructions | Scoped by applyTo patterns | | Repeatable single task (“do X”) | Prompt file (.prompt.md) | Explicit invocation via /... | | Multi-step capability + assets | Agent Skill (SKILL.md + resources) | Progressive disclosure + portability | | Specialist persona + tool boundary | Custom agent (.agent.md) | Least-privilege tools per role | | External API / DB / browser / SaaS | MCP server | Adds tool capabilities beyond VS Code built-ins | | Deterministic enforcement / automation | Hooks | Executes code at lifecycle events; can block tools |

Prompt files vs custom agents:

• Prompt file = “run this procedure” (task).
• Custom agent = “be this role” (persona + tool boundary + optional handoffs/subagents).

Project bootstrap & diagnostics

• /init can generate a starter .github/copilot-instructions.md tailored to the workspace; treat it as a draft to review.
• If customizations don’t apply as expected: open Chat Configure Chat (gear) → Diagnostics and verify which agents/prompt files/instructions/skills are loaded and whether they have validation errors.

---

Custom Instructions — Files, Scope, and Precedence

Instruction types

• Always-on (applies to every request)
• File-based (applies when files match patterns or description matches task)

Common file locations (workspace)

• Always-on: .github/copilot-instructions.md
• File-based: .github/instructions/**/*.instructions.md (default)

Additional supported sources (use intentionally)

• AGENTS.md (always-on instructions file supported by VS Code)
  • In this repo, AGENTS.md is also the orchestrator repo map.
  • If you also use it as Copilot instructions: keep it dual-purpose and avoid contradictions.
• CLAUDE.md (always-on for Claude-compat tooling)

.instructions.md frontmatter (key fields)

• applyTo: glob pattern relative to workspace root (use ** to apply to all)
• name, description: UI metadata; keep descriptions explicit so semantic matching works

Settings you may need (diagnostics-oriented)

• chat.instructionsFilesLocations — add extra folders for instructions discovery
• chat.useAgentsMdFile — enable/disable AGENTS.md detection
• chat.useNestedAgentsMdFiles — nested AGENTS.md in subfolders (experimental)
• chat.includeApplyingInstructions — include pattern-matched instructions automatically
• chat.includeReferencedInstructions — include instructions referenced via Markdown links

Priority model (conflict resolution)

When multiple sources exist, higher priority generally wins:

1. Personal/user instructions
2. Workspace/repository instructions
3. Organization-level instructions

Portability & team rollout

• Organization-level instructions exist (GitHub org feature); use them for baseline policies across repos.
• Settings Sync can sync user prompt/instruction files across devices (look for the “Prompts and Instructions” sync category).

Architect checklist (keep it effective and safe):

• Keep always-on instructions short and stable; move deep procedures into skills.
• Explain the “why” behind non-obvious rules; include 1–2 examples for edge cases.
• Never embed secrets; reference env vars or input prompts only.

---

Prompt Files (.prompt.md) — Slash Commands, Tools, Variables

Locations

• Workspace: .github/prompts/**/*.prompt.md
• User profile: profile prompts/ folder
• Configure additional locations with chat.promptFilesLocations

Frontmatter fields (high-signal)

• name, description, argument-hint
• agent: ask | agent | plan | <custom-agent-name>
• model: optional; falls back to picker
• tools: optional; can include MCP tools and <server>/*

Variable interpolation (design for reuse)

• Workspace: ${workspaceFolder}, ${workspaceFolderBasename}
• File context: ${file}, ${fileBasename}, ${fileDirname}, ${fileBasenameNoExtension}
• Selection: ${selection}, ${selectedText}
• Input: ${input:var} / ${input:var:placeholder}

Tool list priority

If both prompt + agent specify tools, effective tools follow:

1. Prompt file tools
2. Tools from referenced custom agent
3. Default tools of selected agent

Architect checklist:

• Prefer prompt files for repeatable “one-shot” workflows.
• Use prompt files to narrow tools for a specific workflow, not broaden them.
• Reference instructions/skills via Markdown links instead of duplicating rules.

---

Agent Skills — Progressive Disclosure and Portability

What a skill is

• A folder containing SKILL.md (required) and optional resources/scripts.
• Skills are auto-loaded on relevance or invoked via /.

Skill discovery and loading (3 levels)

1. Discovery: only name + description metadata is considered
2. Instructions load: body of SKILL.md is loaded when relevant
3. Resource access: other files in the skill folder are accessed on demand

Skill frontmatter knobs

• user-invokable: false → hidden from slash menu, still auto-loadable
• disable-model-invocation: true → manual-only (no auto-load)

Locations

• Project skills: .github/skills/, .agents/skills/, .claude/skills/
• Personal skills: ~/.copilot/skills/, ~/.agents/skills/, ~/.claude/skills/
• Extend discovery with chat.agentSkillsLocations

Architect checklist:

• Put “how-to” + examples + scripts in skills; keep global instructions minimal.
• Write skill description like a classifier: capability + trigger phrases.
• Treat skills as a reusable library; version and review them like code.

---

Custom Agents (.agent.md) — Personas, Tools, Subagents, Handoffs

This skill already contains the complete .agent.md frontmatter field list, agent type guidance, subagent and handoff patterns.

Add these customization-specific reminders:

• Custom agents were formerly “custom chat modes”; .chatmode.md → .agent.md.
• If you declare agents: (subagents), ensure tools: includes agent.
• Handoffs are best for plan → implement → review workflows with human gates.

---

Hooks — Deterministic Policy and Automation (Preview)

Hooks execute shell commands at lifecycle points and can block/ask/allow tool usage.

Hook events (current set)

SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, SubagentStart, SubagentStop, Stop

Hook config locations

• Workspace shared: .github/hooks/*.hook.jsonc
• Claude-compatible: .claude/settings.json, .claude/settings.local.json
• User: ~/.claude/settings.json

Security posture (A1.3)

• Hooks run with your VS Code permissions; treat them as executable code.
• Do not let agents freely edit hook scripts without manual approval.
• Validate/sanitize hook stdin JSON to avoid injection.

Troubleshooting essentials

• Use Chat Diagnostics to see loaded hooks and validation errors.
• Check the Output panel channel for Copilot Chat Hooks to inspect stdout/stderr.
• If using Stop/SubagentStop “block” behavior, guard against infinite loops by respecting stop_hook_active.

---

Language Models — Constraints That Affect Agent Design

Agent mode may restrict model availability to tool-capable models.

Design implications:

• Prefer explicit model: in a custom agent when output consistency matters.
• If relying on BYOK models, verify tool-calling capability and understand that some Copilot service steps may still occur (embeddings/indexing/intent routing).
• Treat “Auto model selection” as a performance feature, not a governance control.

Also relevant knobs:

• Inline chat can have a different default model via inlineChat.defaultModel.
• Inline suggestions use a separate completions model selection path; don’t assume chat model changes affect suggestions.

---

MCP Servers — External Tool Surface and Trust

This skill already includes a baseline .vscode/mcp.json schema example.

Add these operational/security essentials (A1.3 / LLM06):

• Installing local MCP servers can run arbitrary code; review publisher and config.
• Prefer workspace mcp.json for team-shared config; user profile for personal tools.
• Use input variables / env vars; never hardcode secrets.
• Beyond tools, MCP can provide: resources, prompts, and MCP apps.
• Understand trust prompts: starting from config may bypass interactive trust UX.

Official Documentation Index

Use #fetch <url> to read any page for deep dives:

| Topic | URL | |---|---| | Core concepts (agent loop, context, models) | https://code.visualstudio.com/docs/copilot/core-concepts | | All agent types overview | https://code.visualstudio.com/docs/copilot/agents/overview | | Local agents (Agent/Plan/Ask) | https://code.visualstudio.com/docs/copilot/agents/local-agents | | Subagents | https://code.visualstudio.com/docs/copilot/agents/subagents | | Agent tools reference | https://code.visualstudio.com/docs/copilot/agents/agent-tools | | Customization overview | https://code.visualstudio.com/docs/copilot/customization/overview | | Custom agents (.agent.md) | https://code.visualstudio.com/docs/copilot/customization/custom-agents | | Agent Skills (SKILL.md) | https://code.visualstudio.com/docs/copilot/customization/agent-skills | | Custom instructions | https://code.visualstudio.com/docs/copilot/customization/custom-instructions | | Prompt files (.prompt.md) | https://code.visualstudio.com/docs/copilot/customization/prompt-files | | Hooks | https://code.visualstudio.com/docs/copilot/customization/hooks | | Language models | https://code.visualstudio.com/docs/copilot/customization/language-models | | MCP servers | https://code.visualstudio.com/docs/copilot/customization/mcp-servers | | MCP config reference | https://code.visualstudio.com/docs/copilot/reference/mcp-configuration | | Workspace context / #codebase | https://code.visualstudio.com/docs/copilot/reference/workspace-context | | Context engineering guide | https://code.visualstudio.com/docs/copilot/guides/context-engineering-guide | | Cheat sheet | https://code.visualstudio.com/docs/copilot/reference/copilot-vscode-features |