---
source_keys:
  - context7-websites-code-claude
  - claude-code-plugins-docs
  - claude-code-subagents-docs
  - context7-github-en-copilot
  - github-custom-agents-configuration
  - github-cli-plugin-reference
---

# 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 these
- `mcpServers` — inline MCP server definitions; not available in plugin context
- `permissionMode` — 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 IDEs
- `metadata` — 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.