refactor(install): prefer native plugin install across targets (#609)
Co-authored-by: John Cavanaugh <cavanaug@users.noreply.github.com>
This commit is contained in:
Trevin Chow
@@ -0,0 +1,354 @@
|
||||
---
|
||||
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 skipped unless manifest/history proves CE ownership.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 3: Generate and validate the historical CE artifact manifest**
|
||||
|
||||
**Goal:** Prevent future cleanup gaps when skills or agents are removed, renamed, or converted.
|
||||
|
||||
**Requirements:** R5, R8
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/data/plugin-legacy-artifacts.ts`
|
||||
- Create: `scripts/generate-legacy-artifacts.ts` or similar
|
||||
- Create: `tests/plugin-legacy-artifacts-history.test.ts`
|
||||
- Modify: existing `tests/plugin-legacy-artifacts.test.ts`
|
||||
|
||||
**Approach:**
|
||||
- Scan git history for CE plugin directories and normalize names per target.
|
||||
- Preserve hand-added aliases only for cases not recoverable from source directory history.
|
||||
- Commit generated data in a stable sorted form.
|
||||
- Test that current source artifacts and known removed artifacts are included.
|
||||
|
||||
**Test scenarios:**
|
||||
- Removed `reproduce-bug` remains in cleanup data.
|
||||
- If `document-review` is renamed to `ce-doc-review`, both old and new cleanup-relevant names are tracked.
|
||||
- Historical `prompts` outputs remain cleanup candidates.
|
||||
- Colon, underscore, and hyphen variants normalize correctly for Codex, Gemini, Pi, and OpenCode.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 4: Move Copilot to native plugin distribution through existing Claude metadata**
|
||||
|
||||
**Goal:** Replace user-facing `bunx ... --to copilot` with Copilot marketplace/plugin install.
|
||||
|
||||
**Requirements:** R1, R3, R4, R7, R9
|
||||
|
||||
**Files:**
|
||||
- Modify: `README.md`
|
||||
- Modify: `docs/specs/copilot.md`
|
||||
- Modify: CLI target registration/tests if direct install is deprecated
|
||||
- Reassess/remove: `src/converters/claude-to-copilot.ts`, `src/targets/copilot.ts`, `src/types/copilot.ts`, and Copilot writer/converter tests if they no longer serve release validation
|
||||
|
||||
**Approach:**
|
||||
- Use the existing root `.claude-plugin/marketplace.json`; Copilot CLI explicitly looks there for marketplace metadata.
|
||||
- Use the existing plugin-local `.claude-plugin/plugin.json`; Copilot CLI can discover plugin manifests from `.claude-plugin/plugin.json`.
|
||||
- Document Copilot native install instructions:
|
||||
- `copilot plugin marketplace add EveryInc/compound-engineering-plugin`
|
||||
- `copilot plugin install compound-engineering@compound-engineering-plugin`
|
||||
- Keep plugin agents as agents, not generated skills.
|
||||
- Do not create parallel `.github/plugin` metadata or `agents-copilot/` output unless a real compatibility failure is proven.
|
||||
- Run or recommend `compound cleanup compound-engineering --targets copilot,codex --apply` before switching old installs.
|
||||
- Treat stale Copilot skills as a shadowing risk, not only a duplicate-display risk. Copilot deduplicates skills by `SKILL.md` `name` with first-found-wins precedence, and personal/project skill roots such as `~/.agents/skills` load before plugin skills.
|
||||
|
||||
**Test scenarios:**
|
||||
- Existing `.claude-plugin/marketplace.json` parses and has a `compound-engineering` entry whose `source` points at `plugins/compound-engineering`.
|
||||
- Existing `plugins/compound-engineering/.claude-plugin/plugin.json` parses and is valid enough for both Claude and Copilot.
|
||||
- Copilot docs/spec record the native install commands and the `.claude-plugin` compatibility.
|
||||
- README does not advertise old direct Copilot Bun install as the primary path.
|
||||
- If possible, a local-path Copilot plugin install in a temporary config directory succeeds without modifying the user's real Copilot home.
|
||||
- A seeded stale `~/.agents/skills/ce-plan/SKILL.md` shadows a plugin-provided `ce-plan` in docs/tests or manual verification, proving cleanup is required even when Copilot does not show duplicate skills.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 5: Update Gemini custom install and defer extension packaging**
|
||||
|
||||
**Goal:** Keep Gemini on the custom Bun installer for now, but make it write Gemini-native skills and subagents under `~/.gemini` without using `~/.agents`.
|
||||
|
||||
**Requirements:** R1, R3, R4, R7, R9
|
||||
|
||||
**Files:**
|
||||
- Create or Generate: Gemini skill/agent/command payloads as needed
|
||||
- Modify: `docs/specs/gemini.md`
|
||||
- Modify: `README.md`
|
||||
- Reassess: `src/converters/claude-to-gemini.ts`, `src/targets/gemini.ts`
|
||||
|
||||
**Approach:**
|
||||
- Write pass-through skills to `~/.gemini/skills`.
|
||||
- Write normalized flat Gemini subagents to `~/.gemini/agents`.
|
||||
- Write command TOML files to `~/.gemini/commands` if CE ships commands again.
|
||||
- Write a managed manifest to `~/.gemini/compound-engineering/install-manifest.json`.
|
||||
- Do not write CE-owned Gemini artifacts to `~/.agents/skills`.
|
||||
- Do not assume `gemini extensions install` supports `--path` for a monorepo subdirectory. Current docs and local help list GitHub repository URL or local path sources, while `--path` is documented for `gemini skills install`.
|
||||
- Defer native extension distribution until we choose a shape where the installed source root contains `gemini-extension.json`: dedicated Gemini extension repo, generated distribution branch/package, or release asset.
|
||||
- Preserve agent prompt bodies where possible; the necessary work is flattening agent files into direct `agents/*.md` entries and stripping/translating Claude-specific frontmatter such as `color` and string-form `tools`.
|
||||
|
||||
**Test scenarios:**
|
||||
- Bun install writes to Gemini-owned roots and does not write to `~/.agents/skills`.
|
||||
- Gemini-specific agents are packaged as extension sub-agents, not flattened into skills unless deliberately configured.
|
||||
- Generated Gemini agents are flat direct files under `~/.gemini/agents`, contain strict Gemini-compatible frontmatter, and load without validation errors.
|
||||
- Legacy `.gemini` direct install cleanup still runs from the cleanup command.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 6: Add or defer Pi package distribution**
|
||||
|
||||
**Goal:** Decide whether CE can be installed with `pi install` and, if yes, package the existing Pi output as a real Pi package.
|
||||
|
||||
**Requirements:** R1, R4, R6, R7, R9
|
||||
|
||||
**Files:**
|
||||
- Create or Modify: package metadata for Pi package distribution
|
||||
- Modify: `docs/specs/pi.md` if created, otherwise add one
|
||||
- Modify: `README.md`
|
||||
- Reassess: `src/converters/claude-to-pi.ts`, `src/targets/pi.ts`
|
||||
|
||||
**Approach:**
|
||||
- Prefer npm package distribution if we want to avoid asking users to manually clone a repository.
|
||||
- Package Pi resources with `package.json` `pi` manifest: `skills`, `prompts`, and `extensions`.
|
||||
- Resolve the existing compat-extension conflict risk before promoting Pi native package as primary.
|
||||
- Until packaged and tested, keep the custom Pi writer and have it call shared cleanup every install.
|
||||
|
||||
**Test scenarios:**
|
||||
- Pi package manifest includes skills/prompts/extensions.
|
||||
- Existing `compound-engineering-compat.ts` does not conflict with popular subagent packages or is made conditional.
|
||||
- Cleanup removes old direct writer artifacts under `~/.pi/agent`.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 7: Rationalize remaining custom targets and deprecate Windsurf**
|
||||
|
||||
**Goal:** Make explicit which targets still need the Bun converter/install path, remove Windsurf from active support, and ensure each retained or deprecated target has cleanup coverage.
|
||||
|
||||
**Requirements:** R4, R6, R8, R9, R10
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/targets/index.ts`
|
||||
- Modify: `src/targets/{codex,opencode,kiro,qwen}.ts`
|
||||
- Delete: custom plugin install writers for native-marketplace targets such as Droid and Copilot
|
||||
- Delete: `src/converters/claude-to-windsurf.ts`, `src/types/windsurf.ts`, `src/targets/windsurf.ts`, `src/sync/windsurf.ts`, `tests/windsurf-*.test.ts`
|
||||
- Modify: README target table
|
||||
- Modify: target writer tests
|
||||
|
||||
**Approach:**
|
||||
- Keep custom targets where native install does not cover the full payload or is not documented enough.
|
||||
- Run shared cleanup for each custom install.
|
||||
- Deprecate Windsurf from user-facing `convert`, `install`, `sync`, README, and target lists.
|
||||
- Preserve Windsurf cleanup support so old CE artifacts can be removed from `~/.codeium/windsurf/` even after active support is gone.
|
||||
- For Codex, keep current custom install as primary until native plugin distribution from a GitHub repo is as simple as Copilot/Gemini/Pi or until official directory publishing is available.
|
||||
- For Codex skills, write to `~/.codex/skills/compound-engineering/<skill>` with a manifest under `~/.codex/compound-engineering/`; do not write to `~/.agents/skills`.
|
||||
- For Codex agents, convert Claude Markdown agents to flat TOML custom agents under `~/.codex/agents` using CE-prefixed names such as `ce-review-correctness-reviewer`, and update converted skill content so `Task`/agent references explicitly ask Codex to spawn the named custom agent.
|
||||
- The Codex skill-plus-agent split was smoke-tested on 2026-04-18: a skill in `~/.agents/skills/ce-codex-agent-smoke` successfully spawned a TOML custom agent from `~/.codex/agents/ce-codex-agent-smoke.toml` and returned `CODEX_TOML_AGENT_SMOKE_OK`.
|
||||
- Codex duplicate discovery was also smoke-tested on 2026-04-18: the same skill name installed under both `~/.agents/skills` and legacy `~/.codex/skills` appeared twice in the skill picker. Codex cleanup must remove old CE-owned skills from both roots before writing the namespaced `~/.codex/skills/compound-engineering` install.
|
||||
- Shared skill nesting was smoke-tested on 2026-04-18: Codex discovered flat, nested, and Superpowers-style symlink-pack skills under `~/.agents/skills`, but Copilot and Gemini only discovered the flat direct `~/.agents/skills/<skill>/SKILL.md` shape. CE should avoid this root anyway because of Copilot shadowing.
|
||||
- For OpenCode, do not share pass-through skills via `~/.agents/skills` unless the user explicitly opts into cross-harness shared skills and understands Copilot shadowing.
|
||||
|
||||
**Test scenarios:**
|
||||
- Each custom writer calls cleanup with the correct target roots.
|
||||
- Target writer manifests remove artifacts that disappear between installs.
|
||||
- Windsurf is no longer advertised or selectable as an active install target.
|
||||
- Cleanup can still identify and back up old CE Windsurf artifacts.
|
||||
- README table matches registered target behavior.
|
||||
|
||||
## Sequencing
|
||||
|
||||
1. Land the strategy spec and cleanup command first. This reduces migration risk no matter which native packaging target lands next.
|
||||
2. Promote Copilot native install next because its plugin marketplace flow is documented and closest to Claude's model.
|
||||
3. Add Gemini extension packaging after Copilot because Gemini can bundle skills, commands, and preview sub-agents through extensions.
|
||||
4. Decide Pi packaging after resolving the extension conflict and npm-package shape.
|
||||
5. Revisit Codex native plugins last; the platform supports plugins, but the public distribution UX still appears less direct than Copilot/Gemini/Pi for a GitHub-hosted third-party plugin.
|
||||
6. Deprecate Windsurf and keep the remaining custom targets, with cleanup mandatory and manifest-backed.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should the cleanup command default to dry-run or apply? Recommendation: dry-run for standalone use, apply automatically inside custom install writers.
|
||||
- Should native package payloads be checked in or generated during release validation? Recommendation: generated but checked for determinism in CI if the target package must be present in the repo.
|
||||
- Should the existing `@every-env/compound-plugin` npm package also become the Pi package, or should Pi get a smaller dedicated npm package? Recommendation: investigate package contents first; avoid bloating Pi installs with converter-only code if avoidable.
|
||||
- Should Codex native plugin support be documented as experimental alongside custom install? Recommendation: yes, but do not retire custom install until remote marketplace install is verified end to end.
|
||||
|
||||
## Verification
|
||||
|
||||
- `bun test` after implementation units touching CLI, writers, or conversion.
|
||||
- `bun run release:validate` after native package manifests or plugin inventory changes.
|
||||
- Manual smoke tests for native installers:
|
||||
- Claude: `/plugin install compound-engineering`
|
||||
- Copilot: `copilot plugin marketplace add EveryInc/compound-engineering-plugin` then install
|
||||
- Gemini: `gemini extensions install <repo-url-or-local-path>`
|
||||
- Pi: `pi install npm:<package>` or local package path
|
||||
- Cleanup smoke test with seeded temp homes for `~/.agents`, `~/.codex`, `~/.copilot`, `~/.gemini`, `~/.pi`, `~/.config/opencode`, and `~/.factory`.
|
||||
@@ -0,0 +1,686 @@
|
||||
---
|
||||
title: "Native plugin install strategy for supported harnesses"
|
||||
date: 2026-04-19
|
||||
category: integrations
|
||||
module: installer
|
||||
problem_type: integration_decision
|
||||
component: installer
|
||||
symptoms:
|
||||
- "Multiple harnesses can discover the same CE skills from shared roots and create duplicates or shadowing"
|
||||
- "Some harnesses now support native Claude-compatible plugin installs, making custom Bun installs redundant"
|
||||
- "Old manual installs can leave stale skills and agents after CE renames or deprecations"
|
||||
root_cause: evolving_platform_install_surfaces
|
||||
resolution_type: install_strategy
|
||||
severity: medium
|
||||
tags:
|
||||
- install-strategy
|
||||
- native-plugins
|
||||
- legacy-cleanup
|
||||
- cursor
|
||||
- codex
|
||||
- copilot
|
||||
- droid
|
||||
- qwen
|
||||
- gemini
|
||||
- opencode
|
||||
- kiro
|
||||
---
|
||||
|
||||
# Native Plugin Install Strategy
|
||||
|
||||
Last verified: 2026-04-19
|
||||
|
||||
This document records the intended install model by harness. The current priority is separating native marketplace installs from custom Bun installs so CE does not create duplicate or shadowing skills across tools.
|
||||
|
||||
## Summary
|
||||
|
||||
| Harness | Intended install path | Custom Bun install? | Legacy cleanup needed? | Notes |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Claude Code | Native plugin marketplace using existing `.claude-plugin/marketplace.json` and `plugins/compound-engineering/.claude-plugin/plugin.json` | No | Only for old/manual non-native installs, if any | Current repo shape already satisfies Claude Code. |
|
||||
| Cursor | Native Cursor Plugin Marketplace using existing `.cursor-plugin/marketplace.json` and `plugins/compound-engineering/.cursor-plugin/plugin.json` | No, CE plugin install/convert target removed | No for marketplace installs; add targeted cleanup only if historical custom Cursor artifacts are confirmed | Users install from Cursor Agent chat with `/add-plugin compound-engineering` or by searching the plugin marketplace. |
|
||||
| GitHub Copilot CLI | Native plugin marketplace using the same existing `.claude-plugin` metadata | No, CE plugin install/convert target removed | Yes, before or during migration from previous `.github/` custom installs | Tested manually: Copilot can install from the existing CE marketplace and load agents. |
|
||||
| Factory Droid | Native plugin marketplace pointed at the CE GitHub repository | No, CE plugin install/convert target removed | Yes, before or during migration from previous `~/.factory` custom installs | Droid docs say Claude Code plugins install directly and are translated automatically; `ce-doc-review` was manually tested in Droid. |
|
||||
| Qwen Code | Native extension install from the CE GitHub repository and existing Claude plugin metadata | No, CE plugin install/convert target removed | Yes, before or during migration from previous `~/.qwen` custom installs | Qwen docs say Claude Code extensions install directly from GitHub and are converted automatically; native install was manually tested on 2026-04-19. |
|
||||
| OpenCode | Custom CE install to `~/.config/opencode/{skills,agents,plugins}` plus merged `opencode.json`; source commands are written only if present | Yes | Yes, every install | OpenCode plugins are JS/TS or npm hooks/tools, not a Claude-compatible marketplace install path for CE's full plugin payload. |
|
||||
| Pi | Custom CE install to `~/.pi/agent/{skills,prompts,extensions}` plus MCPorter config; source commands are written only if present | Yes, until CE ships and tests a Pi package | Yes, every install | Pi has package install support, but CE has not yet packaged the compat extension, generated skills, prompts, and MCPorter config into a tested Pi package. |
|
||||
| Codex | Custom CE install to `~/.codex/skills/compound-engineering/<skill>` and `~/.codex/agents/compound-engineering/<agent>.toml` | Yes, because native Codex plugins do not currently register bundled custom agents | Yes, every install | Avoid `~/.agents/skills` so Codex installs do not shadow Copilot's native plugin skills. Claude agents are converted to Codex TOML custom agents. |
|
||||
| Gemini CLI | Custom CE install to `~/.gemini/{skills,agents}` for now; source commands are written only if present; native extension packaging exists but does not fit CE's current repo/package layout | Yes, until CE ships a Gemini extension root, release artifact, or dedicated distribution branch/repo | Yes, every install | Avoid `~/.agents/skills`; write normalized Gemini agents to `~/.gemini/agents`. |
|
||||
| Kiro CLI | Custom CE install to project `.kiro/{skills,agents,steering,settings}` | Yes | Yes, every install; manual `cleanup --target kiro` also exists | Kiro has its own JSON agent format and project-local install root. |
|
||||
|
||||
Deprecated targets:
|
||||
|
||||
- Windsurf is no longer an active CE install, convert, or sync target. `cleanup --target windsurf` remains available only to back up old CE-owned files from previous Bun installs under `~/.codeium/windsurf/` or workspace `.windsurf/`.
|
||||
|
||||
Removed capabilities:
|
||||
|
||||
- Personal Claude Code home sync (`bunx @every-env/compound-plugin sync`) has been removed. Syncing arbitrary `~/.claude` skills, commands, agents, and MCP config across unrelated harnesses is not a bounded compatibility surface; CE only supports installing the CE plugin and cleaning up old CE-owned artifacts.
|
||||
|
||||
Current CE command posture:
|
||||
|
||||
- The `compound-engineering` plugin currently ships no Claude `commands/` files. Its workflow entry points are skills invoked with slash syntax, such as `/ce-plan`, `/ce-work`, and `/ce-doc-review`.
|
||||
- The CLI still understands source plugin commands for legacy cleanup and for converting non-CE Claude plugins that still ship commands. CE install docs should not describe commands as part of the current CE payload except as legacy/source-plugin compatibility.
|
||||
|
||||
## Global Decision: Avoid `~/.agents` For CE-Owned Installs
|
||||
|
||||
Do not install CE-owned skills or agents into `~/.agents` for normal target installs.
|
||||
|
||||
Several harnesses read `~/.agents/skills`, but Copilot CLI gives personal/project skill roots precedence over plugin skills. A CE skill written for Codex, Gemini, Pi, or another target into `~/.agents/skills` can silently shadow the same skill from Copilot's native plugin install. That makes `~/.agents` unsafe as a shared CE-managed install root.
|
||||
|
||||
Use target-owned roots instead:
|
||||
|
||||
```text
|
||||
OpenCode: ~/.config/opencode/skills/<skill>/SKILL.md
|
||||
~/.config/opencode/agents/<agent>.md
|
||||
~/.config/opencode/commands/*.md # source commands only, if present
|
||||
~/.config/opencode/opencode.json
|
||||
|
||||
Pi: ~/.pi/agent/skills/<skill>/SKILL.md
|
||||
~/.pi/agent/prompts/*.md # source commands only, if present
|
||||
~/.pi/agent/extensions/*.ts
|
||||
~/.pi/agent/compound-engineering/mcporter.json
|
||||
|
||||
Codex: ~/.codex/skills/compound-engineering/<skill>/SKILL.md
|
||||
~/.codex/agents/compound-engineering/<agent>.toml
|
||||
|
||||
Gemini: ~/.gemini/skills/<skill>/SKILL.md
|
||||
~/.gemini/agents/<agent>.md
|
||||
~/.gemini/commands/*.toml # source commands only, if present
|
||||
|
||||
Copilot: managed by native plugin install under ~/.copilot
|
||||
Cursor: managed by native Cursor Plugin Marketplace install
|
||||
Droid: managed by native plugin install under ~/.factory for user scope
|
||||
Qwen: managed by native extension install under ~/.qwen
|
||||
```
|
||||
|
||||
`~/.agents/skills` remains a cleanup target only, because prior CE installs or experiments may have left shadowing skills there.
|
||||
|
||||
## Claude Code
|
||||
|
||||
### Decision
|
||||
|
||||
Claude Code is already satisfied by the current repo layout:
|
||||
|
||||
- Root marketplace: `.claude-plugin/marketplace.json`
|
||||
- Plugin root: `plugins/compound-engineering/`
|
||||
- Plugin manifest: `plugins/compound-engineering/.claude-plugin/plugin.json`
|
||||
- Plugin components: `agents/`, `skills/`, and related files under the plugin root. Claude `commands/` would be supported if reintroduced, but CE does not currently ship them.
|
||||
|
||||
Users install with:
|
||||
|
||||
```text
|
||||
/plugin marketplace add EveryInc/compound-engineering-plugin
|
||||
/plugin install compound-engineering
|
||||
```
|
||||
|
||||
No custom Bun install or conversion should be used for Claude Code.
|
||||
|
||||
### Cleanup
|
||||
|
||||
Native Claude plugin installs are owned by Claude Code. The CE cleanup command should not delete Claude Code's plugin cache. It should only handle explicitly known old/manual CE artifacts if we discover any historical non-native Claude install path.
|
||||
|
||||
## Cursor
|
||||
|
||||
### Decision
|
||||
|
||||
Cursor should use the native Cursor Plugin Marketplace, not `bunx @every-env/compound-plugin install compound-engineering --to cursor`.
|
||||
The custom Cursor plugin install/convert target has been removed from the CLI target registry.
|
||||
|
||||
The repo publishes Cursor marketplace metadata separately from the Claude marketplace:
|
||||
|
||||
- Root marketplace: `.cursor-plugin/marketplace.json`
|
||||
- Plugin manifest: `plugins/compound-engineering/.cursor-plugin/plugin.json`
|
||||
|
||||
Users install from Cursor Agent chat with:
|
||||
|
||||
```text
|
||||
/add-plugin compound-engineering
|
||||
```
|
||||
|
||||
They can also search for "compound engineering" in the plugin marketplace.
|
||||
|
||||
No custom Bun install or conversion should be used for Cursor.
|
||||
|
||||
### Cleanup
|
||||
|
||||
Cursor marketplace installs are owned by Cursor. CE should not delete Cursor's plugin marketplace cache.
|
||||
|
||||
If we discover historical CE-owned Cursor artifacts from the old custom writer that can shadow marketplace installs, add a targeted cleanup path for those known artifacts. Do not reintroduce Cursor as an active `convert` or `install` target.
|
||||
|
||||
## GitHub Copilot CLI
|
||||
|
||||
### Decision
|
||||
|
||||
Copilot should use native plugin install, not `bunx @every-env/compound-plugin install compound-engineering --to copilot`.
|
||||
The custom Copilot plugin install/convert target has been removed from the CLI target registry.
|
||||
|
||||
Copilot CLI can read:
|
||||
|
||||
- Marketplace manifests from `.claude-plugin/marketplace.json`
|
||||
- Plugin manifests from `.claude-plugin/plugin.json`
|
||||
- Plugin agents from the plugin `agents/` directory
|
||||
- Plugin skills from the plugin `skills/` directory
|
||||
|
||||
Users install inside Copilot CLI with:
|
||||
|
||||
```text
|
||||
/plugin marketplace add EveryInc/compound-engineering-plugin
|
||||
/plugin install compound-engineering@compound-engineering-plugin
|
||||
```
|
||||
|
||||
Shell equivalents:
|
||||
|
||||
```bash
|
||||
copilot plugin marketplace add EveryInc/compound-engineering-plugin
|
||||
copilot plugin install compound-engineering@compound-engineering-plugin
|
||||
```
|
||||
|
||||
Do not add a parallel `.github/plugin/marketplace.json`, `.github/plugin/plugin.json`, or generated `agents-copilot/` directory unless a real compatibility failure appears. Manual testing showed Copilot can install from the existing CE marketplace and load CE agents.
|
||||
|
||||
Copilot skill conflicts are not displayed like Codex duplicate skills. Copilot deduplicates skills by the `name` field in `SKILL.md` using first-found-wins precedence. Project and personal skill locations, including `~/.agents/skills`, load before plugin skills. Therefore a stale `~/.agents/skills/ce-plan/SKILL.md` with `name: ce-plan` would shadow the plugin's `ce-plan` and the plugin skill would be silently ignored.
|
||||
|
||||
### Cleanup
|
||||
|
||||
The old custom Copilot target wrote generated files under `.github/`-style output. Users who installed that way should run CE legacy cleanup before or during migration so they do not have duplicate agents or skills from both the old Bun output and the native plugin.
|
||||
|
||||
For Copilot, "duplicate" often means silent shadowing rather than two visible entries. Cleanup must remove CE-owned stale skills from project and personal skill roots before switching to native plugin install, otherwise users can appear to have the native plugin installed while actually running an old flat skill.
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
bunx @every-env/compound-plugin cleanup --target copilot
|
||||
```
|
||||
|
||||
The cleanup command backs up known CE-owned Copilot artifacts such as:
|
||||
|
||||
- Generated `.github/agents/*.agent.md` files from old installs
|
||||
- Generated `.github/skills/*/SKILL.md` directories from old installs
|
||||
- Generated `~/.copilot/{agents,skills}` files from personal old installs
|
||||
- Shared `~/.agents/skills/*` CE skills that would shadow native Copilot plugin skills
|
||||
- Any tracked install-manifest entries from the old writer
|
||||
|
||||
It must not delete user-authored `.github/agents` or `.github/skills` content unless manifest/history proves CE ownership.
|
||||
|
||||
## Factory Droid
|
||||
|
||||
### Decision
|
||||
|
||||
Droid should use native plugin marketplace install, not `bunx @every-env/compound-plugin install compound-engineering --to droid`.
|
||||
The custom Droid plugin install/convert target has been removed from the CLI target registry.
|
||||
|
||||
Users install with:
|
||||
|
||||
```bash
|
||||
droid plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin
|
||||
droid plugin install compound-engineering@compound-engineering-plugin
|
||||
```
|
||||
|
||||
Factory's docs describe GitHub marketplace installation, user/project/org plugin scopes, and direct Claude Code plugin compatibility. They explicitly say Droid can install a Claude Code plugin directly and automatically translate the format. Manual testing on 2026-04-19 confirmed Droid could run `ce-doc-review` from the CE plugin and load both the skill and agents.
|
||||
|
||||
This means Droid is now in the same category as Claude Code and Copilot for CE distribution: use the native marketplace/plugin install path, not a generated custom Bun install.
|
||||
|
||||
### Cleanup
|
||||
|
||||
The old custom Droid target wrote CE-owned artifacts under `~/.factory`, especially:
|
||||
|
||||
- `~/.factory/skills/*`
|
||||
- `~/.factory/droids/*.md`
|
||||
- `~/.factory/commands/*.md`
|
||||
- any CE install manifest or managed backup directory created by the old writer
|
||||
|
||||
Before users migrate from the old Bun install to the native Droid plugin, legacy cleanup should remove or back up CE-owned generated files so the native plugin is not shadowed by stale local artifacts.
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
bunx @every-env/compound-plugin cleanup --target droid
|
||||
```
|
||||
|
||||
The cleanup command must not delete Droid's native plugin cache or user-authored Droid files. It should only remove artifacts proven to be CE-owned by an install manifest, known historical CE names, or generated CE metadata.
|
||||
|
||||
## Qwen Code
|
||||
|
||||
### Decision
|
||||
|
||||
Qwen should use native extension install, not `bunx @every-env/compound-plugin install compound-engineering --to qwen`.
|
||||
The custom Qwen plugin install/convert target has been removed from the CLI target registry.
|
||||
|
||||
Users install with:
|
||||
|
||||
```bash
|
||||
qwen extensions install EveryInc/compound-engineering-plugin:compound-engineering
|
||||
```
|
||||
|
||||
Qwen Code's extension docs say it can install Claude Code extensions directly from GitHub and convert Claude plugin metadata to Qwen extension metadata automatically. Manual testing on 2026-04-19 confirmed the CE plugin installed successfully through Qwen's native path.
|
||||
|
||||
This is a better fit than the old custom writer because Qwen now owns the Claude-plugin compatibility layer. The old writer duplicated that logic and did not fully rewrite CE's agent-heavy skill content into Qwen subagent invocation syntax.
|
||||
|
||||
### Cleanup
|
||||
|
||||
The old custom Qwen target wrote CE-owned artifacts under `~/.qwen`, especially:
|
||||
|
||||
- `~/.qwen/extensions/compound-engineering/` with CE-managed tracking keys in `qwen-extension.json`
|
||||
- `~/.qwen/skills/*`
|
||||
- `~/.qwen/agents/*.yaml`
|
||||
- `~/.qwen/agents/*.md`
|
||||
- `~/.qwen/commands/*.md`
|
||||
|
||||
Before users migrate from the old Bun install to the native Qwen extension, legacy cleanup should remove or back up CE-owned generated files so the native extension is not shadowed by stale local artifacts.
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
bunx @every-env/compound-plugin cleanup --target qwen
|
||||
```
|
||||
|
||||
Cleanup only backs up the old extension root when it finds the CE-managed tracking keys written by the legacy writer. This avoids deleting Qwen's current native extension cache after a successful native install.
|
||||
|
||||
## OpenCode
|
||||
|
||||
### Current Platform Facts
|
||||
|
||||
OpenCode's current install/discovery model is file-based:
|
||||
|
||||
- Skills are direct child directories with `SKILL.md` under `.opencode/skills/<name>/`, `~/.config/opencode/skills/<name>/`, `.claude/skills/<name>/`, `~/.claude/skills/<name>/`, `.agents/skills/<name>/`, or `~/.agents/skills/<name>/`.
|
||||
- Agents can be configured in `opencode.json` or as Markdown files under `~/.config/opencode/agents/` or `.opencode/agents/`.
|
||||
- Commands can be configured in `opencode.json` or as Markdown files under `~/.config/opencode/commands/` or `.opencode/commands/`.
|
||||
- Plugins are JavaScript/TypeScript modules loaded from `.opencode/plugins/` or `~/.config/opencode/plugins/`, or npm packages listed in the `plugin` option in `opencode.json`.
|
||||
|
||||
OpenCode has a plugin system, but it is not equivalent to Claude/Copilot/Droid plugin marketplaces. The official docs describe JS/TS hooks, custom tools, local plugin files, and npm package loading. They do not document a native marketplace command that can point at the CE GitHub repository, read `.claude-plugin/marketplace.json`, and install CE skills and agents as a complete plugin.
|
||||
|
||||
### Decision
|
||||
|
||||
Keep the custom CE OpenCode writer for now:
|
||||
|
||||
```text
|
||||
~/.config/opencode/opencode.json
|
||||
~/.config/opencode/skills/<skill>/SKILL.md
|
||||
~/.config/opencode/agents/<agent>.md
|
||||
~/.config/opencode/commands/*.md # source commands only, if present
|
||||
~/.config/opencode/plugins/*.ts
|
||||
~/.config/opencode/compound-engineering/install-manifest.json
|
||||
```
|
||||
|
||||
This matches OpenCode's documented global config root and lets CE convert the full Claude-authored payload: skills, agents, hooks/plugins, MCP config, and source commands if a plugin ships them. An npm OpenCode plugin could be useful later for hooks/tools, but it would not replace the need to place CE skills and agents into OpenCode's discovery roots unless OpenCode adds a richer package/install surface.
|
||||
|
||||
Avoid `~/.agents/skills` for CE-managed OpenCode installs for the same reason as Codex and Gemini: OpenCode can read that shared root, but Copilot can also read it and shadow native plugin skills.
|
||||
|
||||
### Cleanup
|
||||
|
||||
The OpenCode custom writer should continue to track and clean CE-owned files on every install:
|
||||
|
||||
- Old CE-owned `~/.config/opencode/skills/*`
|
||||
- Old CE-owned `~/.config/opencode/agents/*`
|
||||
- Old CE-owned `~/.config/opencode/commands/*`
|
||||
- Old CE-owned `~/.config/opencode/plugins/*`
|
||||
- Old CE-owned shared skills under `~/.agents/skills/*` from previous experiments or installs
|
||||
- Manifest-tracked files that disappeared because a skill, agent, or command was renamed or removed
|
||||
|
||||
## Pi
|
||||
|
||||
### Current Platform Facts
|
||||
|
||||
Pi supports file-based skills and package installs. Its package surface can bundle skills, prompts, extensions, and related package metadata, and `pi install` can install from package sources such as npm, git, URLs, or local paths.
|
||||
|
||||
Pi also has shared skill discovery through `~/.agents/skills` and `.agents/skills`, but CE should not use those shared roots for the same reason as OpenCode, Codex, and Gemini: Copilot can read shared personal/project skills before plugin skills, so a CE skill installed there for Pi could shadow Copilot's native plugin install.
|
||||
|
||||
CE's current Pi compatibility is not a raw Claude-compatible plugin install. The converter currently:
|
||||
|
||||
- Copies platform-compatible CE skills.
|
||||
- Converts Claude agents into generated Pi skills, because Pi does not provide a Claude-style plugin `agents/` runtime equivalent for this payload today.
|
||||
- Writes a `compound-engineering-compat.ts` extension that provides compatibility tools such as subagent invocation and MCPorter access.
|
||||
- Converts Claude MCP server config into `compound-engineering/mcporter.json` for MCPorter.
|
||||
- Writes source commands as prompts only if a source plugin ships commands.
|
||||
|
||||
### Decision
|
||||
|
||||
Keep the custom CE Pi writer for now:
|
||||
|
||||
```text
|
||||
~/.pi/agent/skills/<skill-name>/SKILL.md
|
||||
~/.pi/agent/prompts/*.md
|
||||
~/.pi/agent/extensions/compound-engineering-compat.ts
|
||||
~/.pi/agent/compound-engineering/mcporter.json
|
||||
~/.pi/agent/compound-engineering/install-manifest.json
|
||||
~/.pi/agent/AGENTS.md # CE-managed compatibility block
|
||||
```
|
||||
|
||||
This is a pragmatic install target, not the desired long-term distribution shape. The long-term direction should be a real Pi package that can be installed with `pi install`, but CE should not promote that as the primary path until we package and test the full payload: copied skills, generated agent skills, prompts, the compatibility extension, MCPorter config, and cleanup behavior.
|
||||
|
||||
Do not install CE Pi artifacts into `~/.agents/skills`.
|
||||
|
||||
### Cleanup
|
||||
|
||||
The Pi custom writer should continue to track and clean CE-owned files on every install:
|
||||
|
||||
- Old CE-owned `~/.pi/agent/skills/*`
|
||||
- Old CE-owned `~/.pi/agent/prompts/*`
|
||||
- Old CE-owned `~/.pi/agent/extensions/*`
|
||||
- Old generated agent-as-skill artifacts from prior CE installs
|
||||
- Manifest-tracked files that disappeared because a skill, prompt, generated agent skill, or extension was renamed or removed
|
||||
|
||||
Manual cleanup is also available:
|
||||
|
||||
```bash
|
||||
bunx @every-env/compound-plugin cleanup --target pi
|
||||
```
|
||||
|
||||
Future Pi package work should preserve the same cleanup semantics before switching users from the current custom writer to a native `pi install` package.
|
||||
|
||||
## Codex
|
||||
|
||||
### Current Platform Facts
|
||||
|
||||
Current Codex docs describe user skills under `~/.agents/skills` and repo skills under `.agents/skills`. Codex also reads admin skills from `/etc/codex/skills` and system skills bundled by OpenAI. Codex supports symlinked skill folders and follows symlink targets.
|
||||
|
||||
Empirical note: Codex also still discovers legacy `~/.codex/skills` entries. On 2026-04-18, we created the same skill name in both `~/.agents/skills/ce-duplicate-discovery-smoke` and `~/.codex/skills/ce-duplicate-discovery-smoke`; the Codex skill picker showed both entries.
|
||||
|
||||
Despite current Codex docs favoring `~/.agents/skills`, CE should not write there because those files can shadow Copilot's native plugin skills. CE should use the Codex-specific compatibility root:
|
||||
|
||||
```text
|
||||
~/.codex/skills/compound-engineering/<skill-name>/SKILL.md
|
||||
```
|
||||
|
||||
This shape keeps CE Codex skills isolated from Copilot/Gemini shared discovery roots while still giving Codex a namespaced skill pack.
|
||||
|
||||
Codex also has custom agents and a plugin model:
|
||||
|
||||
- Custom agents are standalone TOML files under `~/.codex/agents/` or `.codex/agents/`.
|
||||
- Each custom agent requires `name`, `description`, and `developer_instructions`.
|
||||
- Codex only spawns subagents when explicitly asked.
|
||||
|
||||
Codex plugins exist, but current public distribution is still local/personal:
|
||||
|
||||
- Repo marketplace: `$REPO_ROOT/.agents/plugins/marketplace.json`
|
||||
- Personal marketplace: `~/.agents/plugins/marketplace.json`
|
||||
- Typical personal plugin storage: `~/.codex/plugins/<plugin-name>`
|
||||
- Installed plugin cache: `~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/`
|
||||
- Official public plugin publishing is still marked as coming soon.
|
||||
|
||||
This means Codex has a plugin model, but not yet a Copilot-style "point at GitHub marketplace repo and install globally" distribution path that is good enough to replace our CE custom install for normal users.
|
||||
|
||||
### What Superpowers Does
|
||||
|
||||
Superpowers' Codex install guide is a skill-discovery install, not a Codex plugin install:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
|
||||
mkdir -p ~/.agents/skills
|
||||
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
|
||||
```
|
||||
|
||||
The real content lives under:
|
||||
|
||||
```text
|
||||
~/.codex/superpowers
|
||||
```
|
||||
|
||||
The discovery entry lives under:
|
||||
|
||||
```text
|
||||
~/.agents/skills/superpowers -> ~/.codex/superpowers/skills
|
||||
```
|
||||
|
||||
So `~/.codex/superpowers` is the backing store, and `~/.agents/skills/superpowers` is a symlink used to make Codex discover the skills. Their migration instructions also remove an old bootstrap block from `~/.codex/AGENTS.md`, which implies an earlier non-skill-discovery install path.
|
||||
|
||||
This is useful, but it has tradeoffs we should not copy blindly:
|
||||
|
||||
- It requires users to clone and update a Git repo manually.
|
||||
- It uses a namespaced subfolder under `~/.agents/skills`.
|
||||
- It is optimized for Codex, but `~/.agents/skills` can shadow Copilot native plugin skills.
|
||||
- It works for pass-through source skills, but CE's Codex target also generates target-specific artifacts from agents/commands, transforms content, writes prompt wrappers, and manages cleanup. A raw clone plus symlink would still need a generation/cleanup step unless we intentionally drop those converted artifacts.
|
||||
|
||||
The useful part to emulate is the idea of isolating a plugin's files under a named folder. The part to avoid is writing CE-owned files into `~/.agents/skills` or requiring a manual clone/update workflow for normal users.
|
||||
|
||||
### Subfolder Decision
|
||||
|
||||
Do not use `~/.agents/skills` for CE Codex installs. Even if Codex discovers it, Copilot also reads it and will let those skills shadow native plugin skills.
|
||||
|
||||
For CE's Codex target, use a Codex-specific namespaced folder:
|
||||
|
||||
```text
|
||||
~/.codex/skills/compound-engineering/<skill-name>/SKILL.md
|
||||
```
|
||||
|
||||
This is not the documented modern Codex skill path, so the implementation should keep a smoke test for current Codex discovery behavior. The tradeoff is intentional: we prefer a Codex-only compatibility path over writing to a shared root that breaks Copilot plugin isolation.
|
||||
|
||||
### Source-of-Truth Decision
|
||||
|
||||
For Codex, `~/.codex` is the durable source of truth for CE-owned Codex artifacts. Keep all generated Codex artifacts under Codex-owned roots and track them with a manifest:
|
||||
|
||||
```text
|
||||
~/.codex/skills/compound-engineering/<skill-name>/SKILL.md
|
||||
~/.codex/agents/compound-engineering/<agent-name>.toml
|
||||
~/.codex/compound-engineering/install-manifest.json
|
||||
```
|
||||
|
||||
Do not create symlinks from `~/.agents/skills` to these Codex-owned files.
|
||||
|
||||
### Intended CE Codex Plan
|
||||
|
||||
For now:
|
||||
|
||||
- Keep a custom CE Codex install path.
|
||||
- Run legacy cleanup on every custom Codex install.
|
||||
- Install generated/converted skills under `~/.codex/skills/compound-engineering/<skill-name>/SKILL.md`.
|
||||
- Convert Claude Markdown agents to Codex TOML custom agents under `~/.codex/agents/compound-engineering/<agent-name>.toml`.
|
||||
- Name converted agents with the source category and CE agent name, for example `review-ce-correctness-reviewer` or `research-ce-repo-research-analyst`, and rewrite skill orchestration text to spawn those names.
|
||||
- Track generated skills, prompts, and agents in `~/.codex/compound-engineering/install-manifest.json`.
|
||||
- Keep Codex-only artifacts under `~/.codex`, such as prompt wrappers, `config.toml` MCP entries, and Codex TOML custom agents.
|
||||
- Rewrite `Task`/agent references to spawn generated Codex custom agents when the referenced agent is known.
|
||||
- Track an install manifest so removed skills and renamed skills can be cleaned later.
|
||||
- Track historical CE artifacts from git history so old flat installs, prompt files, and converted-agent skills can be cleaned safely.
|
||||
|
||||
Do not require users to clone the CE repo for Codex. The CLI should continue to fetch/install from the package or branch source, then write the local Codex-compatible output.
|
||||
|
||||
### Smoke Test Result
|
||||
|
||||
On 2026-04-18, we verified the proposed Codex split with a local smoke test:
|
||||
|
||||
```text
|
||||
~/.agents/skills/ce-codex-agent-smoke/SKILL.md
|
||||
~/.codex/agents/ce-codex-agent-smoke.toml
|
||||
```
|
||||
|
||||
The skill explicitly asked Codex to spawn the `ce_codex_agent_smoke` custom agent. Codex discovered the skill, spawned the TOML custom agent, waited for completion, and returned the expected marker:
|
||||
|
||||
```text
|
||||
CODEX_TOML_AGENT_SMOKE_OK
|
||||
```
|
||||
|
||||
This confirms the intended CE Codex architecture is viable: workflow skills can invoke Claude-authored agents converted to Codex TOML custom agents in `~/.codex/agents`. The skill root should now be moved from the tested `~/.agents/skills` path to the isolated CE path under `~/.codex/skills/compound-engineering`.
|
||||
|
||||
On 2026-04-19, we also verified that Codex discovers nested TOML custom agents under:
|
||||
|
||||
```text
|
||||
~/.codex/agents/compound-engineering/<agent-name>.toml
|
||||
```
|
||||
|
||||
and accepts hyphenated TOML `name` values such as `ce-codex-hyphen-toml-smoke`. CE should therefore use the nested `compound-engineering` agent root for cleanup parity with `~/.codex/skills/compound-engineering/`.
|
||||
|
||||
We also tested Codex native plugin-bundled agents in three shapes:
|
||||
|
||||
```text
|
||||
plugins/<plugin>/agents/<agent>.toml
|
||||
plugins/<plugin>/.codex/agents/<agent>.toml
|
||||
plugins/<plugin>/.codex-plugin/plugin.json with "agents": "./agents/"
|
||||
```
|
||||
|
||||
All installed plugin skills loaded, but spawning the bundled custom agents failed with `unknown agent_type`. Codex native plugins are therefore not a sufficient CE install path for agent-heavy workflows yet.
|
||||
|
||||
On the same day, we verified duplicate discovery behavior by installing two skills with the same `name`:
|
||||
|
||||
```text
|
||||
~/.agents/skills/ce-duplicate-discovery-smoke/SKILL.md
|
||||
~/.codex/skills/ce-duplicate-discovery-smoke/SKILL.md
|
||||
```
|
||||
|
||||
Codex displayed both skill entries in the picker, one from `~/.agents/skills` and one from `~/.codex/skills`. This confirms that any old CE skills left in either root can cause visible duplicates. Cleanup must remove CE-owned stale skills from both `~/.agents/skills` and legacy flat `~/.codex/skills` before writing the namespaced `~/.codex/skills/compound-engineering` install.
|
||||
|
||||
Also on 2026-04-18, we tested nested skill discovery across Codex, Copilot, and Gemini with three shapes:
|
||||
|
||||
```text
|
||||
~/.agents/skills/ce-flat-discovery-smoke/SKILL.md
|
||||
~/.agents/skills/ce-nested-pack/ce-nested-discovery-smoke/SKILL.md
|
||||
~/.agents/skills/ce-symlink-pack -> ~/.agents/ce-discovery-packs/ce-symlink-pack/skills
|
||||
```
|
||||
|
||||
Results:
|
||||
|
||||
| Harness | Flat direct skill | Regular nested skill | Superpowers-style symlink pack |
|
||||
| --- | --- | --- | --- |
|
||||
| Codex | Worked | Worked | Worked |
|
||||
| Copilot CLI | Worked | Not found | Not found |
|
||||
| Gemini CLI | Worked | Not found | Not found |
|
||||
|
||||
Conclusion for shared skill roots: cross-harness `~/.agents/skills` installs only work portably when skills are direct children:
|
||||
|
||||
```text
|
||||
~/.agents/skills/<skill-name>/SKILL.md
|
||||
```
|
||||
|
||||
But CE should no longer install there because Copilot plugin skills can be shadowed by `~/.agents/skills`. Treat these results as cleanup/discovery context, not the target install shape.
|
||||
|
||||
### Future Codex Plugin Option
|
||||
|
||||
Codex now has a documented marketplace/plugin install path, including `codex marketplace add <source>`, but CE should not use it as the primary Codex install path yet because plugin-bundled custom agents did not register in testing.
|
||||
|
||||
Revisit Codex native plugins when Codex documents and supports plugin-bundled custom agents, or when the plugin installer can declare files that should be installed into the user's custom-agent roots.
|
||||
|
||||
Until then, Codex native plugins are useful for local development and testing skill-only packages, but not for CE's agent-heavy workflows.
|
||||
|
||||
## Gemini CLI
|
||||
|
||||
### Current Platform Facts
|
||||
|
||||
Gemini has two relevant install surfaces:
|
||||
|
||||
1. Shared/user skills:
|
||||
- Workspace skills: `.gemini/skills/` or `.agents/skills/`
|
||||
- User skills: `~/.gemini/skills/` or `~/.agents/skills/`
|
||||
- Extension skills bundled inside installed extensions
|
||||
2. Extensions:
|
||||
- Installed with `gemini extensions install <source>`
|
||||
- `<source>` can be a GitHub repository URL or a local path
|
||||
- Gemini copies the extension during installation
|
||||
- Installed extensions live under `~/.gemini/extensions`
|
||||
- `gemini extensions link <path>` symlinks a local development extension for immediate iteration
|
||||
|
||||
Gemini extension roots require `gemini-extension.json`. An extension can bundle:
|
||||
|
||||
- `skills/<skill-name>/SKILL.md`
|
||||
- `commands/*.toml`
|
||||
- `agents/*.md` for preview subagents
|
||||
- `GEMINI.md` context via `contextFileName`
|
||||
- MCP server config
|
||||
- hooks
|
||||
- policies
|
||||
- themes
|
||||
|
||||
For remote distribution and public gallery discovery, Gemini requires `gemini-extension.json` at the absolute root of the GitHub repository or release archive. `gemini extensions install <source>` accepts a GitHub repository URL or local path, but the documented and locally verified command does not include a monorepo `--path` option for extension installs.
|
||||
|
||||
Gemini subagents are Markdown files with YAML frontmatter. Local user/project agents are documented under:
|
||||
|
||||
```text
|
||||
~/.gemini/agents/*.md
|
||||
.gemini/agents/*.md
|
||||
```
|
||||
|
||||
Extension subagents are documented under:
|
||||
|
||||
```text
|
||||
<extension-root>/agents/*.md
|
||||
```
|
||||
|
||||
The shared `.agents/*` alias is documented for skills, not subagents.
|
||||
|
||||
Gemini CLI 0.38.2 implementation confirms this: user agents resolve to `~/.gemini/agents`, project agents resolve to `.gemini/agents`, while shared aliases exist only for skill directories (`~/.agents/skills` and `.agents/skills`). Do not use `~/.agents/agents` as a shared CE agent install root for Gemini.
|
||||
|
||||
### Discovery Test Result
|
||||
|
||||
On 2026-04-18, we tested Gemini shared skill discovery with three shapes:
|
||||
|
||||
```text
|
||||
~/.agents/skills/ce-flat-discovery-smoke/SKILL.md
|
||||
~/.agents/skills/ce-nested-pack/ce-nested-discovery-smoke/SKILL.md
|
||||
~/.agents/skills/ce-symlink-pack -> ~/.agents/ce-discovery-packs/ce-symlink-pack/skills
|
||||
```
|
||||
|
||||
Gemini discovered only the flat direct skill. It did not discover the regular nested skill or the Superpowers-style symlink pack.
|
||||
|
||||
If `~/.agents/skills` is used manually, Gemini-compatible skills must be direct children:
|
||||
|
||||
```text
|
||||
~/.agents/skills/<skill-name>/SKILL.md
|
||||
```
|
||||
|
||||
CE should not use that path for managed Gemini installs because it can shadow Copilot plugin skills.
|
||||
|
||||
### Intended CE Gemini Plan
|
||||
|
||||
For now, keep a custom CE Gemini install path and write directly to Gemini-owned roots:
|
||||
|
||||
```text
|
||||
~/.gemini/skills/<skill-name>/SKILL.md
|
||||
~/.gemini/agents/<agent-name>.md
|
||||
~/.gemini/commands/*.toml # source commands only, if present
|
||||
~/.gemini/compound-engineering/install-manifest.json
|
||||
```
|
||||
|
||||
The Gemini writer should copy pass-through skills to `~/.gemini/skills`, generate normalized flat Gemini subagents in `~/.gemini/agents`, and write command TOML files under `~/.gemini/commands` if CE ships commands again.
|
||||
|
||||
Gemini extension distribution is already supported. The CE blocker is packaging shape: our source repo is a multi-plugin repo and the CE plugin root is `plugins/compound-engineering/`, while Gemini extension installs expect `gemini-extension.json` at the extension source root. Current Gemini extension install does not support a documented monorepo `--path` flow.
|
||||
|
||||
Native Gemini extension packaging should become the preferred Gemini distribution path once CE ships one of these shapes:
|
||||
|
||||
- a generated extension root published as the repository or release archive root
|
||||
- a dedicated Gemini extension repository
|
||||
- a distribution branch whose root is the Gemini extension root
|
||||
|
||||
That extension root should be generated/normalized, not just the Claude plugin directory with `gemini-extension.json` added, because Gemini loads direct `agents/*.md` files and validates Gemini-shaped agent frontmatter.
|
||||
|
||||
Open questions to validate in implementation:
|
||||
|
||||
- Whether Gemini supports any undocumented repository subdirectory syntax for extensions. Current docs and local help only show whole GitHub repository URLs or local paths.
|
||||
- Whether Gemini preview subagents are enabled by default for all users or require settings in some versions/environments.
|
||||
- How Gemini extension subagent invocation names map from nested Claude agent paths.
|
||||
|
||||
### Cleanup
|
||||
|
||||
The Gemini custom writer must clean old CE-owned artifacts so users do not see duplicates or stale converted-agent skills.
|
||||
|
||||
Cleanup should cover:
|
||||
|
||||
- Old CE-owned `.gemini/skills/*`
|
||||
- Old CE-owned `.gemini/agents/*`
|
||||
- Old CE-owned `.gemini/commands/*`
|
||||
- Old CE-owned `~/.gemini/skills/*`
|
||||
- Old CE-owned `~/.gemini/agents/*`
|
||||
- Old CE-owned `~/.gemini/commands/*`
|
||||
- Any CE-owned flat shared skills under `~/.agents/skills/*` from older experiments or installs
|
||||
- Any future CE-owned extension install if we need to uninstall/reinstall a broken pre-release
|
||||
|
||||
## Sources
|
||||
|
||||
- Claude/Copilot marketplace metadata: `.claude-plugin/marketplace.json`
|
||||
- Cursor marketplace metadata: `.cursor-plugin/marketplace.json`
|
||||
- Claude plugin manifest: `plugins/compound-engineering/.claude-plugin/plugin.json`
|
||||
- Cursor plugin manifest: `plugins/compound-engineering/.cursor-plugin/plugin.json`
|
||||
- Copilot plugin reference: `https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference`
|
||||
- Copilot CLI plugins overview: `https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-cli-plugins`
|
||||
- Factory Droid plugin configuration: `https://docs.factory.ai/cli/configuration/plugins`
|
||||
- Factory Droid plugin build guide: `https://docs.factory.ai/guides/building/building-plugins`
|
||||
- OpenCode config: `https://opencode.ai/docs/config/`
|
||||
- OpenCode skills: `https://opencode.ai/docs/skills`
|
||||
- OpenCode agents: `https://opencode.ai/docs/agents/`
|
||||
- OpenCode commands: `https://opencode.ai/docs/commands/`
|
||||
- OpenCode plugins: `https://opencode.ai/docs/plugins/`
|
||||
- Pi overview: `https://buildwithpi.ai/README.md`
|
||||
- Pi skills/packages: `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`
|
||||
- Codex skills: `https://developers.openai.com/codex/skills`
|
||||
- Codex plugin build/distribution docs: `https://developers.openai.com/codex/plugins/build`
|
||||
- Superpowers Codex install guide: `https://github.com/obra/superpowers/blob/main/.codex/INSTALL.md`
|
||||
- Gemini extension reference: `https://geminicli.com/docs/extensions/reference/`
|
||||
- Gemini extension build guide: `https://geminicli.com/docs/extensions/writing-extensions/`
|
||||
- Gemini skills: `https://geminicli.com/docs/cli/skills/`
|
||||
- Gemini subagents: `https://geminicli.com/docs/core/subagents/`
|
||||
- Gemini subagents announcement: `https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/`
|
||||
@@ -1,6 +1,6 @@
|
||||
# Codex Spec (Config, Prompts, Skills, MCP)
|
||||
# Codex Spec (Config, Prompts, Skills, Subagents, MCP)
|
||||
|
||||
Last verified: 2026-01-21
|
||||
Last verified: 2026-04-19
|
||||
|
||||
## Primary sources
|
||||
|
||||
@@ -10,6 +10,7 @@ https://developers.openai.com/codex/config-advanced
|
||||
https://developers.openai.com/codex/custom-prompts
|
||||
https://developers.openai.com/codex/skills
|
||||
https://developers.openai.com/codex/skills/create-skill
|
||||
https://developers.openai.com/codex/subagents
|
||||
https://developers.openai.com/codex/guides/agents-md
|
||||
https://developers.openai.com/codex/mcp
|
||||
```
|
||||
@@ -49,10 +50,28 @@ https://developers.openai.com/codex/mcp
|
||||
- Required fields are single-line with length limits (name ≤ 100 chars, description ≤ 500 chars). citeturn3view4
|
||||
- At startup, Codex loads only each skill’s name/description; full content is injected when invoked. citeturn3view3turn3view4
|
||||
- Skills can be repo-scoped in `.agents/skills/` and are discovered from the current working directory up to the repository root. User-scoped skills live in `~/.agents/skills/`. citeturn1view1turn1view4
|
||||
- Inference: some existing tooling and user setups still use `.codex/skills/` and `~/.codex/skills/` as legacy compatibility paths, but those locations are not documented in the current OpenAI Codex skills docs linked above.
|
||||
- Inference: some existing tooling and user setups still use `.codex/skills/` and `~/.codex/skills/` as compatibility paths, but those locations are not documented in the current OpenAI Codex skills docs linked above.
|
||||
- Compound Engineering should avoid `~/.agents/skills` for managed installs because that shared root can shadow Copilot's native plugin skills. Use the Codex-specific compatibility root `~/.codex/skills/compound-engineering/<skill-name>/SKILL.md` for CE Codex skills, and track generated files with a CE manifest.
|
||||
- Codex also supports admin-scoped skills in `/etc/codex/skills` plus built-in system skills bundled with Codex. citeturn1view4
|
||||
- Skills can be invoked explicitly using `/skills` or `$skill-name`. citeturn3view3
|
||||
|
||||
## Subagents and custom agents
|
||||
|
||||
- Codex subagent workflows are enabled by default in current releases.
|
||||
- Codex only spawns subagents when explicitly asked.
|
||||
- Custom agent files are standalone TOML files under `~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped agents.
|
||||
- Each TOML file defines one custom agent. Required fields:
|
||||
- `name`
|
||||
- `description`
|
||||
- `developer_instructions`
|
||||
- Optional fields can include `nickname_candidates`, `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`.
|
||||
- The TOML `name` field is the source of truth; matching the filename to the agent name is only a convention.
|
||||
- CE converts Claude Markdown agents into Codex custom-agent TOML files under `~/.codex/agents/compound-engineering/`.
|
||||
- CE keeps generated agents under `~/.codex/agents`, not `~/.agents/skills`, because `~/.agents` is shared across harnesses and can shadow native plugin installs.
|
||||
- Generated TOML agent names preserve CE's hyphenated naming and include the source category, such as `review-ce-correctness-reviewer` and `research-ce-repo-research-analyst`.
|
||||
- Empirical test on 2026-04-19 confirmed Codex discovers nested custom-agent TOML files under `~/.codex/agents/compound-engineering/` and accepts hyphenated TOML `name` values.
|
||||
- Empirical plugin test on 2026-04-19 found Codex native plugins did not register custom agents bundled under plugin-local `agents/`, plugin-local `.codex/agents/`, or an undocumented plugin manifest `agents` field. Therefore CE still needs the custom Bun Codex installer for agent-heavy workflows.
|
||||
|
||||
## MCP (Model Context Protocol)
|
||||
|
||||
- MCP configuration lives in `~/.codex/config.toml` and is shared by the CLI and IDE extension. citeturn3view2turn3view5
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Cursor Spec (Rules, Commands, Skills, MCP)
|
||||
# Cursor Spec (Plugin Marketplace, Rules, Commands, Skills, MCP)
|
||||
|
||||
Last verified: 2026-02-12
|
||||
|
||||
@@ -10,6 +10,27 @@ https://docs.cursor.com/context/rules-for-ai
|
||||
https://docs.cursor.com/customize/model-context-protocol
|
||||
```
|
||||
|
||||
## Plugin Marketplace
|
||||
|
||||
Compound Engineering is published through the Cursor Plugin Marketplace.
|
||||
|
||||
In Cursor Agent chat, install with:
|
||||
|
||||
```text
|
||||
/add-plugin compound-engineering
|
||||
```
|
||||
|
||||
Users can also search for "compound engineering" in the plugin marketplace.
|
||||
|
||||
The repo-owned marketplace files are:
|
||||
|
||||
```text
|
||||
.cursor-plugin/marketplace.json
|
||||
plugins/compound-engineering/.cursor-plugin/plugin.json
|
||||
```
|
||||
|
||||
Do not use the old custom Bun converter/install path for Cursor.
|
||||
|
||||
## Config locations
|
||||
|
||||
| Scope | Path |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Gemini CLI Spec (GEMINI.md, Commands, Skills, MCP, Settings)
|
||||
# Gemini CLI Spec (GEMINI.md, Commands, Skills, Subagents, Extensions)
|
||||
|
||||
Last verified: 2026-02-14
|
||||
Last verified: 2026-04-18
|
||||
|
||||
## Primary sources
|
||||
|
||||
@@ -10,7 +10,9 @@ https://geminicli.com/docs/get-started/configuration/
|
||||
https://geminicli.com/docs/cli/custom-commands/
|
||||
https://geminicli.com/docs/cli/skills/
|
||||
https://geminicli.com/docs/cli/creating-skills/
|
||||
https://geminicli.com/docs/extensions/writing-extensions/
|
||||
https://geminicli.com/docs/core/subagents/
|
||||
https://geminicli.com/docs/extensions/reference/
|
||||
https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/
|
||||
https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html
|
||||
```
|
||||
|
||||
@@ -53,7 +55,10 @@ User request: {{args}}
|
||||
## Skills (SKILL.md standard)
|
||||
|
||||
- A skill is a folder containing `SKILL.md` plus optional supporting files.
|
||||
- Skills live in `.gemini/skills/`.
|
||||
- Workspace skills live in `.gemini/skills/` or the `.agents/skills/` alias.
|
||||
- User skills live in `~/.gemini/skills/` or the `~/.agents/skills/` alias.
|
||||
- Extension skills live in an installed extension's `skills/` directory.
|
||||
- Compound Engineering managed Gemini installs should use Gemini-owned roots (`~/.gemini/skills`, `~/.gemini/agents`, `~/.gemini/commands`) rather than `~/.agents/skills`, because `~/.agents/skills` can shadow Copilot plugin skills.
|
||||
- `SKILL.md` uses YAML frontmatter with `name` and `description` fields.
|
||||
- Gemini activates skills on demand via `activate_skill` tool based on description matching.
|
||||
- The `description` field is critical — Gemini uses it to decide when to activate the skill.
|
||||
@@ -71,6 +76,34 @@ description: Review code for security vulnerabilities and OWASP compliance
|
||||
Detailed instructions for security review...
|
||||
```
|
||||
|
||||
## Subagents
|
||||
|
||||
- Gemini CLI supports custom subagents as Markdown files with YAML frontmatter.
|
||||
- Project subagents live in `.gemini/agents/*.md`.
|
||||
- User subagents live in `~/.gemini/agents/*.md`.
|
||||
- Extension subagents live in an installed extension's `agents/*.md` directory.
|
||||
- Current Gemini docs, `/agents reload` command text, and Gemini CLI 0.38.2 implementation name only `.gemini/agents` and `~/.gemini/agents` for local subagent discovery. The `.agents/skills` and `~/.agents/skills` aliases apply to skills; Gemini does not currently read `~/.agents/agents` or `.agents/agents` as subagent discovery paths.
|
||||
- Subagents can be invoked explicitly with `@agent-name` or selected automatically by description.
|
||||
- Subagents run in isolated context loops and can have restricted tool access.
|
||||
- Subagents cannot call other subagents, even if granted wildcard tool access.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: security-auditor
|
||||
description: Specialized in finding security vulnerabilities in code.
|
||||
kind: local
|
||||
tools:
|
||||
- read_file
|
||||
- grep_search
|
||||
model: inherit
|
||||
max_turns: 10
|
||||
---
|
||||
|
||||
You are a ruthless Security Auditor.
|
||||
```
|
||||
|
||||
## MCP server configuration
|
||||
|
||||
- MCP servers are configured in `settings.json` under the `mcpServers` key.
|
||||
@@ -103,8 +136,147 @@ Detailed instructions for security review...
|
||||
## Extensions
|
||||
|
||||
- Extensions are distributable packages for Gemini CLI.
|
||||
- They extend functionality with custom tools, hooks, and commands.
|
||||
- Not used for plugin conversion (different purpose from Claude Code plugins).
|
||||
- Install with `gemini extensions install <github-url-or-local-path>`.
|
||||
- Unlike `gemini skills install`, current Gemini extension docs and local `gemini extensions install --help` output do not list a `--path` flag for installing an extension from a monorepo subdirectory.
|
||||
- Remote extension installs are not local-only. Gemini supports Git repository distribution and GitHub Releases.
|
||||
- For public gallery discovery and normal remote install, `gemini-extension.json` must be at the absolute root of the GitHub repository or release archive.
|
||||
- Gemini CLI copies installed extensions under `~/.gemini/extensions`.
|
||||
- `gemini extensions link <path>` creates a symlink for local development instead of copying the extension.
|
||||
- Extension management commands run from the shell, not inside Gemini's interactive mode. Restart the Gemini session after install/update for commands and extension changes to take effect.
|
||||
- Extensions can bundle commands, skills, subagents, hooks, MCP servers, context files, policies, settings, and themes.
|
||||
- Every extension root must contain `gemini-extension.json`.
|
||||
- Extension commands live in `commands/*.toml`.
|
||||
- Extension skills live in `skills/<name>/SKILL.md`.
|
||||
- Extension subagents live in `agents/*.md`.
|
||||
- For Compound Engineering, native extension packaging is now the likely primary Gemini distribution path because it can preserve commands, skills, and subagents. Direct `.gemini/` writes should be treated as a legacy/custom install path unless retained for local development.
|
||||
- Because this repo is a monorepo with the plugin under `plugins/compound-engineering/`, public Gemini extension distribution likely needs a generated extension-root source, a dedicated extension repo, or a distribution branch whose root is the Gemini extension root.
|
||||
- Interim CE distribution should keep using the Bun installer, but change the writer to install into `~/.gemini/{skills,agents,commands}` with a manifest under `~/.gemini/compound-engineering`.
|
||||
|
||||
### Extension root shape
|
||||
|
||||
A distributable Gemini extension source should look like:
|
||||
|
||||
```text
|
||||
gemini-extension.json
|
||||
GEMINI.md # optional context file
|
||||
skills/<skill-name>/SKILL.md
|
||||
commands/<command>.toml
|
||||
agents/<agent-name>.md
|
||||
hooks/hooks.json # optional
|
||||
policies/*.toml # optional
|
||||
package.json # optional, if the extension has runtime code
|
||||
```
|
||||
|
||||
Minimal manifest:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "compound-engineering",
|
||||
"version": "1.0.0",
|
||||
"description": "Compound Engineering workflows for Gemini CLI",
|
||||
"contextFileName": "GEMINI.md"
|
||||
}
|
||||
```
|
||||
|
||||
Relevant manifest fields:
|
||||
|
||||
- `name`: Required. Local CLI validation allows letters, numbers, and dashes; docs recommend lowercase numbers/dashes and expect the extension directory name to match.
|
||||
- `version`: Required. Validation warns if it is not standard semver.
|
||||
- `description`: Optional but used by the public gallery.
|
||||
- `contextFileName`: Optional. Defaults to `GEMINI.md` when present.
|
||||
- `mcpServers`: Optional. Loaded like user `settings.json` MCP servers, except `trust` is ignored for extension MCP config.
|
||||
- `settings`: Optional install-time/user configuration prompts; values are stored in extension `.env` or keychain for sensitive values.
|
||||
- `excludeTools`, `migratedTo`, `plan`, `themes`: Optional target-specific behavior.
|
||||
|
||||
### Install commands
|
||||
|
||||
Install from a GitHub repository whose root is the extension root:
|
||||
|
||||
```bash
|
||||
gemini extensions install https://github.com/EveryInc/compound-engineering-gemini
|
||||
```
|
||||
|
||||
Install from a branch, tag, or commit:
|
||||
|
||||
```bash
|
||||
gemini extensions install https://github.com/EveryInc/compound-engineering-gemini --ref stable
|
||||
```
|
||||
|
||||
Install from a local extension root:
|
||||
|
||||
```bash
|
||||
gemini extensions install ./dist/gemini-extension
|
||||
```
|
||||
|
||||
Link a local extension root for development:
|
||||
|
||||
```bash
|
||||
gemini extensions link ./dist/gemini-extension
|
||||
```
|
||||
|
||||
Validate a local extension root:
|
||||
|
||||
```bash
|
||||
gemini extensions validate ./dist/gemini-extension
|
||||
```
|
||||
|
||||
Uninstall:
|
||||
|
||||
```bash
|
||||
gemini extensions uninstall compound-engineering
|
||||
```
|
||||
|
||||
### Release options
|
||||
|
||||
Gemini supports two remote release shapes:
|
||||
|
||||
1. **Git repository:** Users install the repository URL. The repository root must contain `gemini-extension.json`.
|
||||
2. **GitHub Releases:** Users still install the repository URL. Gemini can use the latest release archive or a release tag via `--ref`; custom archives must be self-contained with `gemini-extension.json` at the archive root.
|
||||
|
||||
The public Gemini extension gallery indexes public GitHub repositories with the `gemini-cli-extension` topic when `gemini-extension.json` is at the repository or release archive root.
|
||||
|
||||
### Compound Engineering packaging implications
|
||||
|
||||
The current `plugins/compound-engineering/` source root is not currently a valid Gemini extension root because it lacks `gemini-extension.json`:
|
||||
|
||||
```bash
|
||||
gemini extensions validate plugins/compound-engineering
|
||||
# Configuration file not found at .../plugins/compound-engineering/gemini-extension.json
|
||||
```
|
||||
|
||||
Adding only that manifest would make the root validate, but it would not be enough for correct agent packaging:
|
||||
|
||||
- CE agents currently live in nested category directories such as `agents/review/correctness-reviewer.md`.
|
||||
- Gemini's local loader in `@google/gemini-cli` 0.38.2 reads only direct `*.md` files under the extension `agents/` directory.
|
||||
- Gemini agent frontmatter is strict. CE's Claude-authored agent frontmatter can include Claude-only fields such as `color`, and some files use Claude string-form `tools: Read, Grep, Glob, Bash`; Gemini expects `tools` to be an array of valid Gemini tool names.
|
||||
|
||||
Therefore a proper CE Gemini extension should be generated or normalized, not just the Claude plugin root plus a manifest. This does not mean rewriting agent prompts into bespoke Gemini-only instructions. The agent bodies and most `name`/`description`/`model` frontmatter can usually pass through. The generated extension should:
|
||||
|
||||
- Copy pass-through `skills/<skill>/SKILL.md` directories that are not excluded for Gemini.
|
||||
- Convert Claude agents into flat Gemini-compatible subagents under `agents/<agent-name>.md`.
|
||||
- Strip or translate Claude-only frontmatter fields.
|
||||
- Convert Claude tool names to Gemini tool names, or omit tools when there is no reliable mapping.
|
||||
- Generate Gemini `commands/*.toml` only if CE ships source commands again.
|
||||
- Include a `gemini-extension.json` at the generated extension root.
|
||||
- Use `gemini extensions validate <generated-root>` in tests.
|
||||
|
||||
The same normalization is needed for the interim Bun installer, except the output root is `~/.gemini` instead of an extension root:
|
||||
|
||||
```text
|
||||
~/.gemini/skills/<skill-name>/SKILL.md
|
||||
~/.gemini/agents/<agent-name>.md
|
||||
~/.gemini/commands/*.toml
|
||||
~/.gemini/compound-engineering/install-manifest.json
|
||||
```
|
||||
|
||||
Local smoke test on 2026-04-18 with Gemini CLI 0.38.2:
|
||||
|
||||
- A direct extension agent using CE/Claude-style `tools: Read, Grep, Glob, Bash` plus `color: blue` failed to load with Gemini validation errors: `tools: Expected array, received string` and `Unrecognized key(s) in object: 'color'`.
|
||||
- A nested extension agent under `agents/review/nested-agent.md` produced no validation error because the loader only scans direct files under `agents/`; it was not discovered.
|
||||
|
||||
Do not place CE agents in `~/.agents/agents` as a shared cross-harness agent root. Gemini does not currently read it, and if Gemini adds that alias later, Claude/Copilot-shaped frontmatter could become a compatibility problem. For Gemini, use either a native extension with normalized `agents/*.md` files or a legacy/custom install under `~/.gemini/agents` with cleanup.
|
||||
|
||||
If the same Gemini agent name exists in multiple Gemini-read locations, Gemini registers user agents first, project agents next, and extension agents last. Later registrations override earlier ones by name. This avoids duplicate visible agent tools, but stale CE files in `~/.gemini/agents` can still emit validation errors or mask behavior when an extension is disabled, so cleanup remains necessary.
|
||||
|
||||
## Settings.json structure
|
||||
|
||||
|
||||
@@ -1,57 +1,92 @@
|
||||
# OpenCode Spec (Config, Agents, Plugins)
|
||||
|
||||
Last verified: 2026-01-21
|
||||
Last verified: 2026-04-19
|
||||
|
||||
## Primary sources
|
||||
|
||||
```
|
||||
https://opencode.ai/docs/config
|
||||
https://opencode.ai/docs/config/
|
||||
https://opencode.ai/docs/tools
|
||||
https://opencode.ai/docs/permissions
|
||||
https://opencode.ai/docs/plugins/
|
||||
https://opencode.ai/docs/agents/
|
||||
https://opencode.ai/docs/commands/
|
||||
https://opencode.ai/docs/skills
|
||||
https://opencode.ai/config.json
|
||||
```
|
||||
|
||||
## Config files and precedence
|
||||
|
||||
- OpenCode supports JSON and JSONC configs. citeturn10view0
|
||||
- Config sources are merged (not replaced), with a defined precedence order from remote → global → custom → project → `.opencode` directories → inline overrides. citeturn10view0
|
||||
- Global config is stored at `~/.config/opencode/opencode.json`, and project config is `opencode.json` in the project root. citeturn10view0
|
||||
- Custom config file and directory can be provided via `OPENCODE_CONFIG` and `OPENCODE_CONFIG_DIR`. citeturn10view0
|
||||
- The `.opencode` and `~/.config/opencode` directories use plural subdirectory names (`agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`, `themes/`), but singular names are also supported for backwards compatibility. citeturn10view0
|
||||
- OpenCode supports JSON and JSONC configs.
|
||||
- Config sources are merged rather than replaced, with global and project config both participating in the final config.
|
||||
- Global config is stored at `~/.config/opencode/opencode.json`, and project config is `opencode.json` in the project root.
|
||||
- Custom config file and directory can be provided via `OPENCODE_CONFIG` and `OPENCODE_CONFIG_DIR`.
|
||||
- The `.opencode` and `~/.config/opencode` directories use plural subdirectory names (`agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`, `themes/`).
|
||||
|
||||
## Core config keys
|
||||
|
||||
- `model` and `small_model` set the primary and lightweight models; `provider` configures provider options. citeturn10view0
|
||||
- `tools` is still supported but deprecated; permissions are now the canonical control surface. citeturn1search0
|
||||
- `permission` controls tool approvals and can be configured globally or per tool, including pattern-based rules. citeturn1search0
|
||||
- `mcp`, `instructions`, and `disabled_providers` are supported config sections. citeturn1search5
|
||||
- `plugin` can list npm packages to load at startup. citeturn1search2
|
||||
- `model` and `small_model` set the primary and lightweight models; `provider` configures provider options.
|
||||
- `tools` is still supported but deprecated as of OpenCode v1.1.1; permissions are now the canonical control surface.
|
||||
- `permission` controls tool approvals and can be configured globally or per tool, including pattern-based rules.
|
||||
- `mcp`, `instructions`, `disabled_providers`, `enabled_providers`, and `plugin` are supported config sections.
|
||||
- `plugin` can list npm packages to load at startup.
|
||||
- `skills.paths` and `skills.urls` can add extra skill discovery locations, but CE should not depend on them until the layout is smoke-tested locally with OpenCode.
|
||||
|
||||
## Tools
|
||||
|
||||
- OpenCode ships with built-in tools, and permissions determine whether each tool runs automatically, requires approval, or is denied. citeturn1search3turn1search0
|
||||
- Tools are enabled by default; permissions provide the gating mechanism. citeturn1search3
|
||||
- OpenCode ships with built-in tools, and permissions determine whether each tool runs automatically, requires approval, or is denied.
|
||||
- Tools are enabled by default; permissions provide the gating mechanism.
|
||||
|
||||
## Permissions
|
||||
|
||||
- Permissions resolve to `allow`, `ask`, or `deny` and can be configured globally or per tool, with pattern-based rules. citeturn1search0
|
||||
- Defaults are permissive, with special cases such as `.env` file reads. citeturn1search0
|
||||
- Agent-level permissions override the global permission block. citeturn1search1turn1search0
|
||||
- Permissions resolve to `allow`, `ask`, or `deny` and can be configured globally or per tool, with pattern-based rules.
|
||||
- Defaults are permissive, with special cases such as `.env` file reads.
|
||||
- Agent-level permissions override the global permission block.
|
||||
|
||||
## Agents
|
||||
|
||||
- Agents can be configured in `opencode.json` or as markdown files in `~/.config/opencode/agents/` or `.opencode/agents/`. citeturn1search1turn10view0
|
||||
- Agent config supports `mode`, `model`, `temperature`, `tools`, and `permission`, and agent configs override global settings. citeturn1search1
|
||||
- Model IDs use the `provider/model-id` format. citeturn1search1
|
||||
- Agents can be configured in `opencode.json` or as markdown files in `~/.config/opencode/agents/` or `.opencode/agents/`.
|
||||
- Agent config supports `mode`, `model`, `variant`, `temperature`, `top_p`, `hidden`, `steps`, `options`, `permission`, and other schema fields. `tools` still exists but is deprecated.
|
||||
- `mode` can be `primary`, `subagent`, or `all`; omitted mode defaults to `all`.
|
||||
- `hidden: true` hides subagents from the `@` autocomplete menu.
|
||||
- `permission.task` controls which subagents an agent may invoke.
|
||||
- Model IDs use the `provider/model-id` format.
|
||||
|
||||
## Skills
|
||||
|
||||
- Skills are reusable `SKILL.md` definitions loaded on demand through OpenCode's native `skill` tool.
|
||||
- OpenCode searches direct child skill directories in its built-in roots:
|
||||
- `.opencode/skills/<name>/SKILL.md`
|
||||
- `~/.config/opencode/skills/<name>/SKILL.md`
|
||||
- `.claude/skills/<name>/SKILL.md`
|
||||
- `~/.claude/skills/<name>/SKILL.md`
|
||||
- `.agents/skills/<name>/SKILL.md`
|
||||
- `~/.agents/skills/<name>/SKILL.md`
|
||||
- The config schema also exposes `skills.paths` and `skills.urls` for extra skill sources. Do not switch CE to those until tested against a local OpenCode install; direct `~/.config/opencode/skills/<name>/SKILL.md` remains the stable writer shape.
|
||||
- Skill frontmatter recognizes `name`, `description`, `license`, `compatibility`, and `metadata`; unknown fields are ignored.
|
||||
- Skill names must be lowercase alphanumeric with single hyphen separators and must match the directory name.
|
||||
|
||||
## Commands
|
||||
|
||||
- Commands can be configured in `opencode.json` or as Markdown files in `~/.config/opencode/commands/` or `.opencode/commands/`.
|
||||
- Markdown command frontmatter can include fields such as `description`, `agent`, `model`, and `subtask`; the body becomes the prompt template.
|
||||
- If a command targets an agent whose mode is `subagent`, OpenCode invokes it as a subagent by default. `subtask: true` can force subagent invocation.
|
||||
|
||||
## Plugins and events
|
||||
|
||||
- Local plugins are loaded from `.opencode/plugin/` (project) and `~/.config/opencode/plugin/` (global). npm plugins can be listed in `plugin` in `opencode.json`. citeturn1search2
|
||||
- Plugins are loaded in a defined order across config and plugin directories. citeturn1search2
|
||||
- Plugins export a function that returns a map of event handlers; the plugins doc lists supported event categories. citeturn1search2
|
||||
- Local plugins are loaded from `.opencode/plugins/` and `~/.config/opencode/plugins/`. npm plugins can be listed in `plugin` in `opencode.json`.
|
||||
- Plugins are JavaScript/TypeScript modules. Each exported plugin function receives OpenCode context and returns hooks/event handlers.
|
||||
- Local plugins and custom tools can use npm dependencies declared in a `package.json` in the OpenCode config directory; OpenCode runs `bun install` at startup.
|
||||
|
||||
## Notes for this repository
|
||||
|
||||
- Config docs describe plural subdirectory names, while the plugins doc uses `.opencode/plugin/`. This implies singular paths remain accepted for backwards compatibility, but plural paths are the canonical structure. citeturn10view0turn1search2
|
||||
- The current documented global CE install root should stay `~/.config/opencode`, not `~/.agents`, to avoid conflicts with harnesses that also read `~/.agents`.
|
||||
- The current CE writer shape is still appropriate in April 2026:
|
||||
- `~/.config/opencode/opencode.json`
|
||||
- `~/.config/opencode/agents/*.md`
|
||||
- `~/.config/opencode/commands/*.md` only when a source plugin ships commands
|
||||
- `~/.config/opencode/plugins/*.ts`
|
||||
- `~/.config/opencode/skills/*/SKILL.md`
|
||||
- OpenCode's plugin system is useful for JS/TS hooks and custom tools, but current docs do not describe a native marketplace command that consumes CE's `.claude-plugin/marketplace.json` and installs the full skills/agents/commands payload.
|
||||
- Keep the custom Bun writer until OpenCode documents a native distribution path for packaged skills and agents.
|
||||
- The `compound-engineering` plugin currently emits skills and subagent Markdown files for OpenCode. It should not emit deprecated `tools` config; permission config is enough for non-default permission modes.
|
||||
|
||||
@@ -1,477 +0,0 @@
|
||||
# Windsurf Editor Global Configuration Guide
|
||||
|
||||
> **Purpose**: Technical reference for programmatically creating and managing Windsurf's global Skills, Workflows, and Rules.
|
||||
>
|
||||
> **Source**: Official Windsurf documentation at [docs.windsurf.com](https://docs.windsurf.com) + local file analysis.
|
||||
>
|
||||
> **Last Updated**: February 2026
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Base Directory Structure](#base-directory-structure)
|
||||
3. [Skills](#skills)
|
||||
4. [Workflows](#workflows)
|
||||
5. [Rules](#rules)
|
||||
6. [Memories](#memories)
|
||||
7. [System-Level Configuration (Enterprise)](#system-level-configuration-enterprise)
|
||||
8. [Programmatic Creation Reference](#programmatic-creation-reference)
|
||||
9. [Best Practices](#best-practices)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Windsurf provides three main customization mechanisms:
|
||||
|
||||
| Feature | Purpose | Invocation |
|
||||
|---------|---------|------------|
|
||||
| **Skills** | Complex multi-step tasks with supporting resources | Automatic (progressive disclosure) or `@skill-name` |
|
||||
| **Workflows** | Reusable step-by-step procedures | Slash command `/workflow-name` |
|
||||
| **Rules** | Behavioral guidelines and preferences | Trigger-based (always-on, glob, manual, or model decision) |
|
||||
|
||||
All three support both **workspace-level** (project-specific) and **global** (user-wide) scopes.
|
||||
|
||||
---
|
||||
|
||||
## Base Directory Structure
|
||||
|
||||
### Global Configuration Root
|
||||
|
||||
| OS | Path |
|
||||
|----|------|
|
||||
| **Windows** | `C:\Users\{USERNAME}\.codeium\windsurf\` |
|
||||
| **macOS** | `~/.codeium/windsurf/` |
|
||||
| **Linux** | `~/.codeium/windsurf/` |
|
||||
|
||||
### Directory Layout
|
||||
|
||||
```
|
||||
~/.codeium/windsurf/
|
||||
├── skills/ # Global skills (directories)
|
||||
│ └── {skill-name}/
|
||||
│ └── SKILL.md
|
||||
├── global_workflows/ # Global workflows (flat .md files)
|
||||
│ └── {workflow-name}.md
|
||||
├── rules/ # Global rules (flat .md files)
|
||||
│ └── {rule-name}.md
|
||||
├── memories/
|
||||
│ ├── global_rules.md # Always-on global rules (plain text)
|
||||
│ └── *.pb # Auto-generated memories (protobuf)
|
||||
├── mcp_config.json # MCP server configuration
|
||||
└── user_settings.pb # User settings (protobuf)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skills
|
||||
|
||||
Skills bundle instructions with supporting resources for complex, multi-step tasks. Cascade uses **progressive disclosure** to automatically invoke skills when relevant.
|
||||
|
||||
### Storage Locations
|
||||
|
||||
| Scope | Location |
|
||||
|-------|----------|
|
||||
| **Global** | `~/.codeium/windsurf/skills/{skill-name}/SKILL.md` |
|
||||
| **Workspace** | `.windsurf/skills/{skill-name}/SKILL.md` |
|
||||
|
||||
### Directory Structure
|
||||
|
||||
Each skill is a **directory** (not a single file) containing:
|
||||
|
||||
```
|
||||
{skill-name}/
|
||||
├── SKILL.md # Required: Main skill definition
|
||||
├── references/ # Optional: Reference documentation
|
||||
├── assets/ # Optional: Images, diagrams, etc.
|
||||
├── scripts/ # Optional: Helper scripts
|
||||
└── {any-other-files} # Optional: Templates, configs, etc.
|
||||
```
|
||||
|
||||
### SKILL.md Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: Brief description shown to model to help it decide when to invoke the skill
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
Instructions for the skill go here in markdown format.
|
||||
|
||||
## Section 1
|
||||
Step-by-step guidance...
|
||||
|
||||
## Section 2
|
||||
Reference supporting files using relative paths:
|
||||
- See [deployment-checklist.md](./deployment-checklist.md)
|
||||
- Run script: [deploy.sh](./scripts/deploy.sh)
|
||||
```
|
||||
|
||||
### Required YAML Frontmatter Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | **Yes** | Unique identifier (lowercase letters, numbers, hyphens only). Must match directory name. |
|
||||
| `description` | **Yes** | Explains what the skill does and when to use it. Critical for automatic invocation. |
|
||||
|
||||
### Naming Convention
|
||||
|
||||
- Use **lowercase-kebab-case**: `deploy-to-staging`, `code-review`, `setup-dev-environment`
|
||||
- Name must match the directory name exactly
|
||||
|
||||
### Invocation Methods
|
||||
|
||||
1. **Automatic**: Cascade automatically invokes when request matches skill description
|
||||
2. **Manual**: Type `@skill-name` in Cascade input
|
||||
|
||||
### Example: Complete Skill
|
||||
|
||||
```
|
||||
~/.codeium/windsurf/skills/deploy-to-production/
|
||||
├── SKILL.md
|
||||
├── deployment-checklist.md
|
||||
├── rollback-procedure.md
|
||||
└── config-template.yaml
|
||||
```
|
||||
|
||||
**SKILL.md:**
|
||||
```markdown
|
||||
---
|
||||
name: deploy-to-production
|
||||
description: Guides the deployment process to production with safety checks. Use when deploying to prod, releasing, or pushing to production environment.
|
||||
---
|
||||
|
||||
## Pre-deployment Checklist
|
||||
1. Run all tests
|
||||
2. Check for uncommitted changes
|
||||
3. Verify environment variables
|
||||
|
||||
## Deployment Steps
|
||||
Follow these steps to deploy safely...
|
||||
|
||||
See [deployment-checklist.md](./deployment-checklist.md) for full checklist.
|
||||
See [rollback-procedure.md](./rollback-procedure.md) if issues occur.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflows
|
||||
|
||||
Workflows define step-by-step procedures invoked via slash commands. They guide Cascade through repetitive tasks.
|
||||
|
||||
### Storage Locations
|
||||
|
||||
| Scope | Location |
|
||||
|-------|----------|
|
||||
| **Global** | `~/.codeium/windsurf/global_workflows/{workflow-name}.md` |
|
||||
| **Workspace** | `.windsurf/workflows/{workflow-name}.md` |
|
||||
|
||||
### File Format
|
||||
|
||||
Workflows are **single markdown files** (not directories):
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Short description of what the workflow does
|
||||
---
|
||||
|
||||
# Workflow Title
|
||||
|
||||
> Arguments: [optional arguments description]
|
||||
|
||||
Step-by-step instructions in markdown.
|
||||
|
||||
1. First step
|
||||
2. Second step
|
||||
3. Third step
|
||||
```
|
||||
|
||||
### Required YAML Frontmatter Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `description` | **Yes** | Short title/description shown in UI |
|
||||
|
||||
### Invocation
|
||||
|
||||
- Slash command: `/workflow-name`
|
||||
- Filename becomes the command (e.g., `deploy.md` → `/deploy`)
|
||||
|
||||
### Constraints
|
||||
|
||||
- **Character limit**: 12,000 characters per workflow file
|
||||
- Workflows can call other workflows: Include instructions like "Call `/other-workflow`"
|
||||
|
||||
### Example: Complete Workflow
|
||||
|
||||
**File**: `~/.codeium/windsurf/global_workflows/address-pr-comments.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Address all PR review comments systematically
|
||||
---
|
||||
|
||||
# Address PR Comments
|
||||
|
||||
> Arguments: [PR number]
|
||||
|
||||
1. Check out the PR branch: `gh pr checkout [id]`
|
||||
|
||||
2. Get comments on PR:
|
||||
```bash
|
||||
gh api --paginate repos/[owner]/[repo]/pulls/[id]/comments | jq '.[] | {user: .user.login, body, path, line}'
|
||||
```
|
||||
|
||||
3. For EACH comment:
|
||||
a. Print: "(index). From [user] on [file]:[lines] — [body]"
|
||||
b. Analyze the file and line range
|
||||
c. If unclear, ask for clarification
|
||||
d. Make the change before moving to next comment
|
||||
|
||||
4. Summarize what was done and which comments need attention
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
Rules provide persistent behavioral guidelines that influence how Cascade responds.
|
||||
|
||||
### Storage Locations
|
||||
|
||||
| Scope | Location |
|
||||
|-------|----------|
|
||||
| **Global** | `~/.codeium/windsurf/rules/{rule-name}.md` |
|
||||
| **Workspace** | `.windsurf/rules/{rule-name}.md` |
|
||||
|
||||
### File Format
|
||||
|
||||
Rules are **single markdown files**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: When to use this rule
|
||||
trigger: activation_mode
|
||||
globs: ["*.py", "src/**/*.ts"]
|
||||
---
|
||||
|
||||
Rule instructions in markdown format.
|
||||
|
||||
- Guideline 1
|
||||
- Guideline 2
|
||||
- Guideline 3
|
||||
```
|
||||
|
||||
### YAML Frontmatter Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `description` | **Yes** | Describes when to use the rule |
|
||||
| `trigger` | Optional | Activation mode (see below) |
|
||||
| `globs` | Optional | File patterns for glob trigger |
|
||||
|
||||
### Activation Modes (trigger field)
|
||||
|
||||
| Mode | Value | Description |
|
||||
|------|-------|-------------|
|
||||
| **Manual** | `manual` | Activated via `@mention` in Cascade input |
|
||||
| **Always On** | `always` | Always applied to every conversation |
|
||||
| **Model Decision** | `model_decision` | Model decides based on description |
|
||||
| **Glob** | `glob` | Applied when working with files matching pattern |
|
||||
|
||||
### Constraints
|
||||
|
||||
- **Character limit**: 12,000 characters per rule file
|
||||
|
||||
### Example: Complete Rule
|
||||
|
||||
**File**: `~/.codeium/windsurf/rules/python-style.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Python coding standards and style guidelines. Use when writing or reviewing Python code.
|
||||
trigger: glob
|
||||
globs: ["*.py", "**/*.py"]
|
||||
---
|
||||
|
||||
# Python Coding Guidelines
|
||||
|
||||
- Use type hints for all function parameters and return values
|
||||
- Follow PEP 8 style guide
|
||||
- Use early returns when possible
|
||||
- Always add docstrings to public functions and classes
|
||||
- Prefer f-strings over .format() or % formatting
|
||||
- Use pathlib instead of os.path for file operations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memories
|
||||
|
||||
### Global Rules (Always-On)
|
||||
|
||||
**Location**: `~/.codeium/windsurf/memories/global_rules.md`
|
||||
|
||||
This is a special file for rules that **always apply** to all conversations. Unlike rules in the `rules/` directory, this file:
|
||||
|
||||
- Does **not** require YAML frontmatter
|
||||
- Is plain text/markdown
|
||||
- Is always active (no trigger configuration)
|
||||
|
||||
**Format:**
|
||||
```markdown
|
||||
Plain text rules that always apply to all conversations.
|
||||
|
||||
- Rule 1
|
||||
- Rule 2
|
||||
- Rule 3
|
||||
```
|
||||
|
||||
### Auto-Generated Memories
|
||||
|
||||
Cascade automatically creates memories during conversations, stored as `.pb` (protobuf) files in `~/.codeium/windsurf/memories/`. These are managed by Windsurf and should not be manually edited.
|
||||
|
||||
---
|
||||
|
||||
## System-Level Configuration (Enterprise)
|
||||
|
||||
Enterprise organizations can deploy system-level configurations that apply globally and cannot be modified by end users.
|
||||
|
||||
### System-Level Paths
|
||||
|
||||
| Type | Windows | macOS | Linux/WSL |
|
||||
|------|---------|-------|-----------|
|
||||
| **Rules** | `C:\ProgramData\Windsurf\rules\*.md` | `/Library/Application Support/Windsurf/rules/*.md` | `/etc/windsurf/rules/*.md` |
|
||||
| **Workflows** | `C:\ProgramData\Windsurf\workflows\*.md` | `/Library/Application Support/Windsurf/workflows/*.md` | `/etc/windsurf/workflows/*.md` |
|
||||
|
||||
### Precedence Order
|
||||
|
||||
When items with the same name exist at multiple levels:
|
||||
|
||||
1. **System** (highest priority) - Organization-wide, deployed by IT
|
||||
2. **Workspace** - Project-specific in `.windsurf/`
|
||||
3. **Global** - User-defined in `~/.codeium/windsurf/`
|
||||
4. **Built-in** - Default items provided by Windsurf
|
||||
|
||||
---
|
||||
|
||||
## Programmatic Creation Reference
|
||||
|
||||
### Quick Reference Table
|
||||
|
||||
| Type | Path Pattern | Format | Key Fields |
|
||||
|------|--------------|--------|------------|
|
||||
| **Skill** | `skills/{name}/SKILL.md` | YAML frontmatter + markdown | `name`, `description` |
|
||||
| **Workflow** | `global_workflows/{name}.md` (global) or `workflows/{name}.md` (workspace) | YAML frontmatter + markdown | `description` |
|
||||
| **Rule** | `rules/{name}.md` | YAML frontmatter + markdown | `description`, `trigger`, `globs` |
|
||||
| **Global Rules** | `memories/global_rules.md` | Plain text/markdown | None |
|
||||
|
||||
### Minimal Templates
|
||||
|
||||
#### Skill (SKILL.md)
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What this skill does and when to use it
|
||||
---
|
||||
|
||||
Instructions here.
|
||||
```
|
||||
|
||||
#### Workflow
|
||||
```markdown
|
||||
---
|
||||
description: What this workflow does
|
||||
---
|
||||
|
||||
1. Step one
|
||||
2. Step two
|
||||
```
|
||||
|
||||
#### Rule
|
||||
```markdown
|
||||
---
|
||||
description: When this rule applies
|
||||
trigger: model_decision
|
||||
---
|
||||
|
||||
- Guideline one
|
||||
- Guideline two
|
||||
```
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
When programmatically creating items:
|
||||
|
||||
- [ ] **Skills**: Directory exists with `SKILL.md` inside
|
||||
- [ ] **Skills**: `name` field matches directory name exactly
|
||||
- [ ] **Skills**: Name uses only lowercase letters, numbers, hyphens
|
||||
- [ ] **Workflows/Rules**: File is `.md` extension
|
||||
- [ ] **All**: YAML frontmatter uses `---` delimiters
|
||||
- [ ] **All**: `description` field is present and meaningful
|
||||
- [ ] **All**: File size under 12,000 characters (workflows/rules)
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Writing Effective Descriptions
|
||||
|
||||
The `description` field is critical for automatic invocation. Be specific:
|
||||
|
||||
**Good:**
|
||||
```yaml
|
||||
description: Guides deployment to staging environment with pre-flight checks. Use when deploying to staging, testing releases, or preparing for production.
|
||||
```
|
||||
|
||||
**Bad:**
|
||||
```yaml
|
||||
description: Deployment stuff
|
||||
```
|
||||
|
||||
### Formatting Guidelines
|
||||
|
||||
- Use bullet points and numbered lists (easier for Cascade to follow)
|
||||
- Use markdown headers to organize sections
|
||||
- Keep rules concise and specific
|
||||
- Avoid generic rules like "write good code" (already built-in)
|
||||
|
||||
### XML Tags for Grouping
|
||||
|
||||
XML tags can effectively group related rules:
|
||||
|
||||
```markdown
|
||||
<coding_guidelines>
|
||||
- Use early returns when possible
|
||||
- Always add documentation for new functions
|
||||
- Prefer composition over inheritance
|
||||
</coding_guidelines>
|
||||
|
||||
<testing_requirements>
|
||||
- Write unit tests for all public methods
|
||||
- Maintain 80% code coverage
|
||||
</testing_requirements>
|
||||
```
|
||||
|
||||
### Skills vs Rules vs Workflows
|
||||
|
||||
| Use Case | Recommended |
|
||||
|----------|-------------|
|
||||
| Multi-step procedure with supporting files | **Skill** |
|
||||
| Repeatable CLI/automation sequence | **Workflow** |
|
||||
| Coding style preferences | **Rule** |
|
||||
| Project conventions | **Rule** |
|
||||
| Deployment procedure | **Skill** or **Workflow** |
|
||||
| Code review checklist | **Skill** |
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Official Documentation**: [docs.windsurf.com](https://docs.windsurf.com)
|
||||
- **Skills Specification**: [agentskills.io](https://agentskills.io/home)
|
||||
- **Rule Templates**: [windsurf.com/editor/directory](https://windsurf.com/editor/directory)
|
||||
Reference in New Issue
Block a user