feat(kyberforge): implement agent-author skill #10

New Issue

Claude · 2026-06-27T14:42:47Z

Claude commented

2026-06-27 14:42:47 +00:00

Plugin: plugins/kyberforge/
Grill session: 2026-06-27

What to build

A new skill agent-author in the kyberforge plugin — the agent-definition equivalent of skill-author. Creates and improves agent definition files for Claude Code and GitHub Copilot CLI, at plugin, project, or user scope.

Design decisions

Decision	Outcome
Providers	Both Claude Code (`.md`) and Copilot CLI (`.agent.md`)
Output	Two separate files per authoring session
Scope	Plugin, project, user — auto-detected from root
Scaffold	`new-agent.sh <name> <root>` — derives both paths by convention
Partial state	File-by-file no-op; any file exists → improve flow
Companion structure	Bare files only; `agents/sources.md` at plugin scope only
Validation gate	No `agent-audit` (follow-on); inline validation in close step
Location	`plugins/kyberforge/skills/agent-author/`

Path derivation convention (new-agent.sh <name> <root>):

Plugin scope (plugin.json in root): <root>/agents/<name>.md + <root>/agents/<name>.agent.md
Project scope (no plugin.json): <root>/.claude/agents/<name>.md + <root>/.github/agents/<name>.agent.md
User scope (~): ~/.claude/agents/<name>.md + ~/.copilot/agents/<name>.agent.md

See ADR-0015 (docs/adr/0015-agent-author-dual-provider-scaffold.md) for the rationale behind always generating both provider files from a single root input.

Files to produce

plugins/kyberforge/skills/agent-author/
├── SKILL.md
├── scripts/
│   └── new-agent.sh               ← scaffold script
├── assets/
│   └── templates/
│       ├── claude-code.md         ← annotated Claude Code agent template
│       └── copilot.agent.md       ← annotated Copilot CLI agent template
├── references/
│   ├── deployment-modes.md        ← plugin vs project vs user scope gotchas
│   └── sources.md                 ← provenance chain
└── tests/
    └── new-agent.bats             ← bats tests for new-agent.sh
docs/adr/0015-agent-author-dual-provider-scaffold.md

Key gotchas (must appear in `deployment-modes.md` and SKILL.md)

Claude Code plugin agents silently ignore hooks, mcpServers, permissionMode — these only take effect in .claude/agents/ or ~/.claude/agents/
Copilot CLI requires .agent.md extension (not .md) for CLI agents
AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup are never available to any Claude Code subagent regardless of the tools field
Plugin agent scoped identifiers: Claude Code scopes names when in subdirectories (plugin:dir:name) — keep agents flat in agents/
Duplicate agent names: Claude Code silently discards one without warning

Acceptance criteria

plugins/kyberforge/skills/agent-author/SKILL.md exists; metadata.category: factory; passes /skill-audit
Description triggers on: "create an agent for X", "write a subagent that does Y", "add a Claude Code agent to this plugin", "improve this agent" — and does NOT trigger on skill-authoring requests
scripts/new-agent.sh passes all bats tests
WHEN given a root with plugin.json, script creates agents/<name>.md AND agents/<name>.agent.md
WHEN given a project root (no plugin.json), script creates .claude/agents/<name>.md AND .github/agents/<name>.agent.md
WHEN given ~, script creates ~/.claude/agents/<name>.md AND ~/.copilot/agents/<name>.agent.md
WHEN target files already exist, script exits 0 without overwriting (per-file no-op)
assets/templates/claude-code.md is a valid annotated Claude Code agent template with FILL IN: placeholders
assets/templates/copilot.agent.md is a valid annotated Copilot CLI agent template with FILL IN: placeholders
references/deployment-modes.md covers plugin/project/user scope restrictions for both providers
references/sources.md populated from claude-code-plugins and github-copilot-plugins research sources
tests/new-agent.bats covers plugin scope, project scope, user scope, no-op behavior, invalid name
docs/adr/0015-agent-author-dual-provider-scaffold.md committed
HOTL: invoke /agent-author in a fresh session; verify create flow produces both files at plugin scope

Blocked by

None — research docs already present at plugins/kyberforge/docs/research/docs/claude-code-plugins/ and plugins/kyberforge/docs/research/docs/github-copilot-plugins/.

