NetFabric/intelligentium / .agents/skills/copilot-cli-custom-agents
copilot-cli-custom-agents
VerifiedCreate and maintain GitHub Copilot CLI custom agents (.agent.md files). USE FOR: authoring .github/agents or ~/.copilot/agents profiles; frontmatter fields (description, target, name, model, tools, mcp-servers, disable-model-invocation, user-invocable, deferred-tool-loading, skills, reasoning-effort, sidekick); writing descriptions that drive auto-delegation (the CLI routes on description quality, like skills); building orchestrator + specialist squads with the task tool; /fleet parallel subagents; built-in agents (explore, task, research, code-review, rubber-duck, security-review, general-purpose); subagent depth/concurrency limits; list_agents and write_agent coordination. DO NOT USE FOR: VS Code-only fields beyond target (agents: allowlist, handoffs) or GitHub.com cloud agent configuration; MCP server authoring; SKILL.md authoring (use create-skill).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.8 KB |
| references/authoring-workflow.md | markdown | 4.9 KB |
| references/delegation-and-squads.md | markdown | 7.2 KB |
| references/frontmatter-reference.md | markdown | 7.5 KB |
| references/undocumented-and-gotchas.md | markdown | 4.6 KB |
references/authoring-workflow.md
View on GitHub# Authoring Workflow
```mermaid
flowchart LR
C[Create/edit .agent.md] --> Re[Restart CLI / new session]
Re --> I{Invoke}
I -->|description match| Auto[Auto-delegation]
I -->|/agent, @mention, --agent| Explicit[Explicit selection]
I -->|task tool| Dispatch[Dispatched by another agent]
Auto & Explicit & Dispatch --> T[Troubleshoot if wrong/missing]
```
## Create an agent
| Method | How |
| --- | --- |
| Interactive wizard | `/agent` → create → choose Project (`.github/agents/`) or User (`~/.copilot/agents/`) scope → fill description/tools in a guided form |
| Manual file | Create `.github/agents/<name>.agent.md` (or `.md`) directly with frontmatter + prompt body |
| Via `configure-copilot` | Ask the built-in `configure-copilot` agent to scaffold a new agent for you |
| Via a plugin | Ship agents under `<plugin>/agents/` so `apm`/plugin installs distribute them automatically (lowest load priority — a project or user agent with the same filename overrides it) |
Naming: lowercase, hyphenated; filename → agent ID (`react-reviewer.agent.md` → `react-reviewer`). Nested subdirectories under `.github/agents/`/`.claude/agents/` are discovered recursively, even when the session starts from a subdirectory of the repo root.
## Write the description and prompt body
The CLI routes on `description` alone. Name concrete tasks, likely user phrases, commands, and domain terms in 1–3 sentences. State exclusions when sibling agents overlap, and declare consequential limits such as read-only behavior. A title such as "Backend developer" is not a routing description.
Keep one role per agent. Start the body with a one-sentence role, then add only the protocol, constraints, stop conditions, and output format the role needs. Let frontmatter declare tools and model instead of restating them. Orchestrators must name their specialists; sidekicks must name the event that should trigger them.
A dispatched agent starts with fresh context. Put task-specific goals, paths, facts, and constraints in each `task` prompt rather than assuming shared conversation context or hardcoding one task into the reusable body.
## Load & reload
| Trigger | Effect |
| --- | --- |
| Restart CLI / new session | Only way to pick up new or edited agent files mid-work |
| `/clear`, `/new` | Also reset which agent is currently selected |
| `/cd` | Re-discovers agents in the new directory; persists that directory across a resumed session |
## Invoke & verify
1. `/agent` — browse and select an agent by display name; if the filename differs from the display name, the source label still shows which file it came from.
2. `@agent-name your prompt` — explicit inline invocation.
3. `copilot --agent <name> --prompt "..."` — non-interactive/scripted invocation.
4. Just ask naturally and let auto-delegation match your `description` — this is the only way to verify the description is actually trigger-worthy; if the CLI doesn't pick it, tighten the wording (see [frontmatter-reference.md](frontmatter-reference.md)).
5. `/subagents` (alias `/agents`) — configure per-agent model/reasoning-effort/context-tier, and see which agents are registered.
## Troubleshooting
| Symptom | Cause / fix |
| --- | --- |
| Agent never auto-invoked | `description` too generic, or `disable-model-invocation: true`/`infer: false` set. Since v1.0.42 the CLI is also more conservative about delegating at all — see [delegation-and-squads.md](delegation-and-squads.md). |
| Agent missing from `/agent` picker | `user-invocable: false` — by design, still reachable via `task`. |
| Edits keep going through the wrong agent's constraints | Confirm file location priority: project `.github/agents/` (deepest ancestor) > `.claude/agents/` > user `~/.copilot/agents/` > plugin. A same-named agent higher in this order silently wins. |
| "Malformed custom agent" warning | Parse error is now surfaced (not silently skipped); check YAML frontmatter syntax — unknown *fields* only warn, but invalid YAML structure blocks loading. |
| Agent stuck on the wrong model after a session resume | Confirmed fixed for BYOK/BYOM providers in later versions — update the CLI if you still see this with a pinned `model:`. |
| Plugin-provided agent not appearing | Confirm the plugin is installed/enabled (`/plugin list`) and that no project/user agent with the same filename is shadowing it. |
## Testing before you rely on delegation
- Restart the CLI after any edit.
- Ask a question that should trigger auto-delegation and confirm the right agent name appears in the timeline/statusline (agent name is visible in the footer and toggleable via `/statusline`).
- Ask a question that should *not* trigger it, to catch an over-broad description.
- For orchestrators, confirm they dispatch implementation via `task` rather than doing the work inline. Always strip `edit`; strip `shell`/`bash` unless the prompt defines a narrow orchestrator-owned dependency readiness preflight, in which case verify shell use is explicitly forbidden after that preflight.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |