# GitHub Copilot CLI Plugin Reference

Verified against docs.github.com as of June 2026.

---

## Directory structure

```text
plugin-root/
├── plugin.json           # at plugin root (NOT in .claude-plugin/)
├── skills/               # skill directories: <name>/SKILL.md (same as Claude Code)
├── agents/               # agent files: <name>.agent.md (differs from Claude Code)
├── hooks.json            # at plugin root (differs from Claude Code: hooks/hooks.json)
└── .mcp.json             # at plugin root (same as Claude Code)
```

---

## plugin.json schema (Copilot)

```json
{
  "name": "my-plugin",
  "description": "What it does",
  "version": "1.0.0",
  "author": { "name": "Name", "email": "you@example.com" },
  "license": "MIT",
  "keywords": [],
  "agents": "agents/",
  "skills": ["skills/"],
  "hooks": "hooks.json",
  "mcpServers": ".mcp.json"
}
```

Key difference from Claude Code: Copilot expects component path declarations inside
`plugin.json` (`"skills": "skills/"`, `"agents": "agents/"`, etc.). Claude Code instead
defaults to standard dirs and takes path overrides only via the marketplace entry.
This means the same `plugin.json` may need these fields for Copilot but not for Claude.

---

## marketplace.json schema (Copilot)

```json
{
  "name": "my-ai-marketplace",
  "owner": { "name": "Your Name", "email": "you@example.com" },
  "metadata": { "description": "Agents, skills and workflows", "version": "1.0.0" },
  "plugins": [
    {
      "name": "startup-cto",
      "source": "./plugins/startup-cto",
      "description": "...",
      "version": "1.0.0"
    }
  ]
}
```

Copilot's primary marketplace manifest path is `.github/plugin/marketplace.json`.
It also reads `.claude-plugin/marketplace.json` as a fallback.
Relative `source` paths: `./x` and `x` are both valid (Claude requires `./`).

---

## Agent file format

Copilot agents use `.agent.md` extension with frontmatter:

```markdown
---
name: my-agent
description: What this agent does
tools:
  - read_file
  - run_command
---

Agent instructions here.
```

Claude Code agents use `.md` extension without the `.agent.md` suffix.
If shipping agents for both tools, create both files:
- `agents/my-agent.md` — Claude Code
- `agents/my-agent.agent.md` — Copilot CLI

---

## CLI commands

```bash
# Install plugin locally (development)
copilot plugin install ./my-plugin

# List installed plugins
copilot plugin list

# In interactive mode
/plugin list
/skills list
/agent

# Reload after changes
/reload-plugins

# Uninstall (uses bare plugin name, not @marketplace form)
copilot plugin uninstall <name>

# Marketplace
copilot plugin marketplace add owner/repo
```

> ⚠️ **UNVERIFIED: Copilot marketplace install command.**
> The `update`/`uninstall` commands take a bare `<name>`. Whether install from a marketplace
> uses `<name>@<marketplace>` (Claude Code's form) or a bare `<name>` is not confirmed in docs.
> Run `copilot plugin install --help` before documenting the install command anywhere.

---

## Validation

Copilot has no documented `plugin validate` command. For Copilot-side validation, run manual checks:
- Valid JSON in `plugin.json` and `marketplace.json`
- Required fields: `name`, `description`
- Unique plugin names across marketplace
- Kebab-case plugin names
- All `source` paths resolve to existing directories
- `.agent.md` files have valid YAML frontmatter with `name`, `description`, `tools`

---

## Key differences from Claude Code (summary)

| What | Claude Code | Copilot CLI |
|---|---|---|
| Plugin manifest location | `.claude-plugin/plugin.json` | `plugin.json` at plugin root |
| Agent files | `agents/<name>.md` | `agents/<name>.agent.md` |
| Hooks file | `hooks/hooks.json` | `hooks.json` at plugin root |
| Component paths | Declared in marketplace entry | Declared in `plugin.json` |
| Validate command | `claude plugin validate` | None — manual checks only |
| Relative source `./` | Required | Optional (`x` also valid) |