feat(skills): add write-agent factory skill for cross-tool agent authoring

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>
2026-06-21 12:01:34 +00:00
parent 88f3d97d0c
commit f60b4199ce
11 changed files with 544 additions and 1 deletions
--- a/plugins/kyberforge/skills/write-agent/META.md
+++ b/plugins/kyberforge/skills/write-agent/META.md
@@ -0,0 +1,13 @@
+```yaml
+version: "1.0"
+updated: 2026-06-21
+
+when: invoked by explicit trigger ("write an agent for X", "create a subagent that does Y", "add an agent to the Z plugin") or implicit request to author a Claude Code subagent or GitHub Copilot CLI plugin agent definition file
+
+# source: omitted — self-authored original; no upstream content adopted
+
+references:
+  - https://code.claude.com/docs/en/sub-agents
+  - https://code.claude.com/docs/en/plugins-reference
+  - https://docs.github.com/en/copilot/reference/custom-agents-configuration
+```
--- a/plugins/kyberforge/skills/write-agent/SKILL.md
+++ b/plugins/kyberforge/skills/write-agent/SKILL.md
@@ -0,0 +1,111 @@
+---
+name: write-agent
+description: >
+  Use when the user wants to author a new agent definition file for Claude Code (subagent) or
+  GitHub Copilot CLI (plugin agent). Triggers: "write an agent for X", "create a subagent that
+  does Y", "add an agent to the Z plugin", "build a cross-tool agent". Do NOT use when the user
+  wants to create a role skill that loads inline into the current conversation (use /write-skill
+  with category: roles), scaffold a new plugin from scratch (use /plugin-create), edit or update
+  an existing agent definition (use upgrade-agent), or author skills inside a plugin (use
+  /write-skill).
+metadata:
+  category: factory
+model: sonnet
+---
+
+<requirements>
+
+## Required inputs
+
+- **Agent type** — standalone subagent or plugin agent; inferred from request if obvious ("add an agent to plugin X" → plugin agent, "create a subagent" → standalone), ask if ambiguous
+- **Agent name** — kebab-case slug; inferred from user description if not stated, ask if ambiguous
+- **Plugin name** — plugin agents only; must be an existing plugin in `plugins/`; ask if not stated
+- **Purpose + use cases** — what the agent does, what tasks it handles exclusively; source for the `description` field and system prompt body
+- **Tool access rationale** — which tools the agent needs and why (allowlist, denylist, or inherit all); ask if not stated
+
+## Constraints
+
+- One skill, two branches — determine agent type before any other step; do not proceed until type is confirmed
+- Plugin agents: always generate both `<name>.md` (Claude Code) and `<name>.agent.md` (Copilot CLI) — same system prompt body, translated frontmatter; never generate one without the other
+- Plugin agents: `plugins/<name>/` must exist before writing — stop and redirect to `/plugin-create` if not found
+- Standalone subagents: write to `core/agents/<name>.md` per ADR-0010 — never write directly to `.claude/agents/`
+- Do not create role skills (inline mode switches, `category: roles`) — if the user wants a cognitive mode switch without context isolation, redirect to `/write-skill`
+- Load `references/cross-compat.md` before writing any plugin agent frontmatter — Claude Code and Copilot CLI diverge in field names, tool names, and supported features
+- Copy agent files from `assets/` templates — never generate from memory; stop and report the path if a template is missing
+- Flag Claude-only fields (`permissionMode`, `isolation`, `maxTurns`, `memory`, `hooks`, `mcpServers`) in a handoff comment when generating `.agent.md` — these have no Copilot CLI equivalent
+- Body under 500 lines
+
+</requirements>
+
+<steps>
+
+## Process
+
+1. **Determine type.** Infer standalone subagent or plugin agent from the request. Ask if ambiguous. Hard gate: do not proceed until type is confirmed.
+
+2. **Validate target.** For plugin agents: confirm `plugins/<name>/` exists. Stop and redirect to `/plugin-create` if not. For standalone subagents: confirm `core/agents/` exists.
+
+3. **Scan for overlap.** Check `core/agents/` (standalone) or `plugins/<name>/agents/` (plugin) for agents with similar purpose or name. Surface any found and wait for direction before continuing.
+
+4. **Grill.** One question at a time, with a recommendation for each: agent name, purpose, tasks it handles exclusively, what it explicitly does NOT do, tool access rationale, model selection, isolation needs (subagents only), and any optional fields worth setting. Stop when there is shared understanding of all five required inputs.
+
+5. **Conflict check.** Spawn a sub-agent: read `docs/ai-constitution.md`, `docs/research/ai-coding-factory/ai-coding-factory-principles.md`, and `docs/notes/factory-integration-decisions.md`, then check the agreed agent design against all three. Return a numbered list of genuine unresolved tensions, or confirm none found. Hard gate: resolve any findings before proceeding.
+
+6. **Write and test the description field.** Draft the `description:` using the agreed purpose and use cases — this is what Claude reads to decide whether to delegate. Propose negative trigger cases; get explicit user confirmation. Test explicit, implicit, and negative cases and show per-case PASS/FAIL. A failed case means revise and retest — do not proceed.
+
+7. **Walk through the system prompt body.** Propose the body section by section: role statement, task scope, explicit out-of-scope items, behavioral constraints. Wait for explicit confirmation of each before writing.
+
+8. **Walk through optional frontmatter.** For each optional field (`model`, `tools`, `disallowedTools`, `maxTurns`, `effort`, `isolation`, `permissionMode`, `memory`, `background`): propose a value if warranted by the agreed design, or confirm omission. Load `references/claude-code-agents.md` for field semantics. Wait for confirmation of each.
+
+9. **Check template.** Load the appropriate template(s) from `assets/`: `subagent.md` for standalone subagents; `plugin-agent-claude.md` and `plugin-agent-copilot.md` for plugin agents. Stop and report the path if any template is missing — do not generate from memory.
+
+10. **Copy and fill.** Copy the template(s) to the target path(s). Fill with confirmed content. For plugin agents: load `references/cross-compat.md` and translate Claude frontmatter to Copilot equivalents in `<name>.agent.md`. Keep both bodies identical. Note Claude-only fields that have no Copilot equivalent in a handoff comment at the top of `<name>.agent.md`.
+
+11. **Invoke `write-eval`.** Do not mark the agent complete without an eval file.
+
+12. **Run self-check.** Work through every item in the Self-check section below.
+
+13. **Prompt for HITL.** Ask the user to open a fresh session, trigger the agent, and confirm behavior before committing.
+
+## Output format
+
+For standalone subagents:
+- `core/agents/<name>.md` — copy-filled from `assets/subagent.md`
+- `plugins/kyberforge/skills/write-agent/evals/<name>.yaml` — produced by write-eval
+
+For plugin agents:
+- `plugins/<plugin-name>/agents/<name>.md` — copy-filled from `assets/plugin-agent-claude.md`
+- `plugins/<plugin-name>/agents/<name>.agent.md` — copy-filled from `assets/plugin-agent-copilot.md`; Claude-only fields noted in a handoff comment at the top
+- `plugins/kyberforge/skills/write-agent/evals/<name>.yaml` — produced by write-eval
+
+</steps>
+
+<checks>
+
+## Failure handling
+
+- Agent type cannot be determined from the request — stop and ask; do not proceed without explicit type confirmation
+- `plugins/<name>/` not found for a plugin agent — stop, report the path checked, redirect to `/plugin-create`
+- `core/agents/` not found for a standalone subagent — stop, report the path, do not write to `.claude/agents/` directly
+- Template missing from `assets/` — stop, report the exact path searched, do not generate from memory
+- Overlap found in target directory — surface it and wait for explicit direction; do not continue
+- `write-eval` fails or is unavailable — flag, do not mark the agent complete
+- Conflict check sub-agent returns unresolved tensions — resolve before writing any file
+
+## Self-check
+
+- [ ] Agent type confirmed before any other step
+- [ ] Plugin validated to exist at `plugins/<name>/` before any file was written (plugin agents only)
+- [ ] Overlap check completed in the correct target directory before any content was written
+- [ ] Conflict check sub-agent ran — all findings resolved before writing began
+- [ ] Description field tested against explicit, implicit, and negative cases — all passed before body was written
+- [ ] Negative trigger cases confirmed by user before testing
+- [ ] System prompt body confirmed section by section before writing
+- [ ] Optional frontmatter fields confirmed or explicitly omitted
+- [ ] Template(s) loaded from `assets/` — not generated from memory
+- [ ] For plugin agents: both `.md` and `.agent.md` written; bodies are identical; Claude-only fields noted in handoff comment
+- [ ] `references/cross-compat.md` loaded before translating plugin agent frontmatter (plugin agents only)
+- [ ] Standalone subagent written to `core/agents/<name>.md` — not to `.claude/agents/`
+- [ ] `write-eval` invoked — eval file exists and covers trigger cases
+
+</checks>
--- a/plugins/kyberforge/skills/write-agent/assets/plugin-agent-claude.md
+++ b/plugins/kyberforge/skills/write-agent/assets/plugin-agent-claude.md
@@ -0,0 +1,8 @@
+---
+name: AGENT_NAME
+description: AGENT_DESCRIPTION
+tools: AGENT_TOOLS
+model: AGENT_MODEL
+---
+
+AGENT_SYSTEM_PROMPT
--- a/plugins/kyberforge/skills/write-agent/assets/plugin-agent-copilot.md
+++ b/plugins/kyberforge/skills/write-agent/assets/plugin-agent-copilot.md
@@ -0,0 +1,14 @@
+<!-- HANDOFF: The following Claude Code fields were not ported — no Copilot CLI equivalent:
+     CLAUDE_ONLY_FIELDS_NOTE
+     Add Copilot-specific fields (target, disable-model-invocation, user-invocable) if needed.
+     Verify tool names against Copilot CLI tool aliases (codebase, search, edit/editFiles, etc.)
+     rather than Claude Code internal names (Read, Grep, Bash, etc.). -->
+---
+name: AGENT_NAME
+description: AGENT_DESCRIPTION
+tools:
+  - AGENT_TOOLS_COPILOT
+model: AGENT_MODEL_COPILOT
+---
+
+AGENT_SYSTEM_PROMPT
--- a/plugins/kyberforge/skills/write-agent/assets/subagent.md
+++ b/plugins/kyberforge/skills/write-agent/assets/subagent.md
@@ -0,0 +1,8 @@
+---
+name: AGENT_NAME
+description: AGENT_DESCRIPTION
+tools: AGENT_TOOLS
+model: AGENT_MODEL
+---
+
+AGENT_SYSTEM_PROMPT
--- a/plugins/kyberforge/skills/write-agent/evals/write-agent.yaml
+++ b/plugins/kyberforge/skills/write-agent/evals/write-agent.yaml
@@ -0,0 +1,103 @@
+skill_name: write-agent
+
+trigger_tests:
+  - id: explicit-basic
+    name: Explicit trigger — basic invocation
+    query: "write an agent for code review"
+    should_trigger: true
+
+  - id: explicit-plugin
+    name: Explicit trigger — plugin agent
+    query: "add an agent to the security-tools plugin"
+    should_trigger: true
+
+  - id: implicit-isolation
+    name: Implicit trigger — isolated worker need
+    query: "I need a specialized worker that handles DB migrations in isolation"
+    should_trigger: true
+
+  - id: negative-role-skill
+    name: Negative — role skill (inline mode switch)
+    query: "Add an architect role to my session"
+    should_trigger: false
+
+  - id: negative-plugin-create
+    name: Negative — plugin scaffolding
+    query: "Create a new plugin called security-tools"
+    should_trigger: false
+
+  - id: negative-edit-existing
+    name: Negative — editing an existing agent
+    query: "Update the description on my existing code-reviewer agent"
+    should_trigger: false
+
+  - id: negative-skill-authoring
+    name: Negative — skill authoring inside a plugin
+    query: "Write a skill for my refactor plugin"
+    should_trigger: false
+
+output_tests:
+  - id: subagent-output-path
+    name: Standalone subagent written to core/agents/
+    type: deterministic
+    prompt: "Create a standalone subagent called db-migrator that runs database migrations in an isolated context"
+    expected_output: >
+      The skill produces a file at core/agents/db-migrator.md containing valid YAML frontmatter
+      with at minimum name and description fields, followed by a system prompt body.
+    assertions:
+      - "Output references the file path core/agents/db-migrator.md"
+      - "Output does not reference .claude/agents/ as the write target"
+      - "Generated file contains a --- frontmatter block with name: db-migrator"
+
+  - id: plugin-agent-dual-file
+    name: Plugin agent produces both .md and .agent.md
+    type: deterministic
+    prompt: "Add a cross-tool agent called security-scanner to the existing kyberforge plugin"
+    expected_output: >
+      The skill produces two files: plugins/kyberforge/agents/security-scanner.md (Claude Code)
+      and plugins/kyberforge/agents/security-scanner.agent.md (Copilot CLI). Both files share
+      an identical system prompt body.
+    assertions:
+      - "Output references plugins/kyberforge/agents/security-scanner.md"
+      - "Output references plugins/kyberforge/agents/security-scanner.agent.md"
+      - "Skill does not produce only one of the two files"
+
+  - id: claude-frontmatter-required-fields
+    name: Claude Code agent file contains required frontmatter fields
+    type: deterministic
+    prompt: "Write an agent for linting that reads files and reports violations"
+    expected_output: >
+      The generated .md file contains a YAML frontmatter block with at minimum name: and
+      description: fields. The description field contains delegation guidance — when Claude
+      should invoke this agent.
+    assertions:
+      - "Generated frontmatter contains name:"
+      - "Generated frontmatter contains description:"
+      - "The description value is not empty or a placeholder"
+
+  - id: copilot-handoff-comment
+    name: Copilot CLI .agent.md contains handoff comment for Claude-only fields
+    type: deterministic
+    prompt: "Add a plugin agent to the kyberforge plugin that uses permissionMode: bypassPermissions and isolation: worktree"
+    expected_output: >
+      The generated .agent.md file contains a comment at the top noting that permissionMode
+      and isolation are Claude Code-only fields with no Copilot CLI equivalent.
+    assertions:
+      - "The .agent.md file contains a HANDOFF comment or equivalent note"
+      - "The comment names at least one Claude-only field that was not ported"
+      - "The .agent.md frontmatter does not contain permissionMode or isolation fields"
+
+  - id: description-field-quality
+    name: LLM rubric — description field names specific tasks not just a role
+    type: llm-rubric
+    prompt: "Create a standalone subagent called api-tester that tests REST API endpoints for correctness and schema compliance"
+    expected_output: >
+      The description field in the generated agent file should specify delegation conditions
+      precisely enough that an orchestrator model can decide whether to invoke this agent
+      without ambiguity. It should name the task domain, the conditions for delegation,
+      and ideally one or more negative cases. A description that only says "Tests APIs" or
+      restates the agent name is insufficient.
+    assertions:
+      - "The description field mentions what kind of task triggers delegation to this agent"
+      - "The description field does not simply restate the agent name"
+      - "The description is specific enough to distinguish this agent from a general-purpose testing agent"
--- a/plugins/kyberforge/skills/write-agent/references/claude-code-agents.md
+++ b/plugins/kyberforge/skills/write-agent/references/claude-code-agents.md
@@ -0,0 +1,91 @@
+---
+topic: claude-code-agents
+source_keys:
+  - claude-code-docs-subagents
+  - claude-code-docs-plugins
+---
+
+## Overview
+
+Claude Code agents (called subagents) are Markdown files with YAML frontmatter stored in one of several scoped locations. Each runs in its own context window with a custom system prompt, specific tool access, and independent permissions. The parent conversation delegates to a subagent when its `description` matches the task.
+
+## File format
+
+```markdown
+---
+name: code-reviewer
+description: Reviews code for correctness, security, and maintainability. Use proactively after code changes.
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+You are a senior code reviewer. Review for:
+1. Correctness: logic errors, edge cases
+2. Security: injection, auth bypass
+3. Maintainability: naming, complexity
+```
+
+The body becomes the subagent's system prompt. Subagents receive only this system prompt plus basic environment details (working directory) — not the full Claude Code system prompt and not the parent conversation history.
+
+## Supported frontmatter fields
+
+Only `name` and `description` are required. All others are optional.
+
+| Field | Description |
+|---|---|
+| `name` | Unique identifier: lowercase letters and hyphens. Used as `agent_type` in hooks. Filename does not have to match. |
+| `description` | When Claude should delegate to this subagent — determines automatic routing. Write imperatively. |
+| `tools` | Allowlist of tools the subagent can use. Inherits all tools if omitted. Comma-separated or array. Use `Agent(type1, type2)` syntax to restrict which subagents this agent can spawn. |
+| `disallowedTools` | Denylist — removed from inherited or specified list. If both `tools` and `disallowedTools` are set, denylist is applied first. Supports `mcp__<server>` patterns. |
+| `model` | Model alias (`sonnet`, `opus`, `haiku`, `fable`) or full ID (`claude-opus-4-8`). Defaults to `inherit` (parent model). |
+| `permissionMode` | `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`. Inherited from parent; parent's mode takes precedence if stricter. **Ignored for plugin agents.** |
+| `maxTurns` | Maximum agentic turns before the subagent stops. |
+| `skills` | Skills to preload into the subagent's context at startup (full skill content injected, not just description). |
+| `mcpServers` | MCP servers scoped to this subagent. Inline definitions connect on start, disconnect on finish. String references reuse the parent session's connection. **Ignored for plugin agents.** |
+| `hooks` | Lifecycle hooks scoped to this subagent. **Ignored for plugin agents.** |
+| `memory` | Persistent memory scope: `user`, `project`, or `local`. Enables cross-session learning. |
+| `background` | `true` to always run as a background task. Default: `false`. |
+| `effort` | Reasoning effort: `low`, `medium`, `high`, `xhigh`, `max`. Overrides session effort level. |
+| `isolation` | `worktree` — runs in a temporary git worktree (isolated repo copy). Auto-cleaned up if no changes. |
+| `color` | Display color in the task list: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. |
+| `initialPrompt` | Auto-submitted as the first user turn when this agent runs as the main session agent (via `--agent`). |
+
+## Storage locations and scope priority
+
+| Location | Scope | Priority |
+|---|---|---|
+| Managed settings `.claude/agents/` | Organization-wide | 1 (highest) |
+| `--agents` CLI flag | Current session only | 2 |
+| `.claude/agents/` | Current project | 3 |
+| `~/.claude/agents/` | All projects (user-level) | 4 |
+| Plugin `agents/` directory | Where plugin is enabled | 5 (lowest) |
+
+When the same `name` is defined in multiple locations, the highest-priority location wins. Claude Code scans both `.claude/agents/` and `~/.claude/agents/` recursively — files can be organized into subfolders. Identity comes from the `name` frontmatter, not the filename.
+
+## Plugin agent constraints
+
+Plugin agents (in a plugin's `agents/` directory) have three fields ignored for security reasons:
+- `hooks` — ignored
+- `mcpServers` — ignored
+- `permissionMode` — ignored
+
+If any of these are needed, copy the agent file to `.claude/agents/` or `~/.claude/agents/` instead.
+
+Plugin agents in subfolders get a scoped identifier: `plugin-name:subfolder:agent-name` (e.g., a file at `agents/review/security.md` in plugin `my-plugin` registers as `my-plugin:review:security`).
+
+## Repo-specific placement (this repo)
+
+Per ADR-0010, two categories of agent definitions exist in this repo:
+
+- **Subagent definitions** (isolated context, separate context window): live in `core/agents/` — deployed to `~/.claude/agents/` by `install.sh`. These are the "true" subagents.
+- **Plugin agents**: live in `plugins/<name>/agents/<name>.md`. Installed with the plugin.
+- **Role skills** (inline mode switches, NOT agents): live in `.agents/skills/` with `category: roles`.
+
+Never put role skills in `core/agents/`. Never put subagent definitions in `.agents/skills/`. The distinction is the isolation boundary — subagents get a fresh context window; role skills load inline.
+
+## Model routing guidance (from factory §9)
+
+- `haiku` — formatting, classification, fast lookups
+- `sonnet` — most coding, review, analysis
+- `opus` — adversarial reasoning, complex multi-step, security-critical
+- Omit `model` to inherit from the parent session
--- a/plugins/kyberforge/skills/write-agent/references/copilot-cli-agents.md
+++ b/plugins/kyberforge/skills/write-agent/references/copilot-cli-agents.md
@@ -0,0 +1,86 @@
+---
+topic: copilot-cli-agents
+source_keys:
+  - github-copilot-custom-agents-config
+  - github-blog-copilot-cli-agents
+---
+
+## Overview
+
+GitHub Copilot CLI agents are defined as Markdown files with `.agent.md` extension and YAML frontmatter. They live in the `.github/agents/` directory of a repository and are version-controlled with the codebase. Users invoke them via the `/agent` slash command in the CLI.
+
+## File format
+
+```markdown
+---
+name: Accessibility Expert
+description: Expert assistant for web accessibility (WCAG 2.1/2.2)
+model: GPT-4.1
+tools:
+  - codebase
+  - edit/editFiles
+  - search
+---
+
+# Accessibility Expert
+
+You are a web accessibility expert. Focus on WCAG 2.1/2.2 compliance...
+```
+
+The body (below frontmatter) contains the agent's instructions in Markdown. Maximum 30,000 characters.
+
+## Supported frontmatter fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | String | Recommended | Display identifier for the agent |
+| `description` | String | Required | Purpose and capabilities — what this agent does |
+| `target` | String | No | `vscode`, `github-copilot`, or omit for both |
+| `model` | String | No | Model to use (e.g., `GPT-4.1`, `claude-opus-4-8`). Inherits default if unset. |
+| `tools` | List | No | Tools the agent can use. Defaults to all tools if omitted. |
+| `disable-model-invocation` | Boolean | No | When `true`, requires manual agent selection. |
+| `user-invocable` | Boolean | No | Whether user can manually select this agent. Defaults to `true`. |
+| `mcp-servers` | Object | No | Additional MCP server configurations. Not used in VS Code/IDE agents. |
+| `metadata` | Object | No | Key-value annotation pairs. Not applicable to IDE agents. |
+
+## Tools field
+
+Tools can be configured three ways:
+
+- **All tools** (default): omit the `tools` property, or use `tools: ["*"]`
+- **Specific tools**: list names, e.g. `tools: ["codebase", "edit/editFiles", "search"]`
+- **No tools**: `tools: []`
+
+Available tool aliases (case-insensitive): `execute`, `read`, `edit`, `search`, `agent`, `web`, `todo`.
+
+MCP server tools use namespacing: `mcp-server-name/tool-name` or `mcp-server-name/*` for all tools from a server.
+
+Some available tools: `gh`, `git`, `codebase`, `search`, `githubRepo`, `runCommands`, `runTests`, `edit/editFiles`, `terraform`, `conftest`, `jq`, `curl`, `semgrep`, `trivy`, `gitleaks`.
+
+## File location
+
+Copilot CLI agents live in `.github/agents/` in the repository root. The filename uses the `.agent.md` extension (e.g., `accessibility.agent.md`).
+
+## Plugin placement (this repo)
+
+Per the cross-compat reference, plugin agents for Copilot CLI use the `.agent.md` naming:
+- Claude Code reads: `agents/<name>.md`
+- Copilot CLI reads: `agents/<name>.agent.md`
+
+Both files share the same system prompt body. Only the frontmatter differs: Copilot uses `tools:` as an array with different tool names; Claude Code uses `tools:` as comma-separated internal tool names.
+
+## Fields not supported in Copilot CLI
+
+These Claude Code agent fields have no Copilot CLI equivalent:
+- `permissionMode`
+- `maxTurns`
+- `skills` (Claude-specific skill injection)
+- `mcpServers` (inline per-agent MCP — not supported in VS Code/IDE)
+- `hooks`
+- `memory`
+- `background`
+- `effort`
+- `isolation`
+- `color`
+- `initialPrompt`
+- `disallowedTools`
--- a/plugins/kyberforge/skills/write-agent/references/cross-compat.md
+++ b/plugins/kyberforge/skills/write-agent/references/cross-compat.md
@@ -0,0 +1,73 @@
+---
+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.
--- a/plugins/kyberforge/skills/write-agent/references/sources.md
+++ b/plugins/kyberforge/skills/write-agent/references/sources.md
@@ -0,0 +1,36 @@
+# Sources
+
+## claude-code-docs-subagents
+
+- **URL:** https://code.claude.com/docs/en/sub-agents
+- **Description:** Official Claude Code documentation on creating and configuring custom subagents — all frontmatter fields, scope priority, tool restrictions, permission modes.
+- **Contributing files:** claude-code-agents.md, cross-compat.md
+- **Status:** `extracted`
+
+## claude-code-docs-plugins
+
+- **URL:** https://code.claude.com/docs/en/plugins-reference
+- **Description:** Official Claude Code plugin reference — agent fields available in plugin context and security restrictions (hooks, mcpServers, permissionMode ignored).
+- **Contributing files:** claude-code-agents.md, cross-compat.md
+- **Status:** `extracted`
+
+## github-copilot-custom-agents-config
+
+- **URL:** https://docs.github.com/en/copilot/reference/custom-agents-configuration
+- **Description:** GitHub Copilot custom agents configuration reference — all frontmatter fields, tools field format, target field, mcp-servers.
+- **Contributing files:** copilot-cli-agents.md, cross-compat.md
+- **Status:** `extracted`
+
+## github-blog-copilot-cli-agents
+
+- **URL:** https://github.blog/ai-and-ml/github-copilot/from-one-off-prompts-to-workflows-how-to-use-custom-agents-in-github-copilot-cli/
+- **Description:** GitHub blog post on Copilot CLI custom agents — .agent.md format, tool names, invocation pattern.
+- **Contributing files:** copilot-cli-agents.md
+- **Status:** `extracted`
+
+## plugin-marketplace-architecture
+
+- **URL:** /root/ai-development/plugins/kyberforge/docs/plugin-marketplace-architecture.md
+- **Description:** Repo-internal reference on Claude Code vs Copilot CLI divergence, two-file agent pattern, plugin constraints.
+- **Contributing files:** cross-compat.md
+- **Status:** `extracted`
--- a/plugins/kyberforge/skills/write-skill/CATEGORIES.md
+++ b/plugins/kyberforge/skills/write-skill/CATEGORIES.md
@@ -11,6 +11,6 @@
 | `operate` | write-runbook, incident-diagnosis, post-mortem, inspect-deployment |
 | `iac` | write-ansible-role, write-terraform-module, write-k8s-manifest, write-docker-compose, proxmox-vm-spec, iac-security-review, write-molecule-test |
 | `cross-cutting` | zoom-out, caveman, session-handoff, governance-check, git-guardrails, git-commit-message |
-| `factory` | write-skill, write-adr, write-workflow, write-eval, validate-skill, upgrade-skill, write-issue-spec |
+| `factory` | write-skill, write-agent, write-adr, write-workflow, write-eval, validate-skill, upgrade-skill, write-issue-spec |
 | `marketplace` | marketplace-architect — plugin and skill distribution tooling for Claude Code / GitHub Copilot CLI |
 | `roles` | architect, developer, reviewer, security, qa, ops — Chunk 5 |