feat(kyberforge): add agent-author skill for Claude Code and Copilot CLI agents
## Why
skill-author explicitly excludes agent definition files ("Do not use to author
agent definition files"). No factory skill existed to create or improve the
.md / .agent.md files that define Claude Code subagents and Copilot CLI agents
in a plugin, project, or user scope. This fills that gap.
## Implementation Notes
Single-root scaffold convention: new-agent.sh <name> <root> derives both
provider file paths from the root by convention — plugin scope (plugin.json
present) writes both files into <root>/agents/; non-plugin scope writes
.claude/agents/<name>.md and .github/agents/<name>.agent.md. This keeps
input minimal while always generating both provider files. See ADR-0015.
Routing is file-level (not directory-level like skill-author): neither file
exists → create flow; at least one exists → improve flow; scaffold is a
file-by-file no-op so retries are safe.
No companion agent-audit skill — inline validation in the close step covers
the simpler agent field contract. agent-audit is tracked as a follow-on.
## Impact
Closes the skill-author gap for agent definitions. Follow-ons tracked in
Gitea #11: agent-audit skill and --copilot-dest override flag for non-standard
Copilot project paths.
---
ADR: docs/adr/0015-agent-author-dual-provider-scaffold.md
Refs: #10
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
181
plugins/kyberforge/skills/agent-author/SKILL.md
Normal file
181
plugins/kyberforge/skills/agent-author/SKILL.md
Normal file
@@ -0,0 +1,181 @@
|
||||
---
|
||||
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
|
||||
|
||||
- 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
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user