Defame1297
f60b4199ce
Adds write-agent to plugins/kyberforge/skills/ — a factory skill parallel to write-skill that authors Claude Code subagent definitions and cross-tool plugin agents (Claude Code + GitHub Copilot CLI two-file pattern). Includes research references (claude-code-agents.md, copilot-cli-agents.md, cross-compat.md), three asset templates (subagent, plugin-agent-claude, plugin-agent-copilot), eval coverage, and CATEGORIES.md updated to register write-agent in the factory category per the conflict check finding. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
74 lines
4.4 KiB
Markdown
74 lines
4.4 KiB
Markdown
---
|
|
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.
|