holocron/plugins/kyberforge/skills/write-agent/references/cross-compat.md

topic, source_keys

topic	source_keys
cross-tool-agent-compatibility	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:

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.