feat(customizations): align with latest VS Code Copilot spec [skip ci]

Author: trsdn

.github/agents/copilot-customization-builder.agent.md

@@ -16,6 +16,7 @@ You help create and evolve GitHub Copilot and VS Code customization artifacts:
 - Hooks (`.github/hooks/*.json`) for lifecycle automation
 - MCP server configurations (`mcp.json`) and related guidance
 - Agent plugins (preview) — discoverable bundles of customizations
+- Tool sets — reusable groups of built-in, MCP, and extension tools
 
 You are opinionated about correctness, safety, and matching repository conventions.
 
@@ -32,7 +33,7 @@ You are opinionated about correctness, safety, and matching repository conventio
 When a user asks for a new customization, do this:
 
 1. **Clarify the intent**
-   - Are we creating an *agent*, a *prompt file*, *instructions*, a *skill*, a *hook*, or an *MCP* setup?
+   - Are we creating an *agent*, a *prompt file*, *instructions*, a *skill*, a *hook*, an *MCP* setup, a *plugin*, or a *tool set*?
    - Scope: workspace-only (this repo) vs user profile vs org/enterprise.
    - Target environment: `vscode`, `github-copilot`, or both.
 
@@ -42,7 +43,7 @@ When a user asks for a new customization, do this:
    - Match naming, tool naming, and tone.
 
 3. **Design before writing files**
-   - Draft the frontmatter: `name`, `description`, `tools`, optional `model`, optional `user-invocable`, optional `disable-model-invocation`, optional `agents`, optional `target`, optional `handoffs`, optional `hooks`, optional `argument-hint`.
+   - Draft the frontmatter: `name`, `description`, `tools`, optional `model`, optional `user-invocable`, optional `disable-model-invocation`, optional `agents`, optional `target`, optional `handoffs`, optional `hooks`, optional `argument-hint`, optional `mcp-servers`.
    - Keep tool lists small; if omitted, the agent gets *all* tools (avoid that unless explicitly requested).
 
 4. **Implement incrementally**
@@ -93,6 +94,8 @@ Frontmatter guidelines:
 - Workspace-wide: `.github/copilot-instructions.md`
 - File-pattern scoped: `*.instructions.md` with `applyTo: '<glob>'`
 - Optional: `AGENTS.md` for repository-level guidance (often used by coding agents)
+- Optional: `CLAUDE.md` and `.claude/rules/*.md` for Claude-compatible instructions.
+- Organization-level instructions can provide shared defaults; repository files are the local override layer.
 
 ### Agent Skills
 
