Defame1297
ba68b09c87
## 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>
42 lines
2.5 KiB
Markdown
42 lines
2.5 KiB
Markdown
# agent-author generates both provider files from a single root input
|
|
|
|
`agent-author` is the skill that creates Claude Code and GitHub Copilot CLI agent
|
|
definition files. Both providers are always targeted: Claude Code produces a `.md`
|
|
file; Copilot CLI produces a `.agent.md` file. The scaffold script `new-agent.sh`
|
|
accepts a single root directory and derives both destination paths by convention
|
|
rather than requiring the caller to supply two explicit paths. Scope is detected
|
|
from the root: a directory containing `plugin.json` is plugin scope (both files
|
|
land in `<root>/agents/`); a directory with `.git` but no `plugin.json` is project
|
|
scope (`.claude/agents/<name>.md` + `.github/agents/<name>.agent.md`); `~` is user
|
|
scope (`~/.claude/agents/<name>.md` + `~/.copilot/agents/<name>.agent.md`).
|
|
|
|
## Considered options
|
|
|
|
**Two explicit destination paths (rejected)** — `new-agent.sh <name> <claude-dest>
|
|
<copilot-dest>` accepts a separate path per provider. Rejected because it breaks
|
|
the minimal-input principle that guides the entire skill: the caller must now know
|
|
and supply two provider-specific paths, which is exactly the convention knowledge
|
|
the script is meant to encapsulate. Every invocation becomes more error-prone and
|
|
harder to drive from a skill body without user interaction.
|
|
|
|
**Plugin-only dual generation (rejected)** — generate both files only at plugin
|
|
scope; at project/user scope generate a single file with the provider inferred from
|
|
the destination path. Rejected because it is an artificial asymmetry: the reason to
|
|
author for both providers does not disappear outside a plugin context. It would
|
|
force users to run the skill twice per agent at project/user scope or build a
|
|
separate single-provider skill, adding complexity with no benefit.
|
|
|
|
## Consequences
|
|
|
|
- `.github/agents/` is the locked-in Copilot CLI convention at project scope.
|
|
Non-standard paths (e.g. `.copilot/agents/`) are not supported without an
|
|
explicit override flag — deferred to a follow-on issue.
|
|
- The script interface `new-agent.sh <name> <root>` is a stable public contract.
|
|
Changing to a two-destination form is a breaking change to any caller.
|
|
- At plugin scope, both files share a single `agents/sources.md` for provenance.
|
|
At project/user scope, no sources file is generated — ad-hoc authoring outside a
|
|
research-driven workflow has no provenance chain to record.
|
|
- The file-by-file no-op in the script (skip existing files rather than
|
|
overwriting) means partial state — one provider file exists, the other does not —
|
|
is handled by routing in the skill body, not in the script.
|