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/frontmatter-reference.md
View on GitHub# Frontmatter Reference
Source: [CLI command reference §Custom agents reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agents-reference) and [§Tool availability values](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#tool-availability-values), cross-checked against `github/copilot-cli`'s own `changelog.md` (verified current as of CLI v1.0.79).
## Core fields
| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `description` | string | — (required) | Shown in the agent list and to the `task` tool; the CLI routes auto-delegation on this text alone — be specific about scope/triggers, not vague ("Backend developer" won't trigger). |
| `target` | string | — (always set to `github-copilot`) | VS Code-only field, ignored by the standalone CLI. Always include it anyway: if this `.github/agents/*.agent.md` file is ever opened in VS Code, `target: github-copilot` makes VS Code honor its `mcp-servers` key instead of defaulting to a native `vscode`-target agent (source: [VS Code custom agent file structure](https://code.visualstudio.com/docs/agent-customization/custom-agents#_custom-agent-file-structure)). |
| `name` | string | filename | Display label shown in the `/agent` picker and agent list — doesn't need to match the filename (which is still the agent's ID for `task(agent_type=...)`/`@mention`). Keep it short but meaningful; spaces are allowed (e.g. `name: Security Review`). |
| `model` | string | inherits parent | Single model string. When authoring agents, use the canonical lowercase CLI ID shown by GitHub's supported-models table or the CLI model picker (for example, `claude-sonnet-4.6`, `gpt-5.4`, or `gpt-5.3-codex`). Never emit a bare display label such as `GPT-5.4`. If compatibility requires display-name syntax, copy the complete picker value exactly, including any provider suffix (for example, `"GPT-5.4 (copilot)"`); canonical IDs remain preferred. When the session model is `Auto`, subagents always use the resolved session model regardless of this field. |
| `tools` | string[] | `["*"]` (all) | See [Tools](#tools) below. |
| `mcp-servers` | object | — | Same schema as `~/.copilot/mcp-config.json`; merges with configured servers. |
| `disable-model-invocation` | boolean | `false` | Prevents the main agent (and `task`) from auto-invoking this agent. Since CLI has no `agents:` allowlist, this removes the agent from model dispatch **entirely** — there's no "only orchestrator X" exception. |
| `user-invocable` | boolean | `true` | `false` hides the agent from the `/agent` picker; it stays reachable via `task(agent_type=...)`. Use this (not `disable-model-invocation`) to hide internal specialists while keeping them dispatchable. |
| `infer` | boolean | `true` | Legacy alias for `!disable-model-invocation`, kept for backward compatibility since 0.0.411. Prefer `disable-model-invocation` in new agents. |
## Additional fields (changelog-confirmed, thin/absent in the official table)
| Field | Type | Notes |
| --- | --- | --- |
| `deferred-tool-loading` | boolean | Opt-in tool-search discovery instead of loading the full tool list up front — for agents with a large `tools:` list. |
| `skills` | string[] | Eagerly load named skill content into the agent's context at startup (vs. the default on-demand skill loading). |
| `reasoning-effort` | string | `low`/`medium`/`high`/`xhigh`/`max` (model-dependent); sets the agent's reasoning effort independent of the session's `--reasoning-effort`. |
| `sidekick` | object | Turns the file into a background sidekick agent (see below) instead of a normal task-dispatchable agent. |
## Sidekick agents
A `sidekick:` block makes the agent run automatically in response to session events rather than being explicitly invoked.
```yaml
sidekick:
triggers:
- session.context_changed
- event: user.message
limit: 1
behavior: persistent # "restart" (default) | "persistent"
maxSendsPerTurn: 2
```
| Sub-field | Values |
| --- | --- |
| `triggers` | `user.message` (every message) or `session.context_changed` (cwd/repo/branch change); entries can be a bare event string (unlimited fires) or `{event, limit}` |
| `behavior` | `restart` (cancel + relaunch fresh each trigger, for stateless gatherers) or `persistent` (one long-lived loop, state accumulates) |
| `maxSendsPerTurn` | Max inbox sends per trigger (default `1`); resets each delivered message in `persistent` mode |
> The CLI also has no `agents:` allowlist, `handoffs:`, or model fallback-chain array — don't add them, they're silently ignored (unknown fields warn, not error). Enforce a specialist hierarchy by convention instead (naming prefix + `user-invocable: false`). For per-agent model resilience use `~/.copilot/settings.json` → `subagents.agents.<name>.model` rather than an inline fallback list.
## Tools
`tools:` accepts a YAML array or comma-separated string of the CLI's built-in **tool availability values** (the same identifiers used by `--available-tools`/`--excluded-tools`) plus `mcp-server-name/tool-name`. Omit `tools:` for all tools; `[]` disables all tools.
### Shell tools
| Tool | Purpose |
| --- | --- |
| `bash` / `powershell` | Execute commands |
| `list_bash`/`list_powershell` | List active shell sessions |
| `read_bash`/`read_powershell` | Read output from a shell session |
| `stop_bash`/`stop_powershell` | Terminate a shell session |
| `write_bash`/`write_powershell` | Send input to a shell session |
### File operation tools
| Tool | Purpose |
| --- | --- |
| `apply_patch` | Apply patches (used by some models instead of `edit`/`create`) |
| `create` | Create new files |
| `edit` | Edit files via string replacement |
| `view` | Read files or directories |
### Agent/task delegation & other tools
| Tool | Purpose |
| --- | --- |
| `list_agents` | List visible agents (self/sibling/child) |
| `read_agent` | Check a background agent's status |
| `task` | Dispatch a subagent (built-in or custom) |
| `write_agent` | Send a message to a running agent |
| `ask_user` | Ask the user a question |
| `glob` | Find files matching patterns |
| `grep` (or `rg`) | Search for text in files |
| `skill` | Invoke a custom skill |
| `web_fetch` | Fetch/parse a URL |
Unrecognized tool names are ignored rather than erroring. MCP server tools: reference `some-mcp-server/some-tool`, or `some-mcp-server/*` for all of a server's tools.
> **Don't confuse this list with `--allow-tool`/`--deny-tool` permission patterns.** Those use a different, coarser `Kind(argument)` syntax — `memory`, `read`, `shell(git:*)`, `url(github.com)`, `write(src/*.ts)`, `SERVER-NAME` — for session-level allow/deny rules, not for the agent frontmatter `tools:` list. Writing `tools: ['shell(git:*)']` in an agent file is invalid; use `tools: ['bash']` instead.
## Locations & priority
```mermaid
flowchart TD
P["Project: .github/agents/ or .claude/agents/<br/>deepest ancestor directory wins"] -->|overrides| Us["User: ~/.copilot/agents/"]
Us -->|overrides| Pl["Plugin: <plugin>/agents/"]
```
| Scope | Location |
| --- | --- |
| Project | `.github/agents/` or `.claude/agents/`, walked upward from cwd to the Git root; `.github/agents/` beats `.claude/agents/` at the same level |
| User | `~/.copilot/agents/` |
| Plugin | `<plugin>/agents/` |
Name collisions resolve by this priority order (not "first found wins" like skills). Malformed frontmatter shows a real parse error (not a silent skip) as of later CLI versions; unknown fields warn instead of blocking the agent from loading.
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: 470k | 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: 470k | 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: 470k | 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 |