---
title: "Recenter Installs on Native Packages and Shared Skill Cleanup"
description: "Rework the install strategy around current agent-harness behavior:"
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/2026-04-18-001-refactor-native-install-cleanup-plan
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T10:59:06.905Z
license: CC-BY-4.0
attribution: "Recenter Installs on Native Packages and Shared Skill Cleanup — Claudary (https://claudary.paisolsolutions.com/skills/2026-04-18-001-refactor-native-install-cleanup-plan)"
---

# Recenter Installs on Native Packages and Shared Skill Cleanup
Rework the install strategy around current agent-harness behavior:

## Overview

---
title: "refactor: Recenter installs on native packages and shared skill cleanup"
type: refactor
status: active
date: 2026-04-18
---

# Recenter Installs on Native Packages and Shared Skill Cleanup

## Overview

Rework the install strategy around current agent-harness behavior:

- Use native package/plugin installers where they can install the full Compound Engineering payload.
- Avoid `~/.agents` for CE-owned installs because shared skills there can shadow native plugin installs such as Copilot.
- Keep agents target-native unless the harness's package format explicitly supports bundled agents.
- Add a first-class cleanup path for old CE-owned flat installs, renamed skills, removed skills, converted-agent skills, prompts, commands, and target-specific artifacts.

This plan supersedes the Copilot-only native plugin plan because the same decision now affects Codex, Gemini, Pi, OpenCode, and every retained custom converter target.

## Problem Frame

The current CLI grew when most targets did not have native package/plugin support. That is no longer uniformly true:

- Claude Code has native plugin marketplaces.
- Copilot CLI has plugin marketplaces and can install repo-hosted plugins.
- Gemini CLI has native extensions and shared `~/.agents/skills` skill discovery.
- Pi has native packages via `pi install` and also reads `~/.agents/skills`.
- Codex has native plugins, but current public docs still make non-official distribution depend on local/repo/personal marketplace files.
- OpenCode also reads `~/.agents/skills`, but CE should avoid that root by default because it can shadow Copilot plugin skills.
- Windsurf no longer needs active support and should be deprecated from user-facing conversion/install flows while preserving cleanup for old CE artifacts.

At the same time, our legacy installs leave stale flat artifacts behind. Examples include removed skills such as `reproduce-bug`, renamed workflows such as `workflows:*` -> `ce:*`, old prompt files, and agents that older converters flattened into skills. We cannot delete all of `~/.agents/skills` or `~/.codex/skills` because users may have non-CE skills there.

## Requirements Trace

- R1. Prefer native installers when they install the full useful payload with a reasonable user flow.
- R2. Do not write CE-owned installs to `~/.agents`; treat it as a legacy cleanup surface only.
- R3. Preserve target-specific agent behavior where the harness supports agents.
- R4. Continue converting agents to skills only for targets that lack compatible agent packaging or invocation.
- R5. Track all CE legacy skills, agents, commands, prompts, and generated aliases so cleanup can remove stale CE-owned artifacts without touching user-owned items.
- R6. Any remaining custom install path must run legacy cleanup on every install.
- R7. Native-install targets must have a documented one-time cleanup command users can run before switching from old Bun installs.
- R8. Forward installs must write a manifest so removed or renamed artifacts can be cleaned without expanding the hand-maintained legacy list forever.
- R9. The README and target specs must clearly distinguish native installer paths from legacy/custom converter paths.
- R10. Deprecate Windsurf support and preserve cleanup for old CE Windsurf installs.

## External Research Summary

| Harness | Shared `~/.agents/skills` | Native package/plugin install | Agent support path | Planning conclusion |
| --- | --- | --- | --- | --- |
| Claude Code | Not the primary install path for this repo | Yes, `/plugin marketplace add` + `/plugin install` | Plugin `agents/` | Keep Claude native plugin as canonical. No Bun install needed for Claude. |
| Codex | Yes, but CE should avoid it to prevent Copilot plugin shadowing. Codex also discovers `~/.codex/skills` in current local behavior. | Yes, but current docs describe official plugin directory plus local repo/personal marketplace files. | Custom agents are TOML under `~/.codex/agents` or `.codex/agents`, not `~/.agents/agents`. | Keep custom Codex install. Write CE skills under `~/.codex/skills/compound-engineering` and convert Claude agents to flat Codex TOML custom agents under `~/.codex/agents`. |
| Copilot CLI | Yes. Docs list project `.agents/skills` and personal `~/.agents/skills`. | Yes. `copilot plugin marketplace add OWNER/REPO`, then `copilot plugin install NAME@MARKETPLACE`. Copilot can read existing `.claude-plugin/marketplace.json` and `.claude-plugin/plugin.json`. | Personal `~/.copilot/agents`, project `.github/agents`, Claude-compatible `~/.claude/agents` / `.claude/agents`, and plugin `agents/`. No documented `~/.agents/agents`. | Move Copilot to native plugin distribution using the existing Claude plugin metadata. Remove user-facing Bun install. |
| Gemini CLI | Yes, but CE should avoid it to prevent Copilot plugin shadowing. | Yes. `gemini extensions install <github-url-or-local-path>`, but monorepo subdirectory install is not documented. | Project `.gemini/agents`, user `~/.gemini/agents`, and extension `agents/`. The verified `.agents/*` alias is for skills, not subagents. | Keep custom Bun install to `~/.gemini/{skills,agents,commands}` for now; revisit native extension distribution later. |
| Pi | Yes. Docs list `~/.agents/skills` and `.agents/skills`. | Yes. `pi install npm:...`, `pi install git:...`, URL, or local path. | Core Pi has no built-in subagents; subagents are extension/package-provided. Packages can bundle extensions, skills, prompts, themes. | Prefer a Pi package if we can package the existing compat extension, prompts, and skills cleanly. Until then, keep custom writer and cleanup. |
| OpenCode | Yes, but CE should avoid it to prevent Copilot plugin shadowing. | Partial. OpenCode has plugins/config, but no equivalent repo marketplace install for our full payload in current target design. | Agents are OpenCode markdown/config under `~/.config/opencode/agents` or `.opencode/agents`. | Keep custom writer for agents/config; do not share pass-through skills via `~/.agents/skills` by default. |
| Factory Droid | No confirmed `~/.agents/skills`; docs mention `.factory/skills`, `~/.factory/skills`, and project `.agent/skills` compatibility. | Yes. `droid plugin marketplace add <repo>`, then `droid plugin install NAME@MARKETPLACE`. Droid can install Claude Code-compatible plugins directly. | Plugin agents load through the native plugin translation path. | Move Droid to native plugin distribution and remove user-facing Bun install. |
| Kiro | No confirmed `~/.agents/skills` in current docs. | Has import flows, but not a CE-wide plugin install path in current target. | Agents are `.kiro/agents` JSON + prompt files. | Keep custom writer. |
| Windsurf | No longer relevant for CE support. | N/A | Current converter maps agents to skills. | Deprecate/remove user-facing support; keep legacy cleanup for old CE Windsurf installs. |
| Qwen Code | No shared `~/.agents` conclusion needed. | Extension-oriented target already has per-plugin root. | Qwen supports target-native agents. | Keep custom writer/package output. |

Sources checked:

- Codex skills: `https://developers.openai.com/codex/skills`
- Codex plugins: `https://developers.openai.com/codex/plugins` and `https://developers.openai.com/codex/plugins/build`
- Codex subagents: `https://developers.openai.com/codex/subagents`
- Copilot agents/skills/plugins: `https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli`, `https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills`, `https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference`
- Gemini skills/subagents/extensions: `https://geminicli.com/docs/cli/skills/`, `https://geminicli.com/docs/core/subagents/`, `https://geminicli.com/docs/extensions/reference/`, `https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/`
- Pi skills/packages: `https://buildwithpi.ai/README.md`, `https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md`, `https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/packages.md`
- OpenCode skills/agents: `https://opencode.ai/docs/skills`, `https://opencode.ai/docs/agents/`
- Factory Droid skills: `https://docs.factory.ai/cli/configuration/skills`
- Kiro skills/agents: `https://kiro.dev/docs/skills/`, `https://kiro.dev/docs/cli/custom-agents/configuration-reference/`

## Key Decisions

### 1. Do not make `~/.agents` a CE-managed install root

`~/.agents/plugins/marketplace.json` is documented by Codex as a personal marketplace file, not as a cross-harness plugin installation convention. Copilot installs plugins under `~/.copilot/installed-plugins`, Gemini installs extensions under `~/.gemini/extensions`, and Pi packages install through Pi settings plus npm/git/local package storage.

`~/.agents/skills` is also unsafe as a CE-managed install root. Copilot loads personal/project skills before plugin skills and deduplicates by `SKILL.md` `name`. A CE skill installed into `~/.agents/skills` for another target can silently shadow the same skill from Copilot's native plugin.

Treat `~/.agents` as a legacy cleanup surface, not a forward install surface.

### 2. Use native package distribution by target, not one universal folder

Native targets should have target-native packaging:

- Claude: existing `.claude-plugin` marketplace/plugin.
- Copilot: reuse existing `.claude-plugin` marketplace/plugin metadata. Do not add a parallel `.github/plugin` surface unless a future Copilot-only manifest field becomes necessary.
- Gemini: custom Bun install to `~/.gemini/{skills,agents,commands}` for now; future `gemini-extension.json` distribution remains possible.
- Pi: npm/git/local package with `package.json` `pi` manifest.
- Codex: `~/.codex/skills/compound-engineering`, `~/.codex/agents`, and optional future `.codex-plugin/plugin.json`, but do not retire custom install until remote install UX is verified.

### 3. Agents are not portable via `~/.agents`