@@ -128,6 +131,37 @@ Skills work across VS Code, Copilot CLI, and Copilot coding agent (portable, ope
 - Avoid destructive terminal commands; if terminal is required, explain why and keep commands narrowly scoped.
 - Keep tool sets under control; there are practical limits on how many tools can be enabled at once.
 
+### Tools and tool sets
+
+Tools can be built-in tools, MCP tools, extension-contributed tools, or tool sets.
+
+- Use explicit tool names where possible.
+- Use tool aliases (`read`, `edit`, `search`, `web`, `agent`) only when targeting GitHub Copilot cloud agent compatibility.
+- Use `<server>/<tool>` for a specific MCP tool and `<server>/*` only when all tools from that server are intentionally required.
+- Use tool sets to group related tools for prompts and agents, such as read-only research tools or selected MCP tools.
+- Remember the priority order: prompt file `tools` override referenced custom-agent `tools`, which override the selected agent defaults.
+
+### MCP servers
+
+MCP servers connect agents to external tools, APIs, data sources, resources, prompts, and MCP Apps.
+
+- VS Code workspace MCP config lives in `.vscode/mcp.json`; keep examples as `.vscode/mcp.example.json` until intentionally enabled.
+- GitHub Copilot cloud agents can define agent-scoped MCP servers with `mcp-servers` in `.agent.md` frontmatter (`target: github-copilot`).
+- Plugin MCP servers use `.mcp.json` with top-level `mcpServers` (not `servers`).
+- Never commit secrets. Use VS Code input variables, env files, or GitHub Copilot environment secrets/variables.
+- For local stdio servers on macOS/Linux, consider `sandboxEnabled: true` with explicit filesystem and network restrictions.
+- Treat MCP server output as untrusted external content and review trust prompts carefully.
+
+### Agent plugins (preview)
+
+Agent plugins package multiple customization types for installation and reuse.
+
+- A plugin can bundle slash commands, skills, agents, hooks, and MCP servers.
+- Plugin manifests require a kebab-case `name` (lowercase letters, numbers, hyphens; max 64 chars).
+- Keep example manifests inert (`plugin.example.json`) unless the user explicitly asks to create an active plugin.
+- Review plugin hooks and MCP servers carefully because plugins can run local code.
+- Workspace recommendations can point users to approved plugin marketplaces and enabled plugins.
+
 ### Hooks (lifecycle automation)
 
 Hooks execute shell commands at key lifecycle points during agent sessions. They provide deterministic, code-driven automation.
@@ -187,22 +221,29 @@ Some frontmatter fields have different behavior depending on where the agent run
 - Agent Skills standard: <https://agentskills.io/>
 - Language models (VS Code): <https://code.visualstudio.com/docs/copilot/customization/language-models>
 - MCP servers (VS Code): <https://code.visualstudio.com/docs/copilot/customization/mcp-servers>
-- Chat tools & approvals (VS Code): <https://code.visualstudio.com/docs/copilot/chat/chat-tools>
+- MCP configuration reference (VS Code): <https://code.visualstudio.com/docs/copilot/reference/mcp-configuration>
+- Agent tools & approvals (VS Code): <https://code.visualstudio.com/docs/copilot/agents/agent-tools>
+- Tools concepts (VS Code): <https://code.visualstudio.com/docs/copilot/concepts/tools>
 - Chat sessions (VS Code): <https://code.visualstudio.com/docs/copilot/chat/chat-sessions>
+- Subagents (VS Code): <https://code.visualstudio.com/docs/copilot/agents/subagents>
 - Manage context (VS Code): <https://code.visualstudio.com/docs/copilot/chat/copilot-chat-context>
 - Copilot feature reference / cheat sheet (VS Code): <https://code.visualstudio.com/docs/copilot/reference/copilot-vscode-features>
 - Agents overview (local/background/cloud): <https://code.visualstudio.com/docs/copilot/agents/overview>
 - Background agents: <https://code.visualstudio.com/docs/copilot/agents/background-agents>
 - Cloud agents: <https://code.visualstudio.com/docs/copilot/agents/cloud-agents>
+- Customization concepts: <https://code.visualstudio.com/docs/copilot/concepts/customization>
 - Context engineering guide: <https://code.visualstudio.com/docs/copilot/guides/context-engineering-guide>
 - Prompt engineering guide: <https://code.visualstudio.com/docs/copilot/guides/prompt-engineering-guide>
+- Customize AI for your project guide: <https://code.visualstudio.com/docs/copilot/guides/customize-copilot-guide>
 - Security considerations (VS Code): <https://code.visualstudio.com/docs/copilot/security>
-- Subagents / chat sessions (VS Code): <https://code.visualstudio.com/docs/copilot/chat/chat-sessions>
+- Awesome Copilot examples: <https://github.com/github/awesome-copilot>
+- Reference skills (Anthropic): <https://github.com/anthropics/skills>
 
 GitHub Copilot (cloud) custom agents:
 
 - Creating custom agents (GitHub docs): <https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents>
 - Custom agents configuration (GitHub reference): <https://docs.github.com/en/copilot/reference/custom-agents-configuration>
+- Configure organization instructions (GitHub docs): <https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-organization-instructions>
 
 ## Deliverables style
 

.github/copilot-instructions.md

@@ -14,9 +14,14 @@ Copilot agents, prompt files, instructions, skills, and hooks in any project.
 - Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
 - Agent files: `.agent.md` with YAML frontmatter (`description` required, `name` and `tools` recommended)
 - Prompt files: `.prompt.md` with YAML frontmatter (`description` recommended)
-- Skill files: `SKILL.md` in a named directory under `.github/skills/<name>/`
+- Skill files: `SKILL.md` in a named directory under `.github/skills/<name>/` (alt locations: `.claude/skills/`, `.agents/skills/`)
 - Hook configs: JSON files in `.github/hooks/` defining lifecycle automation
+- MCP configs: `.vscode/mcp.json` for VS Code workspace MCP, `mcp-servers` in GitHub Copilot agent frontmatter, `.mcp.json` in plugins
+- Agent plugin manifests: `plugin.json` in plugin roots; keep example manifests inert as `*.example.json`
+- Tool sets group built-in, MCP, and extension tools; keep examples inert unless deliberately enabled via VS Code
 - Use `user-invocable` and `disable-model-invocation` instead of the deprecated `infer` field
+- For multi-agent workspaces, `AGENTS.md` (root or experimental nested) and `CLAUDE.md` are also recognized as always-on instructions
+- For monorepos opened in a subfolder, enable `chat.useCustomizationsInParentRepositories` to discover customizations from the repo root
 
 ## File Structure
 

.github/hooks/README.md

@@ -0,0 +1,36 @@
+# Hooks
+
+This directory holds [agent hook](https://code.visualstudio.com/docs/copilot/customization/hooks)
+configurations (`*.json`) that VS Code loads automatically.
+
+Hooks execute shell commands at lifecycle points during agent sessions
+(`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`,
+`SubagentStart`, `SubagentStop`, `Stop`) and can block, allow, or augment
+agent actions.
+
+## Files
+
+- [`example-block-dangerous.json.example`](./example-block-dangerous.json.example) —
+  inert `PreToolUse` hook sample that warns on dangerous shell patterns. Copy it
+  to `.github/hooks/<name>.json` before use.
+
+## Scaffolding new hooks
+
+Use the bundled prompt template:
+
+```text
+/copilot-new-hook
+```
+
+Or follow the [hooks spec](https://code.visualstudio.com/docs/copilot/customization/hooks).
+
+## Notes
+
+- Hook scripts must be executable (`chmod +x script.sh`).
+- Default timeout is 30 seconds; override via the `timeout` field.
+- Workspace hooks (`.github/hooks/*.json`) are shared with the team via Git.
+- Agent-scoped hooks (in `.agent.md` frontmatter) require
+  `chat.useCustomAgentHooks` to be enabled.
+- VS Code also reads `.claude/settings.json`, `.claude/settings.local.json`,
+  and `~/.claude/settings.json` by default. Use the `chat.hookFilesLocations`
+  setting to customize loading.

.github/hooks/example-block-dangerous.json.example

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://aka.ms/vscode-chat-hooks-schema",
+  "_comment": "Example PreToolUse hook. Adapt and rename before enabling. The script must exist and be executable.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": "./.github/hooks/scripts/check-dangerous.sh",
+        "timeout": 10
+      }
+    ]
+  }
+}

