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

---
name: agent-author
description: >
  Use when the user wants to create a new agent definition file from scratch
  ("write an agent for X", "build a subagent that does Y", "create an agent
  definition for Z"), or improve an existing one. Handles both Claude Code and
  GitHub Copilot CLI agent formats, at plugin, project, and user scope — always
  generating both provider files in one pass. Also use when the user provides
  inline feedback about an agent's behavior and wants it applied, or when a
  grill session has produced findings the user wants acted on — even if they
  don't say "improve" explicitly. Do not use for read-only review — examine
  agent files manually or run a grill session to generate improvement signals.
  Do not use to author skills — use /skill-author instead.
allowed-tools: Bash Read Write Edit
metadata:
  category: factory
  source_keys:
    - context7-websites-code-claude
    - claude-code-plugins-docs
    - claude-code-subagents-docs
    - context7-github-en-copilot
    - github-custom-agents-configuration
    - github-cli-plugin-reference
    - github-plugins-creating
---

## Gotchas

- If the agent lives inside a plugin (its path contains a `plugin.json`), bump the plugin version after every change — in both `plugin.json` and `.claude-plugin/plugin.json` in the same edit pass. Convention: new agent → minor bump; improvement or fix → patch bump. Plugin consumers compare this version to detect updates; skipping it makes the change invisible.
- Plugin agents silently ignore `hooks`, `mcpServers`, and `permissionMode` — these fields have no effect and produce no warning. They only work in `.claude/agents/` or `~/.claude/agents/`.
- `AskUserQuestion`, `EnterPlanMode`, `ExitPlanMode`, and `ScheduleWakeup` are never available to any subagent regardless of the `tools` field.
- Duplicate `name` values in the same scope: Claude Code silently discards one without warning. Always verify uniqueness before shipping.
- Plugin agents in subdirectories get scoped identifiers (`plugin:folder:name`). Keep agents flat in `agents/` to avoid this.
- Copilot CLI agent files **must** use the `.agent.md` extension. A plain `.md` file is not picked up by Copilot.
- Copilot has no `permissionMode`, `maxTurns`, `isolation`, or `memory` fields — do not include them in the Copilot file.
- `model` resolution order for Claude Code: `CLAUDE_CODE_SUBAGENT_MODEL` env var → per-invocation parameter → frontmatter `model` → main session model. The frontmatter value is a low-priority default, not a guarantee.

If the destination is a plugin directory, read `references/deployment-modes.md`.

## Route

Determine which flow before touching the filesystem:

- **Neither `<name>.md` nor `<name>.agent.md` exist at the target paths** → follow **Creating a new agent**
- **At least one file exists + improvement signals present** → follow **Improving an existing agent**
- **At least one file exists + no signals** → ask: "No improvement signals found. Did you mean to create a new agent, or do you have feedback to apply?"

Signals: grill session output, inline user feedback, session context describing what went wrong.

## Creating a new agent

### Prerequisites

Before touching the filesystem, confirm you have:
- [ ] Agent name (kebab-case, e.g. `code-reviewer`)
- [ ] Root directory (plugin root, project root, or `~` for user scope)
- [ ] Agent purpose — one sentence describing the task this agent handles
- [ ] Trigger condition — when should the runtime delegate to this agent?

If any are missing, stop and ask before proceeding.

### Step 1 — Scaffold

Run the scaffold script with the agent name and root directory:

```bash
bash scripts/new-agent.sh <name> <root>
```

Examples:
```bash
bash scripts/new-agent.sh code-reviewer plugins/kyberforge/
bash scripts/new-agent.sh deploy-assistant .
bash scripts/new-agent.sh security-reviewer ~
```

**Scope detection (script handles this automatically):**
- Root contains `plugin.json` → plugin scope → creates `<root>/agents/<name>.md` + `<root>/agents/<name>.agent.md`
- Root is a project directory (no `plugin.json`) → creates `<root>/.claude/agents/<name>.md` + `<root>/.github/agents/<name>.agent.md`
- Root is `~` → creates `~/.claude/agents/<name>.md` + `~/.copilot/agents/<name>.agent.md`

The script is file-by-file no-op — it skips any file that already exists.

### Step 2 — Fill in the Claude Code agent file (`<name>.md`)

Open the scaffolded Claude Code file. Replace every `FILL IN:` placeholder.

**`name`** — lowercase letters and hyphens only. Must be unique within the scope.

**`description`** — the most important field for autonomous delegation:
- Start with an action verb: "Reviews...", "Analyzes...", "Generates..."
- Include "Use proactively" to trigger automatic invocation without explicit user direction
- Specific about the triggering condition and expertise domain
- Under 300 characters preferred

**`tools`** — restrict to what the agent actually needs. Omit to inherit all tools. Use `Agent(type1,type2)` to limit which subagent types this agent can spawn; omit `Agent` entirely to prevent spawning.

**Optional fields worth considering:**
- `model`: set when this agent needs a different capability tier (`haiku` for fast tasks, `opus` for deep reasoning)
- `maxTurns`: set a cap to prevent runaway agents on bounded tasks
- `effort`: set to `low` for single-lookup tasks, `high` or above for deep reasoning or multi-file analysis — overrides session effort level; omit to inherit
- `memory`: `user`, `project`, or `local` — only when cross-session state is genuinely needed
- `isolation: worktree` — only when the agent modifies files and needs an isolated copy

**System prompt body** — write as a direct role instruction:
- Open with: "You are a [role]. When invoked, [primary action]."
- Cover: inputs expected, process steps, output format, error handling
- One job per agent

### Step 3 — Fill in the Copilot CLI agent file (`<name>.agent.md`)

Open the scaffolded Copilot file. Replace every `FILL IN:` placeholder.

**Field differences from Claude Code:**
- `tools` uses Copilot aliases: `execute` (shell), `read`, `edit`, `search`, `agent`, `web`
- `target`: `vscode`, `github-copilot`, or omit for both (default: both)
- `user-invocable`: set `false` to hide from manual invocation (auto-select only)
- `disable-model-invocation`: set `true` to require explicit user invocation

**Do not include Claude Code-only fields**: `maxTurns`, `isolation`, `memory`, `permissionMode`, `effort`, `hooks`, `mcpServers`.

The system prompt body should match the Claude Code version — the agent's task definition is the same across providers.

### Step 4 — Populate or delete `agents/sources.md` (plugin scope only)

Skip this step at project and user scope.

If a research `sources.md` is present in the conversation context:
1. Filter to entries with `` `extracted` `` status only.
2. For each entry, note which agent files it contributed to.
3. Write `agents/sources.md` with those entries. Include `- **Research doc:** <path>` per entry pointing to the upstream research sources file.

If no research sources are in context, delete `agents/sources.md`.

### Step 5 — Validate and close

**Claude Code file (`<name>.md`):**
- [ ] `name` field present, kebab-case, unique in scope
- [ ] `description` field present, action-first
- [ ] If plugin scope: no `hooks`, `mcpServers`, or `permissionMode` (silently ignored at plugin scope — move agent to `.claude/agents/` to use them)
- [ ] System prompt body present and non-empty

**Copilot file (`<name>.agent.md`):**
- [ ] File extension is `.agent.md` (not `.md`)
- [ ] `description` field present
- [ ] No Claude Code-only fields (`maxTurns`, `isolation`, `memory`, `permissionMode`, `effort`)
- [ ] System prompt body present and non-empty

If the destination is inside a plugin directory, apply a **minor bump** to the `version` field in both `plugin.json` and `.claude-plugin/plugin.json` at the plugin root in the same edit pass (e.g. `1.0.4` → `1.1.0`).

Run `/agent-audit` on the created files to confirm the pair is valid before closing.

## Improving an existing agent

### Step 1 — Verify inputs

Confirm the agent files exist and at least one improvement signal is present in the conversation or a referenced file.

If no signals: "This skill applies existing signals to an agent. For a blind review, examine the files manually or run a grill session first."

**Partial state** — if one provider file exists but the other does not, scaffold the missing file first (run `bash scripts/new-agent.sh <name> <root>` — the file-by-file no-op means only the missing file is created), then continue with the improve flow on both files.

### Step 2 — Gather and group signals

Read the current agent file(s). Collect all signals from the conversation.

Group by **root cause**, not symptom. One root cause → one fix.

```text
Example:
- User feedback: agent keeps trying to push to remote
- Session context: no scope boundary in system prompt
→ Root cause: system prompt lacks git scope constraint → fix: add explicit boundary
```

### Step 3 — Announce planned changes

Before editing, state which root causes were identified, what evidence supports each, and which files will change. Then proceed — edits are reversible via git.

### Step 4 — Apply changes

Edit any file the signals point to. Generalize the fix — find the underlying gap, not the specific example that failed. For Copilot files, verify no Claude Code-only fields are introduced.

### Step 5 — Validate and close

Re-run the validation checklist from the create flow's Step 5 on any edited file.

If the agent lives inside a plugin directory, apply a **patch bump** to the `version` field in both `plugin.json` and `.claude-plugin/plugin.json` at the plugin root in the same edit pass (e.g. `1.0.4` → `1.0.5`).

Run `/agent-audit` on the edited files to confirm no regressions before closing.