refactor(install): prefer native plugin install across targets (#609)

Co-authored-by: John Cavanaugh <cavanaug@users.noreply.github.com>

docs/specs/copilot.md

@@ -1,10 +1,14 @@
 # GitHub Copilot Spec (Agents, Skills, MCP)
 
-Last verified: 2026-02-14
+Last verified: 2026-04-18
 
 ## Primary sources
 
 ```
+https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli
+https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference
+https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference
+https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-cli-plugins
 https://docs.github.com/en/copilot/reference/custom-agents-configuration
 https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
 https://docs.github.com/en/copilot/concepts/agents/coding-agent/mcp-and-coding-agent
@@ -15,19 +19,50 @@ https://docs.github.com/en/copilot/concepts/agents/coding-agent/mcp-and-coding-a
 | Scope | Path |
 |-------|------|
 | Project agents | `.github/agents/*.agent.md` |
+| Project agents (Claude-compatible) | `.claude/agents/*.md` |
+| Personal agents | `~/.copilot/agents/*.agent.md` |
+| Personal agents (Claude-compatible) | `~/.claude/agents/*.md` |
+| Plugin agents | `agents/` by default, overridable in plugin manifest |
 | Project skills | `.github/skills/*/SKILL.md` |
+| Project skills (auto-discovery) | `.agents/skills/*/SKILL.md` |
 | Project instructions | `.github/copilot-instructions.md` |
 | Path-specific instructions | `.github/instructions/*.instructions.md` |
 | Project prompts | `.github/prompts/*.prompt.md` |
 | Org/enterprise agents | `.github-private/agents/*.agent.md` |
 | Personal skills | `~/.copilot/skills/*/SKILL.md` |
+| Personal skills (auto-discovery) | `~/.agents/skills/*/SKILL.md` |
 | Directory instructions | `AGENTS.md` (nearest ancestor wins) |
 
 ## Agents (.agent.md files)
 
 - Custom agents are Markdown files with YAML frontmatter stored in `.github/agents/`.
 - File extension is `.agent.md` (or `.md`). Filenames may only contain: `.`, `-`, `_`, `a-z`, `A-Z`, `0-9`.
+- The documented custom-agent extension is singular `.agent.md`, not `.agents.md`.
 - `description` is the only required frontmatter field.
+- Current Copilot CLI docs do not list `.agents/agents` or `~/.agents/agents` as custom-agent discovery paths. The `.agents/*` convention is documented for skills (`.agents/skills`, `~/.agents/skills`), not agents.
+- Copilot CLI also loads Claude-compatible agent directories (`.claude/agents`, `~/.claude/agents`) after native Copilot agent directories and before plugin agents.
+- `AGENTS.md` files are supported as custom instruction/context files, not as custom-agent profile files.
+
+## Plugins
+
+- Copilot CLI plugins bundle reusable agents, skills, hooks, MCP servers, and related configuration.
+- Install from a registered marketplace with:
+
+```text
+/plugin marketplace add EveryInc/compound-engineering-plugin
+/plugin install compound-engineering@compound-engineering-plugin
+```
+
+- The terminal equivalents are:
+
+```bash
+copilot plugin marketplace add EveryInc/compound-engineering-plugin
+copilot plugin install compound-engineering@compound-engineering-plugin
+```
+
+- Copilot CLI looks for plugin manifests at `.plugin/plugin.json`, `plugin.json`, `.github/plugin/plugin.json`, or `.claude-plugin/plugin.json`.
+- Copilot CLI looks for marketplace manifests at `marketplace.json`, `.plugin/marketplace.json`, `.github/plugin/marketplace.json`, or `.claude-plugin/marketplace.json`.
+- Therefore the existing repository-level `.claude-plugin/marketplace.json` and plugin-level `plugins/compound-engineering/.claude-plugin/plugin.json` are expected to be sufficient for Copilot native plugin install. Do not add a parallel `.github/plugin` surface unless Copilot requires a Copilot-only manifest field in the future.
 
 ### Frontmatter fields
 
@@ -72,6 +107,7 @@ Agent body content is limited to **30,000 characters**.
 | Project (Claude-compatible) | `.claude/skills/*/SKILL.md` |
 | Project (auto-discovery) | `.agents/skills/*/SKILL.md` |
 | Personal | `~/.copilot/skills/*/SKILL.md` |
+| Personal (auto-discovery) | `~/.agents/skills/*/SKILL.md` |
 
 ## MCP (Model Context Protocol)
 
@@ -115,8 +151,20 @@ Agent body content is limited to **30,000 characters**.
 
 ## Precedence
 
-1. Repository-level agents
-2. Organization-level agents (`.github-private`)
-3. Enterprise-level agents (`.github-private`)
+1. Built-in agents
+2. `~/.copilot/agents`
+3. `<project>/.github/agents`
+4. `<parents>/.github/agents`
+5. `~/.claude/agents`
+6. `<project>/.claude/agents`
+7. `<parents>/.claude/agents`
+8. Plugin `agents/` directories
+9. Remote organization/enterprise agents
 
 Within a repo, `AGENTS.md` files in directories provide nearest-ancestor-wins instructions.
+
+Skills use separate first-found-wins precedence. Current docs list project `.github/skills`, `.agents/skills`, `.claude/skills`, inherited project skills, personal `~/.copilot/skills`, personal `~/.agents/skills`, personal `~/.claude/skills`, then plugin skill directories.
+
+Skills are deduplicated by the `name` field inside `SKILL.md`, not by directory name. If a personal or project skill has the same `name` as a plugin skill, Copilot uses the first-loaded personal/project skill and silently ignores the plugin skill. For example, a stale `~/.agents/skills/ce-plan/SKILL.md` with `name: ce-plan` would shadow the native plugin's `ce-plan`; it should not show as two separate skills in Copilot CLI. Use `/skills info ce-plan` to confirm which location won.
+
+This makes Copilot cleanup different from Codex duplicate cleanup: stale CE skills in `~/.agents/skills`, `~/.copilot/skills`, `.agents/skills`, or `.github/skills` may not create visible duplicates, but they can silently override newer plugin-provided CE skills.