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>
2.9 KiB
source_keys
| source_keys | |||||
|---|---|---|---|---|---|
|
Agent Deployment Modes
Agent definitions deploy at three scopes and behave differently at each. The scope determines which fields are honoured, where files must live, and what identifiers users invoke.
Scope hierarchy and precedence
| Scope | Claude Code path | Copilot CLI path | Who it affects |
|---|---|---|---|
| User | ~/.claude/agents/ |
~/.copilot/agents/ |
All sessions for this user |
| Project | .claude/agents/ |
.github/agents/ or .copilot/agents/ |
This repo only |
| Plugin | <plugin>/agents/ |
<plugin>/agents/ |
Sessions with the plugin installed |
When the same agent name appears at multiple scopes, user scope wins over project scope wins over plugin scope in Claude Code. In Copilot CLI, repo-level agents override enterprise and org-level; home-directory (user) agents override repo-level on name collision.
Plugin scope restrictions
Plugin agents (agents shipped inside a plugin's agents/ directory) have fewer capabilities than project or user agents:
Claude Code — silently ignored for plugin agents:
hooks— per-agent event handlers; copy the agent to.claude/agents/to use thesemcpServers— inline MCP server definitions; not available in plugin contextpermissionMode— silently ignored; the parent session's permission mode applies
Copilot CLI — unsupported or ignored:
mcp-servers— cloud agents only; ignored in VS Code and most IDEsmetadata— key-value annotations; ignored in VS Code
Scoped identifiers (Claude Code plugin agents only)
Plugin agents in subdirectories get compound identifiers:
plugins/my-plugin/agents/review/security.md → my-plugin:review:security
Users must invoke with @agent-my-plugin:review:security. Keep agents flat in agents/ to avoid this — subdirectory nesting is rarely worth the UX cost.
At project and user scope, subdirectory path does not affect the agent's name.
Cache isolation
When a plugin is installed, its directory is copied to a cache. Any path that leaves the agent's plugin directory breaks post-install. Agent definition files must be self-contained — they cannot reference scripts, templates, or shared files outside the plugin.
Agents at project or user scope are read directly from disk; cache isolation does not apply.
Copilot CLI path conventions
| Scope | Expected path | Notes |
|---|---|---|
| User | ~/.copilot/agents/<name>.agent.md |
Home directory |
| Project | .github/agents/<name>.agent.md |
Standard; also .copilot/agents/ |
| Plugin | <plugin>/agents/<name>.agent.md |
Inside plugin root |
The .agent.md extension is mandatory — Copilot CLI does not pick up plain .md files in the agents/ directory.