GitHub Copilot custom agents
Create a role only when its instructions and capability boundary recur. Tool
restriction reduces capability but does not make model output a security boundary.
Workflow
- Define the role, non-goals, user/model invocation, allowed mutations,
evidence, and exit condition.
- Inspect current tool, model, subagent, and host identifiers.
- Store workspace agents in
.github/agents/<name>.agent.md; default to
workspace scope and target: vscode when host specificity matters.
- Grant least privilege. Planning/audit roles receive read-only tools; editing
or terminal tools require a stated job.
- Set
user-invocable and disable-model-invocation independently. Restrict
agents and include the agent tool only when delegation is required.
- Make handoffs reviewable with
send: false by default. Verify every target.
Rules
- Do not freeze a model name unless verified availability is part of the contract.
- Avoid duplicating repository instructions in the body; link to them.
- Keep agent frontmatter host-compatible. IDE-only
handoffs and
argument-hint can be ignored by other hosts.
- Never grant mutation just because a built-in agent normally has it.
Read agent fields, use role patterns, and run verification.
Completion
The agent is discoverable in the intended host, hidden/invocable as designed,
cannot access excluded tools, every handoff resolves without auto-submission
unless approved, and artifact-based tests prove its positive and negative role boundaries.
1---2name: github-copilot-custom-agents3description: >-4 Use for creating, reviewing, or debugging GitHub Copilot custom agents in Visual Studio Code, including .agent.md roles, tool restrictions, model selection, subagent permissions, and handoffs. Do not use for a single slash command, automatic coding rules, Agent Skills, or merely changing the selected chat model.5argument-hint: "[agent role, authority, tools, handoffs, and host]"6---78# GitHub Copilot custom agents910Create a role only when its instructions and capability boundary recur. Tool11restriction reduces capability but does not make model output a security boundary.1213## Workflow14151. Define the role, non-goals, user/model invocation, allowed mutations,16 evidence, and exit condition.172. Inspect current tool, model, subagent, and host identifiers.183. Store workspace agents in `.github/agents/<name>.agent.md`; default to19 workspace scope and `target: vscode` when host specificity matters.204. Grant least privilege. Planning/audit roles receive read-only tools; editing21 or terminal tools require a stated job.225. Set `user-invocable` and `disable-model-invocation` independently. Restrict23 `agents` and include the agent tool only when delegation is required.246. Make handoffs reviewable with `send: false` by default. Verify every target.2526## Rules2728- Do not freeze a model name unless verified availability is part of the contract.29- Avoid duplicating repository instructions in the body; link to them.30- Keep agent frontmatter host-compatible. IDE-only `handoffs` and31 `argument-hint` can be ignored by other hosts.32- Never grant mutation just because a built-in agent normally has it.3334Read [agent fields](references/artifact-contracts.md), use [role patterns](references/patterns.md), and run [verification](references/verification.md).3536## Completion3738The agent is discoverable in the intended host, hidden/invocable as designed,39cannot access excluded tools, every handoff resolves without auto-submission40unless approved, and artifact-based tests prove its positive and negative role boundaries.
schattenspiegel