`~/.agents/skills` is increasingly common. `~/.agents/agents` is not documented by the primary sources checked for Codex, Copilot, or Gemini. Agent support must remain per target:

- Copilot agents: markdown agent files under `~/.copilot/agents`, `.github/agents`, Claude-compatible `.claude/agents` / `~/.claude/agents`, or plugin `agents`.
- Gemini sub-agents: markdown files under `.gemini/agents`, `~/.gemini/agents`, or extension `agents/`.
- Codex custom agents: TOML files under `.codex/agents` / `~/.codex/agents`. CE should generate these from Claude Markdown agents instead of degrading them into skills.
- OpenCode agents: markdown/config under `.opencode/agents` / `~/.config/opencode/agents`.
- Kiro agents: JSON configs and prompt files under `.kiro/agents`.
- Pi: no built-in subagents; package an extension if CE needs subagent behavior.

This means the previous "convert agents to skills" behavior remains legitimate for targets without compatible agent packaging, but it should not be applied to Copilot and Gemini unless intentionally degraded. Gemini's April 2026 subagent support makes this more important: Gemini output should package CE agents as subagents under Gemini-owned roots, while `~/.agents` remains cleanup-only.

### 4. Cleanup must be a product feature, not incidental writer behavior

Current cleanup work in `src/data/plugin-legacy-artifacts.ts` is the right direction, but it is too writer-bound. We need a standalone cleanup command that can run before switching users from old Bun installs to native harness installers.

Custom writers should still invoke cleanup automatically. Native installers cannot clean old CE artifacts in unrelated roots, so users need an explicit CE cleanup command.

### 5. Legacy inventory should be generated and validated against git history

The hand-maintained legacy list should be backed by a script that scans historical plugin inventories from git history:

- `plugins/compound-engineering/skills/*`
- `plugins/compound-engineering/agents/*`
- `plugins/compound-engineering/commands/*`
- historical `prompts/*` or converted command outputs
- renamed colon/underscore/hyphen variants per target

The result should be committed as data, and tests should fail when the current or historical source inventory includes an untracked CE artifact.

## Implementation Units

- [ ] **Unit 1: Add a platform install strategy spec**

**Goal:** Replace ad hoc target assumptions with one repo-owned matrix for native vs custom install, shared-skill support, and agent support.

**Requirements:** R1, R2, R3, R4, R9

**Files:**
- Create: `docs/solutions/integrations/native-plugin-install-strategy-2026-04-19.md`
- Modify: `README.md`
- Modify as needed: `docs/specs/codex.md`, `docs/specs/copilot.md`, `docs/specs/gemini.md`, `docs/specs/opencode.md`

**Approach:**
- Document why CE avoids `~/.agents/skills` despite broad discovery support.
- Document target-native package locations and install commands.
- Mark each current target as `native-primary`, `custom-primary`, or `hybrid`.
- Explicitly list whether source Claude agents become target agents or generated skills.

**Test scenarios:**
- README no longer implies all targets require the same Bun install path.
- Target specs agree on whether a target uses native install or custom writer.

---

- [ ] **Unit 2: Build a standalone CE cleanup command**

**Goal:** Give users one command to remove stale CE-owned artifacts from old installs before or during migration to native installers.

**Requirements:** R5, R6, R7, R8

**Files:**
- Create: `src/commands/cleanup.ts`
- Create or Modify: `src/cleanup/*`
- Modify: `src/index.ts`
- Modify: `src/targets/*` custom writers to call shared cleanup helpers
- Modify: `tests/cli.test.ts`
- Add targeted cleanup tests under `tests/`

**Approach:**
- Add a command such as `compound cleanup compound-engineering --targets codex,copilot,gemini,pi,opencode,droid --apply`.
- Default to dry-run unless the existing CLI convention strongly favors direct action.
- Move matched legacy artifacts to a timestamped backup rather than hard-deleting.
- Only touch known CE-owned artifacts, existing install-manifest entries, and symlinks whose targets are CE-managed.
- Cover `~/.agents/skills`, `~/.codex/skills`, `~/.codex/prompts`, `~/.copilot/skills`, `~/.copilot/agents`, `~/.gemini/skills`, `~/.gemini/agents`, `~/.gemini/commands`, `~/.pi/agent/{skills,prompts,extensions}`, `~/.config/opencode/{skills,agents,commands,plugins}`, `~/.factory/{skills,commands,droids}`, deprecated `~/.codeium/windsurf/{skills,workflows,mcp_config.json}`, and other current writer roots.

**Test scenarios:**
- Dry run reports stale `reproduce-bug` without moving it.
- Apply moves stale CE artifacts to backup.
- Non-CE skill with the same parent directory root is preserved.
- A CE-managed symlink in `~/.agents/skills` is removed or moved safely.
- A real user-owned directory at a CE-looking path is skipp

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/2026-04-18-001-refactor-native-install-cleanup-plan) · https://claudary.paisolsolutions.com