docs(agents): align frontmatter fields and tools documentation with VS Code 1.109+

[katriendg]

Note

Partial Completion Status (assessed 2026-02-13)

Completed:

• Schema has new fields for VS Code 1.106+ features (description, tools, handoffs)
• Documentation updated for VS Code 1.106+ baseline

Remaining:

• mode field documentation not yet removed (lines 164-169 in custom-agents.md)
• Missing frontmatter fields not yet documented: agents, user-invokable, disable-model-invocation, target, mcp-servers
• maturity field still present (HVE-specific, but not reconciled with VS Code spec)
• Tools format inconsistent — no team decision on Option A vs Option B
• Missing #tool: reference syntax documentation
• Validation checklist not yet updated to remove mode field

Issue Description

The docs/contributing/custom-agents.md documentation has several discrepancies with the official VS Code custom agents documentation at .

This issue requires reflecting on the latest version from the documentation when picking up the issue! Evaluate the best way to update the tools list especially, reflecting if we should point to the official documentation instead of keeping a list in our own documentation which risks being outdated quickly due to pace of evolution of GHCP and VS code.

Changes Required:

1. Remove mode field documentation (lines 164-169) - This field does not exist in VS Code's frontmatter specification

2. Add missing frontmatter fields:

   • name - Display name (defaults to filename)
   • argument-hint - Hint text for chat input field
   • agents - List of subagent names (use * for all, [] for none)
   • model - AI model (string or prioritized array)
   • user-invokable - Controls visibility in agents dropdown (default true)
   • disable-model-invocation - Prevents subagent invocation (default false)
   • target - Environment (vscode or github-copilot)
   • mcp-servers - MCP config JSON (cloud agents only)
   • handoffs.model - Model override for handoff execution

3. Tools documentation (requires team discussion):

   • Option A: Remove tools list, reference official VS Code docs
   • Option B: Keep curated list with categories and sync disclaimer
   • Remove invalid entry Bicep (EXPERIMENTAL)/*
   • Clarify MCP tools only apply to cloud agents via mcp-servers field

4. Update validation checklist - Remove mode field validation

5. Add tool reference syntax - Document #tool: syntax

Additional Context

• VS Code docs retrieved: 2026-02-05
• VS Code version: 1.109+
• No agent files currently use mode field (documentation-only change)
• Agents using namespaced tools (execute/runInTerminal, etc.) are correct; documentation is outdated