holocron/plugins/kyberforge/skills/write-agent/SKILL.md

name, description, metadata, model

name	description	metadata	model
write-agent	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).	category factory	sonnet

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

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

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