Technical Reference

Frontmatter specs, compatibility matrices, MCP tool naming, and debugging playbook

Discovery

File Discovery Matrix

Which platform reads which files.

File / Folder	Claude Code	VS Code Copilot
`.claude/agents/*.md`	Yes	Yes
`.github/agents/*.agent.md`	No	Yes
`.claude/skills/*/SKILL.md`	Yes	Yes
`.claude/rules/*.md`	Yes	Yes
`.github/instructions/*/.instructions.md`	No	Yes (recursive since v1.111)
`CLAUDE.md`	Yes	Yes (via setting)
`AGENTS.md`	No	Yes
`.mcp.json`	Yes	No
`.vscode/mcp.json`	No	Yes

Cross-Platform Rule

VS Code reads Claude’s formats. Claude does NOT read VS Code’s formats. Shared agents go in .claude/agents/. Shared skills go in .claude/skills/.

Frontmatter

Skill Frontmatter Spec

Every field a skill can use, with platform compatibility.

Field	Required	Claude Code	Copilot CLI
`name`	Yes	Slash command name	Slash command name
`description`	Yes	Auto-invocation matching	Help text
`argument-hint`	No	UI placeholder	UI placeholder
`context: fork`	No	Isolated subagent	Ignored (runs inline)
`agent`	No	Subagent type for fork	Ignored
`disable-model-invocation`	No	Prevent auto-invoke	Supported

Frontmatter

Agent Frontmatter Spec

Full field comparison across both platforms.

Field	Claude Code	Copilot
`name`	`kebab-case`	`PascalCase`
`tools`	Comma string: `Read, Glob, Bash`	YAML list: `[read, search, execute]`
`model`	Alias: `sonnet`, `opus`	Full string or array (fallback chain)
`memory`	`project / user / local`	Not supported
`isolation`	`worktree`	Not supported
`agents`	N/A	Subagent restriction list
`handoffs`	N/A	Workflow navigation buttons
`hooks`	Supported (settings.json + frontmatter)	Frontmatter only (v1.111+ preview)
`user-invocable`	N/A	Controls visibility in agent picker
`maxTurns`	Number	Ignored
`permissionMode`	String	Ignored
Max body	No limit	30,000 characters

MCP

MCP Tool Naming

Getting tool names right is critical -- wrong prefixes cause silent failures.

Context	Format	Example
Claude Code (project-level)	`mcp__<server>__<tool>`	`mcp__ado__wit_get_work_item`
Claude Code (plugin)	`mcp__plugin_<plugin>_<server>__<tool>`	`mcp__plugin_dx-aem_AEM__getNodeContent`
Copilot	`<server>/<tool>`	`ado/wit_get_work_item`

Plugin MCP Prefix

MCP servers in a plugin’s .mcp.json get the full prefix: mcp__plugin_<plugin-name>_<server>__<tool>. Using the shorthand (mcp__AEM__ instead of mcp__plugin_dx-aem_AEM__) causes “tool not found” failures.

Copilot Tool Alias Mapping

Copilot Alias	Claude Code Equivalent
`execute` / `shell`	`Bash`
`read`	`Read`
`edit`	`Edit`, `Write`
`search`	`Grep`, `Glob`
`agent`	`Task` (Agent tool)
`web`	`WebSearch`, `WebFetch`

Hooks

Hook System

Platform-separated hook architecture -- no overlap, no double-firing.

Hook Source	Active In
Plugin `hooks/hooks.json`	Claude Code CLI only
`.github/hooks/hooks.json`	Copilot CLI only (v1.0.10+)
Agent frontmatter `hooks:`	VS Code Chat only (v1.111+)

Hook Events

Pre-Tool Hooks

PreToolUse fires before any tool invocation. Use to block dangerous operations or modify input. The branch-guard hook blocks commits on protected branches.

Post-Tool Hooks

PostToolUse fires after tool completion. Use for auto-formatting, logging, or result processing. PostToolUseFailure fires on tool errors.

All Supported Events

Event	When	Use Cases
`PreToolUse`	Before tool invocation	Block dangerous ops, modify input
`PostToolUse`	After tool completes	Formatters, logging
`UserPromptSubmit`	User submits prompt	Audit, inject context
`SessionStart`	Session begins	Context setup
`SubagentStart / Stop`	Subagent lifecycle	Tracking, result processing
`Stop`	Agent finishes	Cleanup

Debug

Debugging Playbook

Common issues and how to fix them.

Skill Not Found

Check file is at correct skills path
Verify name: in frontmatter matches what you are typing
Check description: contains trigger phrases for auto-invocation
Verify no trailing spaces on --- delimiters

MCP Tools Not Available

Check server is running
Verify config in .mcp.json or .claude/settings.json
If agent, check that tools: is NOT set (blocks MCP inheritance)
Run ToolSearch(“+servername”) to load deferred tools

Copilot Agent Not Appearing

File must have .agent.md extension
Must be in .github/agents/ directory
Check user-invokable: is not false
Restart VS Code after adding new agents
Use /troubleshoot to inspect loaded customizations

Deferred vs Pre-loaded MCP

If tools: is omitted, MCP tools are deferred — must ToolSearch before calling
If tools: lists MCP tools explicitly, they are pre-loaded — ToolSearch returns nothing
Always try calling the tool directly first, fall back to ToolSearch

The #2 Gotcha: ToolSearch False Negatives

If an agent has MCP tools explicitly listed in tools:, those tools are pre-loaded and ToolSearch will return nothing for them. This leads agents to wrongly conclude MCP is unavailable. Always try calling the tool directly first.

Settings

Settings Reference

Configuration file hierarchy and key fields.

File Hierarchy (highest priority first)

Priority	Location
1 (highest)	Enterprise managed settings
2	`~/.claude/settings.json` (user)
3	`.claude/settings.json` (project)
4 (lowest)	`.claude/settings.local.json` (local, gitignored)

Permission Modes

Mode	Behavior
`default`	Prompts on first use of each tool
`acceptEdits`	Auto-accepts file edits, prompts for other tools
`plan`	Read-only, no modifications allowed
`dontAsk`	Auto-denies unless pre-approved via permissions
`bypassPermissions`	Skips all prompts (isolated environments only)