.github/hooks/scripts/check-dangerous.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Example PreToolUse hook script.
+# Reads JSON from stdin, denies destructive shell patterns via permissionDecision.
+# Exit code 0 = parse stdout JSON; 2 = blocking error; other = non-blocking warning.
+
+set -euo pipefail
+
+input="$(cat)"
+
+# Extract tool_input.command if present (best-effort, no jq dep).
+cmd="$(printf '%s' "$input" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)"
+
+deny() {
+  cat <<JSON
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by check-dangerous.sh: $1"
+  }
+}
+JSON
+  exit 0
+}
+
+case "$cmd" in
+  *"rm -rf /"*|*"rm -rf ~"*|*"mkfs"*|*"dd if=/dev/"*|*":(){ :|:& };:"*|*"DROP TABLE"*|*"DROP DATABASE"*)
+    deny "destructive pattern detected"
+    ;;
+esac
+
+# Allow by default — return empty JSON.
+echo '{}'

.github/plugin/plugin.example.json

@@ -0,0 +1,12 @@
+{
+  "name": "example-copilot-plugin",
+  "description": "Example inert agent plugin manifest. Rename to plugin.json in a plugin root to enable.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Your Team"
+  },
+  "skills": "skills/",
+  "agents": "agents/",
+  "hooks": "hooks.json",
+  "mcpServers": ".mcp.json"
+}

.github/prompts/copilot-audit-setup.prompt.md

@@ -11,7 +11,7 @@ Analyze this repository's GitHub Copilot customization and provide recommendatio
 
 ## Audit Scope
 
-Focus area (optional): `${input:focusArea:Leave empty for full audit, or specify: instructions, agents, prompts, skills, settings}`
+Focus area (optional): `${input:focusArea:Leave empty for full audit, or specify: instructions, agents, prompts, skills, hooks, MCP, plugins, toolsets, org, settings}`
 
 ## Audit Workflow
 
@@ -23,6 +23,7 @@ Check for existence and content of:
    - `.github/copilot-instructions.md`
    - `.github/instructions/*.instructions.md`
    - `AGENTS.md` (root and subfolders)
+   - `CLAUDE.md` and `.claude/rules/*.md` when present
 
 2. **Custom Agents**
    - `.github/agents/*.agent.md`
@@ -34,7 +35,21 @@ Check for existence and content of:
 4. **Agent Skills**
    - `.github/skills/*/SKILL.md`
 
-5. **Settings**
+5. **Hooks**
+   - `.github/hooks/*.json`
+   - Inert examples such as `.github/hooks/*.json.example`
+
+6. **MCP**
+   - `.vscode/mcp.json`
+   - `.vscode/mcp.example.json`
+   - Agent frontmatter `mcp-servers`
+   - Plugin `.mcp.json` / `mcpServers`
+
+7. **Agent Plugins and Tool Sets**
+   - `plugin.json` / `plugin.example.json`
+   - `.github/toolsets/*.jsonc`
+
+8. **Settings**
    - `.vscode/settings.json`
 
 ### Step 2: Validate Existing Files
@@ -52,6 +67,10 @@ Based on project type, suggest missing customizations:
 - Common workflow agents
 - Repetitive task prompts
 - Project knowledge skills
