aalmada/Stationary / .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).
Copilot CLI Custom Agents
A custom agent is a Markdown file (.agent.md or .md) with YAML frontmatter plus a system-prompt body. The filename (minus extension) is the agent's ID. The CLI auto-delegates to it based on the description field — exactly like the skill/skill-invocation mechanism — so a vague description never gets invoked.
Anatomy
| Part | Purpose |
|---|---|
| Frontmatter | description (required) + target: github-copilot (always set) + optional name, model, tools, mcp-servers, disable-model-invocation, user-invocable, deferred-tool-loading, skills, reasoning-effort, sidekick |
| Body | System prompt: role, protocol, constraints. Max 30,000 characters |
| Location | .github/agents/ or .claude/agents/ (project, walked to Git root, deepest wins) > ~/.copilot/agents/ (user) > <plugin>/agents/ (plugin, lowest priority) |
Minimal example
---
description: Reviews code for OWASP Top 10 security issues. Use for security audits, "seccheck", or vulnerability review requests.
target: github-copilot
tools: ['read', 'search']
---
You are a security reviewer. Identify vulnerabilities following the OWASP Top 10
taxonomy. Report findings in a table with severity, location, and remediation.
Do NOT modify files.
Invocation
| Method | Syntax |
|---|---|
| Auto-delegation | Main agent matches your prompt against every agent's description |
| Inline mention | @agent-name your prompt |
| Slash command | /agent (browse/select), then enter a prompt |
| CLI flag | copilot --agent agent-name --prompt "..." |
| From another agent | task(agent_type="agent-name", prompt="...") — the CLI's subagent-dispatch tool |
task takes exactly two parameters: agent_type (the target agent's ID) and prompt (the task to run). The subagent starts with a fresh, empty context — prompt is the only channel of information it receives, so the calling agent must write every fact the subagent needs (goal, constraints, file paths) directly into that string rather than assuming shared context. Details and examples → references/delegation-and-squads.md.
Built-in agents
explore, task, general-purpose, code-review, research (only via /research), rubber-duck, security-review — plus the undocumented configure-copilot agent for managing MCP servers/agents/skills. Full table → references/delegation-and-squads.md.
Workflow
- Scope one focused role per agent — read references/frontmatter-reference.md for every field
- Run
agent-markdown-best-practicesto write a specific, keyword-densedescriptionand a constraint-driven prompt body — vague descriptions never get auto-invoked - Restrict
tools:to the minimum the role needs; stripeditfrom orchestrators and normally stripshellso they delegate. Retain narrowly scoped shell access only for an explicit orchestrator-owned dependency readiness preflight (for example, CBM installation/index verification), and forbid all other shell work in the prompt body - Choose
model:(andreasoning-effort:) using themodel-selectionskill before finalizing frontmatter — never leave it unset on the assumption an inherited default is adequate - For multi-agent squads, adopt a naming prefix and use
user-invocable: falseon internal specialists → references/delegation-and-squads.md - Always set
target: github-copilotin the frontmatter — the CLI ignores it, but it's needed if the same file is ever opened in VS Code → references/frontmatter-reference.md - Restart the CLI (or start a new session) to load new/edited agent files
- Check references/authoring-workflow.md if the agent doesn't load or isn't invoked
- Check references/undocumented-and-gotchas.md for fields/behaviors missing from the official reference table
- Run
markdown-best-practicesover the finished.agent.mdfor frontmatter fences, heading/list hygiene, and other Markdown rendering rules
Reference Files
| File | Load When |
|---|---|
| references/frontmatter-reference.md | Writing or reviewing any frontmatter field, tool name/alias, or file location/priority rule |
| references/delegation-and-squads.md | Building an orchestrator, a specialist squad, using task/list_agents/write_agent, or /fleet |
| references/authoring-workflow.md | Creating an agent via the CLI wizard, testing it, or troubleshooting why it won't load/invoke |
| references/undocumented-and-gotchas.md | Hitting a field or behavior the official CLI reference table omits; reconciling CLI vs. VS Code vs. cloud-agent differences |
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: 466k | 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: 466k | 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: 466k | 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: 192k | Updated | Claude CodeCodex | Verified | Install |