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

name, description, allowed-tools, metadata

name	description	allowed-tools	metadata
agent-author	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.	Bash Read Write Edit	category source_keys factory 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, ScheduleWakeup, and WaitForMcpServers are never available to any subagent regardless of the tools field. Exception: ExitPlanMode is available when the parent session runs in permissionMode: plan.
• 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.

Route

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

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?
• Capture git log --oneline -1 now, before touching the filesystem — Step 5 needs it to verify a real commit landed

If any are missing, stop and ask before proceeding.

Verify kyberforge:agent-audit is available — it ships with the kyberforge plugin and is co-installed with this skill. If unavailable, stop and tell the user to install the kyberforge plugin before continuing.

Step 1 — Scaffold

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

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

Examples:

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, .claude-plugin/plugin.json, .plugin/plugin.json, or .github/plugin/plugin.json → plugin scope → creates <root>/agents/<name>.md + <root>/agents/<name>.agent.md
• Root is a project directory (no plugin marker) → 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. Remove all template documentation comments from the YAML frontmatter after filling in required fields — these are marked with <!-- and --> and must be deleted before shipping.

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..."
• If this agent should trigger without explicit user direction, include "Use proactively" in the description
• 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
• disallowedTools: space-separated denylist applied before tools; supports mcp__* glob patterns (e.g. disallowedTools: mcp__filesystem__*)
• skills: list of skill names preloaded at agent startup — different from the source_keys metadata field
• color: UI color for the agent tile (red, blue, green, yellow, purple, orange, pink, cyan)
• initialPrompt: auto-submitted as the first turn when this agent activates as the main session thread; only set when this agent is intended for main-thread activation
• background: set true to force background execution

source_keys — top-level list of research source slugs that informed this agent. Add only when research sources were used (i.e. entries with `extracted` status are in context from a prior /research session). Each slug must match an H2 heading in sources.md (plugin root). Omit entirely when no research was used.

source_keys:
  - my-source-slug

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 agent file

There are two distinct Copilot agent formats with different paths and field sets. Choose one based on the deployment target:

CLI format (default — what the scaffold creates):

• Path: .github/agents/<name>.agent.md (project) or <plugin>/agents/<name>.agent.md (plugin)
• Extension: must be .agent.md
• Supported fields: name (required), description (required), tools (optional)
• tools uses Copilot aliases: execute (shell), read, edit, search, agent, web
• Body length limit: 30,000 characters — content beyond this is silently truncated

Cloud/IDE format (use when targeting Copilot Chat in VS Code or GitHub.com):

• Path: .github/copilot/agents/<name>.md (note: plain .md, different directory)
• Additional fields available: target (vscode, github-copilot, or omit for both), user-invocable (set false to hide from manual invocation), disable-model-invocation (set true to require explicit user invocation), mcp-servers (MCP server config — processed by cloud runtime, ignored in VS Code)
• Body length limit: 30,000 characters — silently truncated

Do not include Claude Code-only fields in either format: maxTurns, isolation, memory, permissionMode, effort, hooks, mcpServers.

source_keys — add the same top-level list as the CC file when research sources were used. Omit when no research was used.

Remove all template documentation comments from the YAML frontmatter after filling in required fields — these are marked with <!-- and --> and must be deleted before shipping.

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 sources.md (plugin scope only)

Skip this step at project and user scope. The file lives at the plugin root, not inside agents/ — claude plugin validate --strict auto-discovers every .md under agents/ as an agent requiring frontmatter, and a flat provenance file would fail that check (see ADR-0010).

If a research sources.md is present in the conversation context:

1. Filter to entries with `extracted` status only.
2. For each entry, identify which agent files in the pair it contributed to.
3. Write sources.md at the plugin root using the format below. Paths in Contributing files: are relative to the plugin root.

# Sources

## slug-name

- **URL:** <source URL>
- **Research doc:** <path/to/research/sources.md relative to repo root>
- **Description:** <what this source covers>
- **Contributing files:** agents/<name>.md, agents/<name>.agent.md
- **Status:** `extracted`

Each slug must match an H2 heading, and each slug must also appear in the source_keys list of every file listed under Contributing files:.

If no research sources are in context, delete sources.md.

Step 5 — Validate and close

Run this checklist before invoking the audit:

Claude Code file (<name>.md):

• name field present, kebab-case, unique in scope
• description field present and action-first
• If plugin scope: no hooks, mcpServers, or permissionMode (silently ignored at plugin scope)
• System prompt body present and non-empty
• No FILL IN: placeholders remain
• No <!-- --> template comments remain in frontmatter

Copilot CLI file (<name>.agent.md):

• File extension is .agent.md (not .md)
• name field matches the filename stem (e.g. name: my-agent in my-agent.agent.md)
• description field present
• No Claude Code-only fields (maxTurns, isolation, memory, permissionMode, effort, hooks, mcpServers)
• System prompt body present and non-empty
• Body does not exceed 30,000 characters
• No <!-- --> template comments remain in frontmatter

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).

Invoke the kyberforge:agent-audit skill directly on the created files to confirm the pair is valid before closing.

Commit verification. Capture git log --oneline -1 before Step 1 and keep it. Once the audit is clean, run git add and git commit for the new agent files — do not stop at staging. Then run git log --oneline -1 again and confirm the hash changed from the one you captured at the start. A non-empty git diff --stat is not sufficient proof of completion: staged-but-uncommitted work isn't part of any commit and can be silently lost if the working tree is cleaned up before a commit lands. Only report the agent as done once the hash has actually changed.

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."

Verify kyberforge:agent-audit is available — it ships with the kyberforge plugin and is co-installed with this skill. If unavailable, stop and tell the user to install the kyberforge plugin before continuing.

Capture git log --oneline -1 now, before making any edits — Step 5 needs it to verify a real commit landed.

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.

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 every sentence you add, ask: "Would the agent get this wrong without it?" A shorter, focused definition consistently outperforms an exhaustive one. 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).

Invoke the kyberforge:agent-audit skill directly on the edited files to confirm no regressions before closing.

Commit verification. Capture git log --oneline -1 at the start of Step 1 and keep it. Once the audit is clean, run git add and git commit for the changed files — do not stop at staging. Then run git log --oneline -1 again and confirm the hash changed from the one you captured at the start. A non-empty git diff --stat is not sufficient proof of completion: staged-but-uncommitted work isn't part of any commit and can be silently lost if the working tree is cleaned up before a commit lands. Only report the improvement as done once the hash has actually changed.