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`	Yes (v2.1.277+, via `agents-md@builtin` — default mode reads it only when there is no `CLAUDE.md`)	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 — with one exception since Claude Code v2.1.277: AGENTS.md, through the built-in agents-md@builtin plugin. 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
`model`	No	Alias: `opus` / `sonnet` / `haiku` — never a pinned id	Ignored
`effort`	No	`low` / `medium` / `high` / `xhigh` / `max` — only honored from v2.1.267	Ignored
`paths`	No	Limit auto-activation to file globs	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)
`effort`	`low` / `medium` / `high` / `xhigh` / `max`	Not supported
`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_work_item`
Claude Code (plugin)	`mcp__plugin_<plugin>_<server>__<tool>`	`mcp__plugin_dx-aem_AEM__getNodeContent`
Copilot CLI / VS Code Chat	Bare name (no prefix)	`getNodeContent`
Codex CLI	Bare name; TOML `[mcp_servers.<server>]`. Tool names constrained to `^[a-zA-Z0-9_-]+$` — dots disallowed	`getNodeContent`
Gemini CLI	`mcp_<server>_<tool>` (single underscore). Server name must not contain `_`	`mcp_aem_getnodecontent`

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

Which platform reads which hook file -- the plugin file is shared, the rest are not.

Hook Source	Active In
Plugin `hooks/hooks.json`	Claude Code CLI (`Stop` / `SubagentStop`) and Copilot CLI — both read this same file
`.github/hooks/hooks.json`	Copilot CLI only (v1.0.10+; Notification 1.0.18+; HTTP hooks 1.0.35+)
Agent frontmatter `hooks:`	VS Code Chat only (v1.111+)

Copilot CLI v1.0.40+ needs an env var

Repo hooks in .github/hooks/hooks.json are silently ignored unless GITHUB_COPILOT_PROMPT_MODE_REPO_HOOKS=1 is exported in your shell. The same applies to project-root .mcp.json, which needs GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP=1.

Event names differ per platform

Claude Code uses Stop / SubagentStop; Copilot CLI uses agentStop / subagentStop. To give both platforms the same safety hooks, install to both locations — /dx-init step 9i does this for branch-guard and the Stop guard.

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.

Hook Events (Claude Code)

Grouped by what they observe. This mirrors the list in CLAUDE.md; the upstream hooks reference occasionally adds events ahead of us, so treat it as current-as-of-our-last-sweep rather than exhaustive.

Group	Events	Fires when	Typical use
Session	`SessionStart`, `Setup`, `SessionEnd`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`	Session starts or ends, or its environment changes	Context setup, re-read config, teardown
Prompt	`UserPromptSubmit`, `UserPromptExpansion`	A prompt is submitted, before expansion completes	Audit, inject context
Tools	`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch` (parallel-tool batch)	Around each tool invocation, or a parallel batch	Block dangerous ops, formatters, logging
Permissions	`PermissionRequest`, `PermissionDenied`	A permission is requested or denied	Audit trail, custom allow logic
Stop	`Stop`, `StopFailure`	The agent finishes a turn, or fails to	Cleanup, completion guards
Subagents & tasks	`SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle`	Subagent or background-task lifecycle	Tracking, result processing
Files & worktrees	`FileChanged`, `WorktreeCreate`, `WorktreeRemove`	A file changes on disk, or a worktree is created/removed	Re-index, workspace setup and teardown
Context	`PreCompact`, `PostCompact`	Immediately before and after compaction	Preserve state across a compact
Other	`Elicitation`, `ElicitationResult`, `Notification`	Interactive elicitation, or a notification is raised	Custom prompts, external alerting

Handler type: values: command, http, mcp_tool, prompt, agent.

Hook Authoring — Key Fields

Field	Purpose	Example
`matcher`	Which tool events to listen for	`”Bash”`, `“Edit”`, `“mcp__figma“`
`if`	Fine-grained permission-rule filter, evaluated before spawning	`”Bash(git commit*)“`
`statusMessage`	Spinner text while the hook runs	`”Checking branch protection…“`
`async`	Non-blocking background execution	`true` for observational hooks
`asyncRewake`	Background execution that wakes Claude on exit code 2	`true` for long checks that must signal failure
`timeout`	Seconds before cancelling	`30`
`once`	One-shot per session. Skill/agent frontmatter only — not `settings.json`	`true` for init scripts

Never use exit 1 to block

0 = success (JSON is parsed from stdout). 2 = blocking error, with stderr fed back as feedback. Any other code is a non-blocking error, shown only in verbose mode — so a hook that exits 1 to reject something fails open and looks like it did nothing.

Hook Profiles — `DX_HOOK_PROFILE`

Profile	Level	Behavior
`minimal`	1	Only blocking safety hooks (branch-guard). Informational hooks skipped
`standard`	2	Default. All hooks enabled
`strict`	3	All hooks plus extra guardrails (future use)

Export DX_HOOK_PROFILE=minimal to suppress informational hooks during focused work, or strict for CI and pipeline environments. Hook scripts gate themselves with source hook-profile.sh && require_profile “standard”.

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)