---
topic: cross-tool-agent-compatibility
source_keys:
  - claude-code-docs-plugins
  - github-copilot-custom-agents-config
  - plugin-marketplace-architecture
---

## The core rule

Skills are the portable primitive — identical format in both tools. Agents diverge. The system prompt body can be shared; the frontmatter and filename cannot.

## Divergence table

| Concern | Claude Code | GitHub Copilot CLI | Portable choice |
|---|---|---|---|
| File extension | `agents/<name>.md` | `agents/<name>.agent.md` | Ship both files — same body, tool-specific frontmatter |
| Required fields | `name`, `description` | `description` | Use both `name` and `description` in both files |
| `tools` format | Comma-separated string or array; internal tool names (e.g. `Read`, `Grep`, `Bash`) | Array; Copilot tool aliases (e.g. `codebase`, `search`, `edit/editFiles`) | Different values — maintain separately |
| `model` values | `sonnet`, `opus`, `haiku`, `fable`, or full model ID | Copilot model names (e.g. `GPT-4.1`, `claude-opus-4-8`) | Maintain separately |
| `permissionMode` | Supported | Not supported | Claude-only field |
| `maxTurns` | Supported | Not supported | Claude-only field |
| `skills` | Preloads skills into context | Not supported | Claude-only field |
| `mcpServers` | Inline or reference; ignored in plugin agents | `mcp-servers` (different key); not used in IDE agents | Maintain separately if needed |
| `hooks` | Supported (ignored in plugin agents) | Not supported | Claude-only field |
| `memory` | `user`, `project`, `local` | Not supported | Claude-only field |
| `background` | `true`/`false` | Not supported | Claude-only field |
| `effort` | `low`/`medium`/`high`/`xhigh`/`max` | Not supported | Claude-only field |
| `isolation` | `worktree` | Not supported | Claude-only field |
| `color` | `red`/`blue`/etc. | Not supported | Claude-only field |
| `target` | Not supported | `vscode` or `github-copilot` | Copilot-only field |
| `disable-model-invocation` | Not supported | Boolean | Copilot-only field |
| `user-invocable` | Not supported | Boolean (default `true`) | Copilot-only field |
| `metadata` | Not supported | Key-value object | Copilot-only field |

## The two-file pattern

For every cross-tool agent in a plugin, ship two files with the same body:

```text
plugins/<plugin-name>/agents/
├── <name>.md         ← Claude Code (frontmatter: name, description, tools, model, ...)
└── <name>.agent.md   ← Copilot CLI (frontmatter: name, description, tools as array, ...)
```

The system prompt body (everything below the frontmatter `---`) is identical in both. Copy-fill both from the same system prompt source. Update both when the system prompt changes.

If the agent is Claude Code-only (not intended for Copilot), ship only `<name>.md` and note it explicitly.

## Plugin-specific constraints (Claude Code)

Plugin agents in Claude Code cannot use: `hooks`, `mcpServers`, `permissionMode`. These fields are silently ignored. If the agent needs them, it must be a user-level or project-level agent (`.claude/agents/`), not a plugin agent.

## Subagent vs role skill (this repo)

A common mistake: confusing role skills with subagents.

| Type | What it is | Where it goes | When to use |
|---|---|---|---|
| Role skill | Inline mode switch; loads into current conversation | `.agents/skills/` with `category: roles` | When you want Claude to adopt a cognitive mode (Architect, Reviewer) without context isolation |
| Subagent | Fresh context window, own system prompt, isolated | `core/agents/` → deployed to `~/.claude/agents/` | When a task would flood the main context (research, parallel work, long exploration) |
| Plugin agent | Installed with plugin; same isolation as subagent | `plugins/<name>/agents/<name>.md` + `.agent.md` | When the agent is part of a distributable plugin |

Write-agent creates subagents and plugin agents. Write-skill creates role skills. Do not mix the two.

## Recommended authoring stance

Claude Code is the stricter format (more fields, security restrictions for plugins). Treat it as the source of truth. For each agent:

1. Write the Claude Code `.md` file first with all relevant frontmatter.
2. Copy the system prompt body to the Copilot `.agent.md` file.
3. Translate frontmatter: keep `name`, `description`; translate `tools` to Copilot aliases; drop Claude-only fields; add Copilot-only fields if needed.
4. Note any fields that couldn't be ported (e.g., `permissionMode`, `isolation`) as Claude-only behaviors.