**Plugin:** `plugins/kyberforge/` **Grill session:** 2026-06-27 ## What to build A new skill `agent-author` in the kyberforge plugin — the agent-definition equivalent of `skill-author`. Creates and improves agent definition files for Claude Code and GitHub Copilot CLI, at plugin, project, or user scope. ## Design decisions | Decision | Outcome | |---|---| | Providers | Both Claude Code (`.md`) and Copilot CLI (`.agent.md`) | | Output | Two separate files per authoring session | | Scope | Plugin, project, user — auto-detected from root | | Scaffold | `new-agent.sh <name> <root>` — derives both paths by convention | | Partial state | File-by-file no-op; any file exists → improve flow | | Companion structure | Bare files only; `agents/sources.md` at plugin scope only | | Validation gate | No `agent-audit` (follow-on); inline validation in close step | | Location | `plugins/kyberforge/skills/agent-author/` | **Path derivation convention (`new-agent.sh <name> <root>`):** - Plugin scope (`plugin.json` in root): `<root>/agents/<name>.md` + `<root>/agents/<name>.agent.md` - Project scope (no `plugin.json`): `<root>/.claude/agents/<name>.md` + `<root>/.github/agents/<name>.agent.md` - User scope (`~`): `~/.claude/agents/<name>.md` + `~/.copilot/agents/<name>.agent.md` See ADR-0015 (`docs/adr/0015-agent-author-dual-provider-scaffold.md`) for the rationale behind always generating both provider files from a single root input. ## Files to produce ``` plugins/kyberforge/skills/agent-author/ ├── SKILL.md ├── scripts/ │ └── new-agent.sh ← scaffold script ├── assets/ │ └── templates/ │ ├── claude-code.md ← annotated Claude Code agent template │ └── copilot.agent.md ← annotated Copilot CLI agent template ├── references/ │ ├── deployment-modes.md ← plugin vs project vs user scope gotchas │ └── sources.md ← provenance chain └── tests/ └── new-agent.bats ← bats tests for new-agent.sh docs/adr/0015-agent-author-dual-provider-scaffold.md ``` ## Key gotchas (must appear in `deployment-modes.md` and SKILL.md) - **Claude Code plugin agents** silently ignore `hooks`, `mcpServers`, `permissionMode` — these only take effect in `.claude/agents/` or `~/.claude/agents/` - **Copilot CLI** requires `.agent.md` extension (not `.md`) for CLI agents - **`AskUserQuestion`, `EnterPlanMode`, `ExitPlanMode`, `ScheduleWakeup`** are never available to any Claude Code subagent regardless of the `tools` field - **Plugin agent scoped identifiers**: Claude Code scopes names when in subdirectories (`plugin:dir:name`) — keep agents flat in `agents/` - **Duplicate agent names**: Claude Code silently discards one without warning ## Acceptance criteria - [x] `plugins/kyberforge/skills/agent-author/SKILL.md` exists; `metadata.category: factory`; passes `/skill-audit` - [x] Description triggers on: "create an agent for X", "write a subagent that does Y", "add a Claude Code agent to this plugin", "improve this agent" — and does NOT trigger on skill-authoring requests - [x] `scripts/new-agent.sh` passes all bats tests - [x] WHEN given a root with `plugin.json`, script creates `agents/<name>.md` AND `agents/<name>.agent.md` - [x] WHEN given a project root (no `plugin.json`), script creates `.claude/agents/<name>.md` AND `.github/agents/<name>.agent.md` - [x] WHEN given `~`, script creates `~/.claude/agents/<name>.md` AND `~/.copilot/agents/<name>.agent.md` - [x] WHEN target files already exist, script exits 0 without overwriting (per-file no-op) - [x] `assets/templates/claude-code.md` is a valid annotated Claude Code agent template with `FILL IN:` placeholders - [x] `assets/templates/copilot.agent.md` is a valid annotated Copilot CLI agent template with `FILL IN:` placeholders - [x] `references/deployment-modes.md` covers plugin/project/user scope restrictions for both providers - [x] `references/sources.md` populated from claude-code-plugins and github-copilot-plugins research sources - [x] `tests/new-agent.bats` covers plugin scope, project scope, user scope, no-op behavior, invalid name - [x] `docs/adr/0015-agent-author-dual-provider-scaffold.md` committed - [x] **HOTL:** invoke `/agent-author` in a fresh session; verify create flow produces both files at plugin scope ## Blocked by None — research docs already present at `plugins/kyberforge/docs/research/docs/claude-code-plugins/` and `plugins/kyberforge/docs/research/docs/github-copilot-plugins/`.

Claude added the Kind/Feature

Priority

Medium

3

labels 2026-06-27 14:53:59 +00:00

Claude referenced this issue

2026-06-27 14:57:09 +00:00

kyberforge: agent-audit skill (agent-author follow-ons) #11

Defame1297 added the

Reviewed

Confirmed

1