+- MCP integrations for trusted external tools/data
+- Tool sets for repeated tool bundles
+- Agent plugins when a workflow should be packaged/distributed
+- Organization/enterprise defaults vs repository overrides
 
 ### Step 4: Generate Report
 

.github/prompts/copilot-check-compatibility.prompt.md

@@ -25,7 +25,7 @@ Diagnose feature availability and troubleshoot Copilot customization issues.
 
 When diagnosing, fetch these sources as needed:
 
-- **Release Notes**: `https://code.visualstudio.com/updates/v1_XXX` (replace XXX with version)
+- **Release Notes**: use `https://code.visualstudio.com/updates/v1_108` as the pattern and replace the version as needed
 - **Custom Instructions**: https://code.visualstudio.com/docs/copilot/customization/custom-instructions
 - **Custom Agents**: https://code.visualstudio.com/docs/copilot/customization/custom-agents
 - **Agent Skills**: https://code.visualstudio.com/docs/copilot/customization/agent-skills
@@ -40,7 +40,7 @@ When diagnosing, fetch these sources as needed:
 | Agent Skills | `chat.useAgentSkills: true` |
 | Nested AGENTS.md | `chat.useNestedAgentsMdFiles: true` |
 | Subagents with custom agents | `chat.customAgentInSubagent.enabled: true` |
-| Org/Enterprise agents | `github.copilot.chat.customAgents.showOrganizationAndEnterpriseAgents: true` |
+| Org/Enterprise agents | `github.copilot.chat.organizationCustomAgents.enabled: true` |
 | Background agents | `chat.agent.background.enabled: true` |
 
 ### Stable Features (usually enabled by default)

.github/prompts/copilot-new-agent.prompt.md

@@ -25,6 +25,7 @@ Create a new custom agent profile in this repository.
    - `description` (required): Brief description shown as placeholder text in chat input
    - `name` (recommended): Display name (defaults to filename if omitted)
    - `tools` (recommended): Explicit list of available tools (prefer minimal)
+       - Can include built-in tools, tool aliases, extension tools, tool sets, or MCP tools (`<server>/<tool>`, `<server>/*`)
    - `target`: Set to `vscode` or `github-copilot` if restricting; omit for both
    - `model` (optional): Specific AI model or prioritized array of models
    - `user-invocable` (optional): Boolean to control agents dropdown visibility (default: true)
@@ -58,6 +59,13 @@ handoffs:
 - `send`: Auto-submit prompt if true (default: false)
 - `model`: Optional model override for the handoff target
 
+## MCP and tool guidance
+
+- For VS Code-only agents, configure MCP servers in `.vscode/mcp.json`, not agent frontmatter.
+- For GitHub Copilot cloud agents, use `mcp-servers` in frontmatter and reference tools in `tools`.
+- Prefer specific MCP tools (`server/tool-name`) over full server wildcards (`server/*`).
+- Use tool sets for reusable groups of built-in, MCP, and extension tools when the same capability bundle is reused.
+
 When done, list the created file path and how to select the agent in the VS Code agents dropdown.
 
 > **Deprecated:** `infer` is deprecated. Use `user-invocable` and `disable-model-invocation` instead.
@@ -68,7 +76,8 @@ When done, list the created file path and how to select the agent in the VS Code
 - Agents overview (local/background/cloud): https://code.visualstudio.com/docs/copilot/agents/overview
 - Background agents: https://code.visualstudio.com/docs/copilot/agents/background-agents
 - Cloud agents: https://code.visualstudio.com/docs/copilot/agents/cloud-agents
-- Tools & approvals (VS Code): https://code.visualstudio.com/docs/copilot/chat/chat-tools
+- Agent tools & approvals (VS Code): https://code.visualstudio.com/docs/copilot/agents/agent-tools
+- MCP servers (VS Code): https://code.visualstudio.com/docs/copilot/customization/mcp-servers
 - Security considerations (VS Code): https://code.visualstudio.com/docs/copilot/security
 - Hooks (VS Code): https://code.visualstudio.com/docs/copilot/customization/hooks
 - Awesome Copilot examples: https://github.com/github/awesome-copilot

.github/prompts/copilot-new-instructions.prompt.md

@@ -24,6 +24,8 @@ VS Code supports multiple types of instructions files:
 | `.github/copilot-instructions.md` | Workspace root | All chat requests |
 | `*.instructions.md` | `.github/instructions/` or user profile | File-pattern scoped via `applyTo` |
 | `AGENTS.md` | Workspace root (or subfolders with experimental setting) | All agents in workspace |
+| `CLAUDE.md` | Workspace root, `.claude/`, or `~/.claude/` | Claude-compatible always-on instructions |
+| `.claude/rules/*.md` | Workspace `.claude/rules/` | Claude Rules format (uses `paths` glob array, not `applyTo`) |
 ## Requirements
 
 1. Create the file at the appropriate location: