## File: README.md # Compound Engineering [](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml) AI skills that make each unit of engineering work easier than the last. ## Install ### Claude Code ```text /plugin marketplace add EveryInc/compound-engineering-plugin /plugin install compound-engineering ``` > **Already have Compound Engineering installed?** Compound Engineering moved to a root-native layout. You must refresh the marketplace *before* updating — see [Existing Installs](#existing-installs). Running `/plugin update` alone keeps you on the old version. ### Cursor In Cursor Agent chat, install from the plugin marketplace: ```text /add-plugin compound-engineering ``` Or search for "compound engineering" in the plugin marketplace. ### Grok Bot Grok Bot is its own app, but it uses your Cursor account and plugin library. There is no separate Grok Bot login. Install Compound Engineering once on that account and Grok Bot agents can load it. In Cursor Agent chat: ```text /add-plugin compound-engineering ``` Or search for "compound engineering" in the Cursor plugin marketplace. Do not run `/add-plugin` in the Grok Bot chat, and do not clone this repository onto the Grok Bot computer. ### Codex App Compound Engineering is not listed in Codex's built-in plugin marketplace yet. Add it as a custom marketplace: 1. In the Codex app, open **Plugins** from the sidebar. 2. Click the arrow next to **Create**, then select **Add marketplace**. 3. Enter: | Field | Value | | --- | --- | | Source | `EveryInc/compound-engineering-plugin` | | Git ref | `main` | | Sparse paths | leave blank | 4. Click **Add marketplace**. 5. Search for **Compound Engineering**, install **compound-engineering-plugin**, then restart Codex. The Codex app install is self-contained for Compound Engineering. Specialist reviewer and research behavior lives inside the skills as local prompt assets; no separate custom-agent install step is required. ### Codex CLI Register the marketplace, then install the plugin. 1. **Register the marketplace with Codex:** ```bash codex plugin marketplace add EveryInc/compound-engineering-plugin ``` 2. **Install the plugin:** ```bash codex plugin add compound-engineering@compound-engineering-plugin ``` You can also launch `codex`, run `/plugins`, find the **Compound Engineering** marketplace, select the **compound-engineering** plugin, and choose **Install**. Restart Codex after install completes. The native Codex plugin install is self-contained for Compound Engineering. Specialist reviewer and research behavior lives inside the skills as local prompt assets; no separate custom-agent install step is required. For a non-default Codex profile, run every Codex-related step against the same `CODEX_HOME`. This example installs CE into a `work` profile: ```bash CODEX_HOME="$HOME/.codex/profiles/work" codex plugin marketplace add EveryInc/compound-engineering-plugin CODEX_HOME="$HOME/.codex/profiles/work" codex plugin add compound-engineering@compound-engineering-plugin ``` The marketplace step only makes the plugin available; the plugin install is what activates the native CE skills for that profile. #### Remove the legacy Codex tool map (pre-native installs) If you previously installed Compound Engineering with the Bun `convert` / `install --to codex` CLI (before native Codex plugin support), that path may have inserted a managed block into your **global** Codex instructions file: `` … `` in `$CODEX_HOME/AGENTS.md` (default `~/.codex/AGENTS.md`). That Claude-compat tool map is obsolete — CE skills name Codex tools inline — and one of its lines incorrectly told Codex to collapse subagent dispatch onto the main thread. Native plugin install does **not** add this block. Paste this into Codex (or any agent with access to your home directory) to remove it: ```text Remove the obsolete Compound Engineering Codex tool-map block from my Codex home AGENTS.md. 1. Check `$CODEX_HOME/AGENTS.md` if CODEX_HOME is set, otherwise `~/.codex/AGENTS.md`. If I use Codex profiles, also check `~/.codex/profiles/*/AGENTS.md`. 2. Look for the exact sentinels `` and ``. 3. If both are present, delete only the span from the BEGIN line through the END line (inclusive), leaving any other user content untouched. Do not edit project/repo AGENTS.md unless those exact sentinels are present there. 4. If the file is empty after the removal, delete the file. 5. Show a short before/after summary of what you changed (or say the block was already absent). Do not add a replacement tool map. ``` Re-running the Bun convert/install CLI for Codex also strips the block if it is still present; it no longer inserts it. **Another editor or CLI?** Kimi Code CLI, Cline, Grok Build CLI, Devin CLI, GitHub Copilot, Factory Droid, Qwen Code, OpenCode, Pi, oh-my-pi (omp), and Antigravity CLI are all supported — see [More install options](#more-install-options). --- ## Philosophy **Each unit of engineering work should make subsequent units easier -- not harder.** Invocation syntax: this README uses `/skill-name` examples for slash-skill hosts. In Codex, invoke installed skills with `$skill-name` (for example, `$ce-plan` and `$lfg`). In oh-my-pi (omp), these prompts can model-route to visible skills; use the native deterministic `/skill:` form for manual-only or hidden skills (for example, `/skill:ce-polish`). `/goal` remains a Codex built-in command. Traditional development accumulates technical debt. Every feature adds complexity. Every bug fix leaves behind a little more local knowledge that someone has to rediscover later. The codebase gets larger, the context gets harder to hold, and the next change becomes slower. Compound engineering inverts this. 80% is in planning and review, 20% is in execution: - Plan thoroughly before writing code with `/ce-brainstorm` and `/ce-plan` using one readiness-based plan artifact - Review to catch issues and calibrate judgment with `/ce-code-review` and `/ce-doc-review` - Codify knowledge so it is reusable with `/ce-compound` - Keep quality high so future changes are easy The point is not ceremony. The point is leverage. A good brainstorm makes the plan sharper. A good plan makes execution smaller. A good review catches the pattern, not just the bug. A good compound note means the next agent does not have to learn the same lesson from scratch. **Learn more** - [Skill documentation catalog](docs/skills/README.md) - [Compound engineering: how Every codes with agents](https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents) - [The story behind compounding engineering](https://every.to/source-code/my-ai-had-already-fixed-the-code-before-i-saw-it) ## Workflow The core loop is six steps: **brainstorm** the requirements, **plan** the implementation, **work** through the plan, **simplify** what you wrote, **review** the result, then **compound** the learning -- and repeat with better context. | Skill | Purpose | |-------|---------| | [`/ce-brainstorm`](docs/skills/ce-brainstorm.md) | Interactive Q&A to think through a feature or problem and write a requirements-only unified plan before planning | | [`/ce-plan`](docs/skills/ce-plan.md) | Enrich feature ideas or requirements-only plans into implementation-ready plans | | [`/ce-work`](docs/skills/ce-work.md) | Execute implementation-ready plans natively or through a qualified cross-model author while retaining host verification, commits, and shipping | | [`/ce-simplify-code`](docs/skills/ce-simplify-code.md) | Refine the freshly written code for clarity and reuse before review | | [`/ce-code-review`](docs/skills/ce-code-review.md) | Report-only multi-agent review against the plan before merging; local apply is explicit | | [`/ce-compound`](docs/skills/ce-compound.md) | Capture the learning into `docs/solutions/` so the next loop starts smarter | Each cycle compounds: `/ce-compound` writes learnings that the next `/ce-brainstorm` and `/ce-plan` read as grounding -- brainstorms sharpen plans, plans inform future plans, reviews catch more issues, patterns get documented. That return arrow is the whole point. > Artifact folders like `docs/solutions/` and `docs/plans/` are the **defaults**. A project whose `docs/` is tracked content can relocate every CE artifact folder under one repo-relative root via the `docs_root` setting -- see [configuration](docs/skills/configuration.md#artifact-root). ### Additional skills These sit around the loop or get reached for on demand -- not every cycle needs them. | Skill | When to reach for it | |-------|---------| | [`/ce-ideate`](docs/skills/ce-ideate.md) | *Before the loop*, when you don't yet know what to build -- generates and critically ranks grounded ideas, then routes the strongest one into `/ce-brainstorm` | | [`/ce-strategy`](docs/skills/ce-strategy.md) | *Upstream anchor* -- creates and maintains `STRATEGY.md`, read as grounding by ideate, brainstorm, and plan so strategy choices flow into every feature | | [`/ce-product-pulse`](docs/skills/ce-product-pulse.md) | *Outer loop* -- a time-windowed report on what users actually experienced (usage, performance, errors), saved to `docs/pulse-reports/`; its follow-ups feed back into ideation and brainstorming | | [`/ce-debug`](docs/skills/ce-debug.md) | *Instead of brainstorm -> plan -> work* when the input is a bug rather than a feature -- reproduce, trace root cause, fix, then polish/review before PR handoff when warranted | | [`/ce-pov`](docs/skills/ce-pov.md) | *On demand, before you commit* -- a decisive, project-grounded adoption verdict, holistic document take, or position on supplied approaches; optionally cross-checked by named peers or `oracle` through a blind initial round and bounded reconciliation | | [`/ce-explain`](docs/skills/ce-explain.md) | *On demand, to account for the work or understand it* -- turns a concept, a diff, an idea, or "what did I do this week?" into a dense, self-contained visual document built to keep, with an optional check-in (predict-then-reveal for diffs, corrected exercises) when the material is worth retaining | For the full catalog and how each skill chains together, see [docs/skills](docs/skills/README.md). The complete inventory is [below](#full-skill-inventory). ## Quick Example **Finding a direction** -- when you don't have a specific idea yet, ideate first, then carry the strongest survivor into the loop: ```text /ce-ideate new drawing tools /ce-ideate surprise me /ce-ideate open issues # ground ideas in your tracker's open issues (GitHub, Linear, Jira) ``` `/ce-ideate` does the homework first (codebase, past learnings, prior art on the web, optionally your issue tracker), then hands you a ranked set of grounded candidates to take into `/ce-brainstorm`. **Standard feature loop** -- turn a rough idea into shipped, reviewed code: ```text /ce-brainstorm make background job retries safer /ce-plan /ce-work /ce-simplify-code /ce-code-review /ce-compound ``` **Simplifying code** -- use it after fresh implementation work, or point it at code that keeps slowing changes down: ```text /ce-simplify-code /ce-simplify-code simplify the code in my most-churned file ``` The first pass tightens recent branch changes before review. The targeted pass is useful when one file keeps absorbing unrelated fixes, follow-ups, or merge conflicts. **Debugging a bug** -- when you start from broken behavior instead of a feature: ```text /ce-debug the checkout webhook sometimes creates duplicate invoices /ce-code-review /ce-compound ``` **Autonomous** -- hand off a feature and let the agent run the whole pipeline: ```text /ce-brainstorm describe the feature /lfg ``` `/lfg` runs the loop hands-off: it plans, works through the plan, simplifies, runs code review and applies the fixes, runs browser tests, then commits. When a git remote exists it pushes, opens a PR, and watches CI with a bounded repair loop (it does not merge, and it can finish with leftovers if the repair budget is hit). With no remote it stops at local commits. Start it after `/ce-brainstorm` so it plans against real requirements rather than a one-line prompt. It's the autopilot version of the standard loop when you want to step away and come back to an open PR. When an eligible multi-area plan still has unplanned work, `lfg` also recommends and justifies the next separately planned area; only if you accept does it create a `/ce-handoff` for a fresh session and separate plan. ## Getting Started After installing, run `/ce-setup` in any project. It reports optional tool capabilities, creates repo `.compound-engineering/config.yaml` when missing, refreshes the committed example, and gitignores an existing local override. The `compound-engineering` plugin currently ships 33 skills. Its core workflows spawn specialist subagents on demand for research, review, planning, and implementation. Each skill seeds generic subagents with its own prompts instead of relying on standalone plugin agents, keeping the workflows portable across harnesses that handle formal agent definitions differently. ### Full Skill Inventory | Skill | Purpose | |-------|---------| | [`/ce-strategy`](docs/skills/ce-strategy.md) | Create or maintain `STRATEGY.md` | | [`/ce-ideate`](docs/skills/ce-ideate.md) | Generate and critically evaluate grounded ideas | | [`/ce-pov`](docs/skills/ce-pov.md) | Form a decisive, project-grounded POV on an adoption, document, or approach set | | [`/ce-explain`](docs/skills/ce-explain.md) | Document a concept, diff, idea, or window of your own work as a visual artifact built to keep | | [`/ce-brainstorm`](docs/skills/ce-brainstorm.md) | Explore requirements and write a right-sized requirements doc | | [`/ce-plan`](docs/skills/ce-plan.md) | Create structured implementation plans | | [`/ce-work`](docs/skills/ce-work.md) | Execute plans with native or cross-model implementation, durable progress, and transactional host-owned integration | | [`/ce-code-review`](docs/skills/ce-code-review.md) | Review code with skill-local reviewer personas | | [`/ce-doc-review`](docs/skills/ce-doc-review.md) | Review requirements and plan documents | | [`/ce-debug`](docs/skills/ce-debug.md) | Reproduce failures, trace root cause, fix bugs, and prepare non-trivial fixes for PR | | [`/ce-compound`](docs/skills/ce-compound.md) | Document solved problems to compound team knowledge | | [`/ce-compound-refresh`](docs/skills/ce-compound-refresh.md) | Refresh stale or drifting learnings | | [`/ce-optimize`](docs/skills/ce-optimize.md) | Run iterative optimization loops | | [`/ce-retune`](docs/skills/ce-retune.md) | Retune a skill corpus for a new model, measurement-first | | [`/ce-product-pulse`](docs/skills/ce-product-pulse.md) | Generate time-windowed product pulse reports | | [`/ce-riffrec-feedback-analysis`](docs/skills/ce-riffrec-feedback-analysis.md) | Convert Riffrec recordings or notes into structured feedback | | [`/ce-sweep`](docs/skills/ce-sweep.md) | Sweep feedback sources, track item lifecycles, and emit an `/lfg`-ready plan | | [`/ce-resolve-pr-feedback`](docs/skills/ce-resolve-pr-feedback.md) | Resolve PR review feedback | | [`/ce-commit`](docs/skills/ce-commit.md) | Create a git commit with a clear message | | [`/ce-commit-push-pr`](docs/skills/ce-commit-push-pr.md) | Commit, push, and open a PR (or construct/submit an opt-in managed stack) that teaches any concept the change newly introduces | | [`/ce-babysit-pr`](docs/skills/ce-babysit-pr.md) | Watch an open PR (or confirmed managed stack under posture) and keep it moving toward merge, reacting to review comments and CI as they arrive | | [`/ce-worktree`](docs/skills/ce-worktree.md) | Ensure work happens in an isolated git worktree | | [`/ce-promote`](docs/skills/ce-promote.md) | Draft user-facing announcement copy | | [`/ce-test-browser`](docs/skills/ce-test-browser.md) | Run browser tests on PR-affected pages | | [`/ce-test-xcode`](docs/skills/ce-test-xcode.md) | Build and test iOS apps on simulator | | [`/ce-setup`](docs/skills/ce-setup.md) | Diagnose optional tool capabilities and create repo `config.yaml` | | [`/ce-handoff`](docs/skills/ce-handoff.md) | Create a session handoff at the default temp store or a requested destination, then resume from a selected source | | [`/ce-simplify-code`](docs/skills/ce-simplify-code.md) | Simplify recent code changes | | [`/ce-prototype`](docs/skills/ce-prototype.md) | Build a throwaway prototype so someone can experience how the product should work, feel, or read | | [`/ce-polish`](docs/skills/ce-polish.md) | Start a dev server and iterate on UX polish | | [`/ce-proof`](docs/skills/ce-proof.md) | Create, edit, and share Proof documents | | [`/ce-dogfood`](docs/skills/ce-dogfood.md) | Hands-off diff-scoped browser QA of the active branch, with autonomous fixes | | [`/lfg`](docs/skills/lfg.md) | Full autonomous engineering workflow | --- ## More Install Options [Claude Code, Cursor, and Codex](#install) are at the top. Everything here is equally supported. ### Kimi Code CLI Kimi Code CLI can install Compound Engineering directly from this repository because the repo ships a native `.kimi-plugin/plugin.json` manifest: ```text /plugins install https://github.com/EveryInc/compound-engineering-plugin ``` You can also browse it through Kimi's custom marketplace flow: ```text /plugins marketplace https://raw.githubusercontent.com/EveryInc/compound-engineering-plugin/main/.kimi-plugin/marketplace.json ``` After installing or updating, run `/reload` or start a new Kimi session so the plugin skills are loaded. ### Cline Cline loads CE skills from on-demand `SKILL.md` directories. Enable **Settings -> Features -> Enable Skills** in the Cline extension, then link this repository's skills globally or per project: ```bash git clone https://github.com/EveryInc/compound-engineering-plugin ./compound-engineering-plugin/.cline/scripts/install-skills.sh --global ``` Per-project install from a checkout: ```bash ./compound-engineering-plugin/.cline/scripts/install-skills.sh --project ``` Start a new Cline task after installing or updating skills. See [`.cline/INSTALL.md`](.cline/INSTALL.md) for pinning, local development, and uninstall steps. ### Grok Build CLI (`grok`) xAI's [Grok Build CLI](https://x.ai/cli) (`grok`) installs Compound Engineering directly from this repository — the repo root is a valid Grok plugin (`grok` reads the existing Claude-compatible manifests, and the repo also ships a native `.grok-plugin/plugin.json`): ```bash grok plugin install EveryInc/compound-engineering-plugin ``` This tracks the repository; run `grok plugin update` to pull the latest. To browse it as a marketplace source instead, the repo ships a native `.grok-plugin/marketplace.json`: ```bash grok plugin marketplace add EveryInc/compound-engineering-plugin grok plugin install compound-engineering ``` Both paths track the repository directly (no commit pin), so no Bun install step is needed. Add `--trust` to skip the install confirmation. `grok` stores config under `~/.grok`; start a new session after installing so the skills load. Compound Engineering is also being submitted to the official [xAI plugin marketplace](https://github.com/xai-org/plugin-marketplace); see [`docs/grok-marketplace-submission.md`](docs/grok-marketplace-submission.md) for the maintainer runbook. ### Devin CLI Devin CLI can install Compound Engineering directly from GitHub because the repo ships a native `.devin-plugin/plugin.json` manifest: ```bash devin plugins install EveryInc/compound-engineering-plugin ``` Verify the install and inspect the skills: ```bash devin plugins list devin plugins info compound-engineering ``` Update to the latest version with `devin plugins update compound-engineering`. Plugins load at session start, so start a new Devin session after installing or updating for the skills to appear (as `/compound-engineering:` slash commands). A few skills declare Claude-style `allowed-tools` names that Devin does not map (for example `Bash`); those skills still work, but some of their actions ask for permission instead of running auto-approved. See [`docs/specs/devin.md`](docs/specs/devin.md) for details. ### GitHub Copilot For **VS Code Copilot Agent Plugins**: 1. Run `Chat: Install Plugin from Source` from the VS Code command palette 2. Use `EveryInc/compound-engineering-plugin` for the repo 3. Select `compound-engineering` when VS Code shows the plugins in this repository For **Copilot CLI**, use: Inside Copilot CLI: ```text /plugin marketplace add EveryInc/compound-engineering-plugin /plugin install compound-engineering@compound-engineering-plugin ``` From a shell with the `copilot` binary: ```bash copilot plugin marketplace add EveryInc/compound-engineering-plugin copilot plugin install compound-engineering@compound-engineering-plugin ``` Copilot CLI reads the existing Claude-compatible plugin manifests, so no separate Bun install step is needed. ### Factory Droid From a shell with the `droid` binary: ```bash droid plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin droid plugin install compound-engineering@compound-engineering-plugin ``` Droid uses `plugin@marketplace` plugin IDs; here `compound-engineering` is the plugin and `compound-engineering-plugin` is the marketplace name. Droid installs the existing Claude Code-compatible plugin and translates the format automatically, so no Bun install step is needed. ### Qwen Code ```bash qwen extensions install EveryInc/compound-engineering-plugin:compound-engineering ``` Qwen Code installs Claude Code-compatible plugins directly from GitHub and converts the plugin format during install, so no Bun install step is needed. ### OpenCode Add Compound Engineering to the `plugin` array in your global or project `opencode.json`: ```json { "plugin": ["compound-engineering@git+https://github.com/EveryInc/compound-engineering-plugin.git"] } ``` Restart OpenCode after changing the config. The OpenCode plugin registers the Compound Engineering skills directory directly; no Bun installer or generated skill copy is required. See [`.opencode/INSTALL.md`](.opencode/INSTALL.md) for pinning examples. ### Pi Install Compound Engineering as a Pi package from this repository: ```bash pi install git:github.com/EveryInc/compound-engineering-plugin ``` Required companion for CE workflows that dispatch reviewer, research, or implementation subagents: ```bash pi install npm:pi-subagents ``` Recommended companion for richer blocking questions: ```bash pi install npm:pi-ask-user ``` ### oh-my-pi (omp) oh-my-pi (omp) installs Compound Engineering through its marketplace flow. The repo ships a native `.omp-plugin/marketplace.json` catalog whose plugin entry carries a release-managed `version`, so omp's update checker can see each new CE release: ```text omp plugin marketplace add EveryInc/compound-engineering-plugin omp plugin install compound-engineering@compound-engineering-plugin ``` To stay current automatically, enable auto-update: ```bash omp config set marketplace.autoUpdate auto ``` The default `notify` mode only writes update availability to the debug log — it does not prompt — so without `auto` you will not hear about new releases. To upgrade by hand instead, run `omp plugin upgrade compound-engineering@compound-engineering-plugin`. Other install paths (pin-style and contributor development) `omp install https://github.com/EveryInc/compound-engineering-plugin` installs the repository as an npm-style plugin. That path has **no update mechanism** — treat it as pinning a snapshot, not as the recommended install. For local development from a checkout, use a live symlink instead: ```bash omp plugin link "$PWD" ``` Run `/reload-plugins` or start a new omp session after installing so the skills load. omp's native deterministic command is `/skill:` (for example, `/skill:ce-plan`); ordinary `/skill-name` prompts can also model-route to visible skills, but manual-only or hidden skills require the native form. See [`docs/specs/omp.md`](docs/specs/omp.md) for details. ### Antigravity CLI (`agy`) Google has replaced the consumer Gemini CLI with [Antigravity CLI](https://antigravity.google) (`agy`), which still runs on Gemini models. Install Compound Engineering directly from GitHub — no clone step required: ```bash agy plugin install https://github.com/EveryInc/compound-engineering-plugin ``` Verify with `agy plugin list`. The repository root is the plugin package (`plugin.json` plus `skills/`). For a local checkout or pinned release: ```bash git clone https://github.com/EveryInc/compound-engineering-plugin agy plugin install ./compound-engineering-plugin ``` The bundled `.agy/` directory remains a compatibility entry point (`agy plugin install ./compound-engineering-plugin/.agy`). `agy` also loads `GEMINI.md` workspace context from the checkout. See [`.agy/INSTALL.md`](.agy/INSTALL.md) for pinning, local development, uninstall, and legacy Gemini import. ### Existing Installs Compound Engineering moved to a root-native, skills-only layout. An existing marketplace install keeps a **cached** marketplace snapshot that still points at the old `plugins/compound-engineering` path, so updating the plugin on its own reads that stale snapshot and leaves you on the previous version. Refresh the cached marketplace **first**, then update the plugin — order matters. **Claude Code** ```text /plugin marketplace update compound-engineering-plugin /plugin update compound-engineering ``` **Codex CLI** ```bash codex plugin marketplace upgrade compound-engineering-plugin codex plugin add compound-engineering@compound-engineering-plugin ``` There is no `codex plugin update`; re-running `add` reinstalls from the refreshed snapshot. For a non-default profile, run both commands against the same `CODEX_HOME`. **Codex App** Refresh the marketplace from the **Plugins** panel (remove and re-add the `EveryInc/compound-engineering-plugin` marketplace if there is no refresh control), then reinstall **compound-engineering** and restart Codex. **Grok Bot** Reinstall or refresh Compound Engineering on that Cursor account (`/add-plugin compound-engineering` in Cursor Agent chat, or marketplace search). Grok Bot then loads the new snapshot from the shared plugin library. Do not clone this repository onto the Grok Bot computer for a normal update. If you configured a host with a direct path or sparse path under `plugins/compound-engineering`, edit or reinstall that source so it points at the repository root with no sparse path. If a previous Bun-installed copy is still shadowing native plugin skills, run the current cleanup command from a checkout of this repository: ```bash git clone https://github.com/EveryInc/compound-engineering-plugin.git /tmp/compound-engineering-plugin-cleanup cd /tmp/compound-engineering-plugin-cleanup bun install bun run cleanup --target all ``` --- ## Local Development ```bash bun install bun test bun run release:validate ``` ### From your local checkout For active development, load this checkout directly in the harness you want to test. **Claude Code** ```bash claude --plugin-dir "$PWD" ``` **Cursor Agent CLI** ```bash cursor-agent --plugin-dir "$PWD" ``` **Codex** For the normal production-like plugin installation, use the [Codex App](#codex-app) or [Codex CLI](#codex-cli) instructions above. The workflow below is only for contributors who need Codex to load unreleased files from an exact checkout or linked worktree. **Advanced: test this exact checkout in Codex** Select the current worktree as the active Codex development source: ```bash bun run codex:dev -- local ``` This creates one collection symlink at `$CODEX_HOME/skills/compound-engineering-local` (default `~/.codex/skills/compound-engineering-local`) pointing to this worktree's `skills/` directory. It removes installed Compound Engineering plugin variants through the Codex CLI so a cached marketplace plugin cannot shadow or duplicate the local skills. It does not copy skills, change the checkout, pull Git, or touch unrelated entries under `$CODEX_HOME/skills`. The link exposes exactly what is in the selected worktree, including modified and untracked skills. Ordinary edits therefore need no reinstall, and current Codex versions detect direct skill changes automatically. Start a new session after switching between local and remote installation modes; if an ordinary skill edit does not appear, restart Codex. Use these commands to inspect and switch modes: ```bash bun run codex:dev -- status bun run codex:dev -- refresh bun run codex:dev -- remote bun run codex:dev -- remove ``` - `status` reports local, remote, mixed, drifted, or absent state plus the linked checkout, worktree kind, branch, commit SHA, and dirty counts. - `refresh` is an idempotent alias for `local`; use it to reconcile accidental plugin installs. The live link already reflects file changes. - `remote` refreshes the official Git marketplace, installs and verifies `compound-engineering@compound-engineering-plugin`, then removes the local link. Use it to simulate the released user experience. - `remove` removes Compound Engineering plugin variants and the managed link, leaving the checkout and unrelated user skills intact. The script derives the repository path, so it works from checkouts in any location, including paths with spaces. It inherits the active `CODEX_HOME`; set `CODEX_HOME` on the command when testing an isolated profile. Run every mode against the same `CODEX_HOME` you use to launch Codex. Do not use `codex plugin marketplace add "$PWD"` for live local development. It installs a cached copy of this checkout, so later edits are not reflected until the plugin is installed again; a matching manifest version also does not prove the cache matches the worktree. The `codex:dev` workflow instead keeps Codex linked to the current skill files. **Kimi Code CLI** Inside Kimi Code CLI: ```text /plugins install /path/to/compound-engineering-plugin ``` To test the local marketplace catalog instead, pass the catalog path: ```text /plugins marketplace /path/to/compound-engineering-plugin/.kimi-plugin/marketplace.json ``` **Cline** ```bash /path/to/compound-engineering-plugin/.cline/scripts/install-skills.sh --global ``` Enable **Settings -> Features -> Enable Skills** in the Cline extension, then start a new task. **Devin CLI** ```bash devin plugins install /path/to/compound-engineering-plugin ``` Local installs are linked to the checkout rather than copied, so skill edits apply on the next Devin session without reinstalling. **OpenCode** ```json { "plugin": ["/path/to/compound-engineering-plugin"] } ``` Restart OpenCode after changing `opencode.json`. **Pi** ```bash pi -e "$PWD" ``` **oh-my-pi (omp)** ```bash omp plugin link "$PWD" ``` **Antigravity CLI (`agy`)** ```bash agy plugin install "$PWD" agy plugin validate "$PWD" ``` Or install the bundled `.agy/` entry point: ```bash agy plugin install "$PWD/.agy" ``` See [`.agy/INSTALL.md`](.agy/INSTALL.md) for remote install and pinning examples. ## Limitations OpenCode, Pi, and oh-my-pi (omp) use native package/plugin loading from this repository. The Bun CLI remains for repository development and converter maintenance, not normal installation. Release versions are owned by release automation. Routine feature PRs should not hand-bump plugin or marketplace manifest versions. ## FAQ ### Do I need Bun to install Compound Engineering? No. Bun is only needed for repo development tasks and converter maintenance. ### Where do I see all available skills? The skill inventory is in this README, and the deeper skill catalog is in [`docs/skills/README.md`](docs/skills/README.md). Each skill's authoritative runtime spec lives in `skills//SKILL.md`. ### Where is release history? GitHub Releases are the canonical release-notes surface. The root [`CHANGELOG.md`](CHANGELOG.md) points to that history. ## Contributing Contributions are welcome. Issues, bug reports, and pull requests all help make this better, and we genuinely appreciate them — bug reports especially. A note on what to expect: Compound Engineering is opinionated by design. It's maintained by [@kieranklaassen](https://github.com/kieranklaassen) and [@tmchow](https://github.com/tmchow), and its direction reflects a specific point of view about how AI-assisted engineering should work. So while we welcome help, we can't promise to accept every change — some proposals won't fit that vision even when they're good ideas on their own. Open an issue or send a PR, and we'll fold in what moves the plugin in the right direction. We just want to be upfront that not everything will land. ## License [MIT](LICENSE) --- ## File: docs/specs/copilot.md # GitHub Copilot Spec (Agents, Skills, MCP) 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 ``` ## Config locations | 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 | Field | Required | Default | Description | |-------|----------|---------|-------------| | `name` | No | Derived from filename | Display name | | `description` | **Yes** | — | What the agent does | | `tools` | No | `["*"]` | Tool access list. `[]` disables all tools. | | `target` | No | both | `vscode`, `github-copilot`, or omit for both | | `infer` | No | `true` | Auto-select based on task context | | `model` | No | Platform default | AI model (works in IDE, may be ignored on github.com) | | `mcp-servers` | No | — | MCP config (org/enterprise agents only) | | `metadata` | No | — | Arbitrary key-value annotations | ### Character limit Agent body content is limited to **30,000 characters**. ### Tool names | Name | Aliases | Purpose | |------|---------|---------| | `execute` | `shell`, `Bash` | Run shell commands | | `read` | `Read` | Read files | | `edit` | `Edit`, `Write` | Modify files | | `search` | `Grep`, `Glob` | Search files | | `agent` | `Task` | Invoke other agents | | `web` | `WebSearch`, `WebFetch` | Web access | ## Skills (SKILL.md) - Skills follow the open SKILL.md standard (same format as Claude Code and Cursor). - A skill is a directory containing `SKILL.md` plus optional `scripts/`, `references/`, and `assets/`. - YAML frontmatter requires `name` and `description` fields. - Skills are loaded on-demand when Copilot determines relevance. ### Discovery locations | Scope | Path | |-------|------| | Project | `.github/skills/*/SKILL.md` | | 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) - MCP configuration is set via **Repository Settings > Copilot > Coding agent > MCP configuration** on GitHub. - Repository-level agents **cannot** define MCP servers inline; use repository settings instead. - Org/enterprise agents can embed MCP server definitions in frontmatter. - All env var names must use the `COPILOT_MCP_` prefix. - Only MCP tools are supported (not resources or prompts). ### Config structure ```json { "mcpServers": { "server-name": { "type": "local", "command": "npx", "args": ["package"], "tools": ["*"], "env": { "API_KEY": "COPILOT_MCP_API_KEY" } } } } ``` ### Server types | Type | Fields | |------|--------| | Local/stdio | `type: "local"`, `command`, `args`, `tools`, `env` | | Remote/SSE | `type: "sse"`, `url`, `tools`, `headers` | ## Prompts (.prompt.md) - Reusable prompt files stored in `.github/prompts/`. - Available in VS Code, Visual Studio, and JetBrains IDEs only (not on github.com). - Invoked via `/promptname` in chat. - Support variable syntax: `${input:name}`, `${file}`, `${selection}`. ## Precedence 1. Built-in agents 2. `~/.copilot/agents` 3. `/.github/agents` 4. `/.github/agents` 5. `~/.claude/agents` 6. `/.claude/agents` 7. `/.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. --- ## File: docs/specs/cursor.md # Cursor Spec (Plugin Marketplace, Rules, Commands, Skills, MCP) Last verified: 2026-02-12 ## Primary sources ``` https://docs.cursor.com/context/rules 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 .cursor-plugin/plugin.json ``` Do not use the old custom Bun converter/install path for Cursor. ## Config locations | Scope | Path | |-------|------| | Project rules | `.cursor/rules/*.mdc` | | Project commands | `.cursor/commands/*.md` | | Project skills | `.cursor/skills/*/SKILL.md` (Cursor also discovers `.agents/skills/*/SKILL.md`; the writer emits only `.cursor/skills`) | | Project MCP | `.cursor/mcp.json` | | Project CLI permissions | `.cursor/cli.json` | | Global MCP | `~/.cursor/mcp.json` | | Global CLI config | `~/.cursor/cli-config.json` | | Legacy rules | `.cursorrules` (deprecated) | ## Rules (.mdc files) - Rules are Markdown files with the `.mdc` extension stored in `.cursor/rules/`. - Each rule has YAML frontmatter with three fields: `description`, `globs`, `alwaysApply`. - Rules have four activation types based on frontmatter configuration: | Type | `alwaysApply` | `globs` | `description` | Behavior | |------|:---:|:---:|:---:|---| | Always | `true` | ignored | optional | Included in every conversation | | Auto Attached | `false` | set | optional | Included when matching files are in context | | Agent Requested | `false` | empty | set | AI decides based on description relevance | | Manual | `false` | empty | empty | Only included via `@rule-name` mention | - Precedence: Team Rules > Project Rules > User Rules > Legacy `.cursorrules` > `AGENTS.md`. ## Commands (slash commands) - Custom commands are Markdown files stored in `.cursor/commands/`. - Commands are plain markdown with no YAML frontmatter support. - The filename (without `.md`) becomes the command name. - Commands are invoked by typing `/` in the chat UI. - Commands support parameterized arguments via `$1`, `$2`, etc. ## Skills (Agent Skills) - Skills follow the open SKILL.md standard, identical to Claude Code and Codex. - A skill is a folder containing `SKILL.md` plus optional `scripts/`, `references/`, and `assets/`. - `SKILL.md` uses YAML frontmatter with required `name` and `description` fields. - Skills can be repo-scoped in `.cursor/skills/` or user-scoped in `~/.cursor/skills/`. - At startup, only each skill's name/description is loaded; full content is injected on invocation. ## MCP (Model Context Protocol) - MCP configuration lives in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global). - Each server is configured under the `mcpServers` key. - STDIO servers support `command` (required), `args`, and `env`. - Remote servers support `url` (required) and optional `headers`. - Cursor infers transport type from whether `command` or `url` is present. Example: ```json { "mcpServers": { "server-name": { "command": "npx", "args": ["-y", "package-name"], "env": { "KEY": "value" } } } } ``` ## CLI (cursor-agent) - Cursor CLI launched August 2025 as `cursor-agent`. - Supports interactive mode, headless mode (`-p`), and cloud agents. - Reads `.cursor/rules/`, `.cursorrules`, and `AGENTS.md` for instructions. - CLI permissions controlled via `.cursor/cli.json` with allow/deny lists. - Permission tokens: `Shell(command)`, `Read(path)`, `Write(path)`, `Delete(path)`, `Grep(path)`, `LS(path)`. --- ## File: docs/specs/kiro.md # Kiro CLI Spec (Custom Agents, Skills, Steering, MCP, Settings) Last verified: 2026-02-17 ## Primary sources ``` https://kiro.dev/docs/cli/ https://kiro.dev/docs/cli/custom-agents/configuration-reference/ https://kiro.dev/docs/cli/skills/ https://kiro.dev/docs/cli/steering/ https://kiro.dev/docs/cli/mcp/ https://kiro.dev/docs/cli/hooks/ https://agentskills.io ``` ## Config locations - Project-level config: `.kiro/` directory at project root. - No global/user-level config directory — all config is project-scoped. ## Directory structure ``` .kiro/ ├── agents/ │ ├── .json # Agent configuration │ └── prompts/ │ └── .md # Agent prompt files ├── skills/ │ └── / │ └── SKILL.md # Skill definition ├── steering/ │ └── .md # Always-on context files └── settings/ └── mcp.json # MCP server configuration ``` ## Custom agents (JSON config + prompt files) - Custom agents are JSON files in `.kiro/agents/`. - Each agent has a corresponding prompt `.md` file, referenced via `file://` URI. - Agent config has 14 possible fields (see below). - Agents are activated by user selection (no auto-activation). - The converter outputs a subset of fields relevant to converted plugins. ### Agent config fields | Field | Type | Used in conversion | Notes | |---|---|---|---| | `name` | string | Yes | Agent display name | | `description` | string | Yes | Human-readable description | | `prompt` | string or `file://` URI | Yes | System prompt or file reference | | `tools` | string[] | Yes (`["*"]`) | Available tools | | `resources` | string[] | Yes | `file://`, `skill://`, `knowledgeBase` URIs | | `includeMcpJson` | boolean | Yes (`true`) | Inherit project MCP servers | | `welcomeMessage` | string | Yes | Agent switch greeting | | `mcpServers` | object | No | Per-agent MCP config (use includeMcpJson instead) | | `toolAliases` | Record | No | Tool name remapping | | `allowedTools` | string[] | No | Auto-approve patterns | | `toolsSettings` | object | No | Per-tool configuration | | `hooks` | object | No (future work) | 5 trigger types | | `model` | string | No | Model selection | | `keyboardShortcut` | string | No | Quick-switch shortcut | ### Example agent config ```json { "name": "security-reviewer", "description": "Reviews code for security vulnerabilities", "prompt": "file://./prompts/security-reviewer.md", "tools": ["*"], "resources": [ "file://.kiro/steering/**/*.md", "skill://.kiro/skills/**/SKILL.md" ], "includeMcpJson": true, "welcomeMessage": "Switching to security-reviewer. Reviews code for security vulnerabilities" } ``` ## Skills (SKILL.md standard) - Skills follow the open [Agent Skills](https://agentskills.io) standard. - A skill is a folder containing `SKILL.md` plus optional supporting files. - Skills live in `.kiro/skills/`. - `SKILL.md` uses YAML frontmatter with `name` and `description` fields. - Kiro activates skills on demand based on description matching. - The `description` field is critical — Kiro uses it to decide when to activate the skill. ### Constraints - Skill name: max 64 characters, pattern `^[a-z][a-z0-9-]*$`, no consecutive hyphens (`--`). - Skill description: max 1024 characters. - Skill name must match parent directory name. ### Example ```yaml --- name: workflows-plan --- # Planning Workflow Detailed instructions... ``` ## Steering files - Markdown files in `.kiro/steering/`. - Always loaded into every agent session's context. - Equivalent to the repo instruction file used by Claude-oriented workflows; in this repo `AGENTS.md` is canonical and `CLAUDE.md` may exist only as a compatibility shim. - Used for project-wide instructions, coding standards, and conventions. ## MCP server configuration - MCP servers are configured in `.kiro/settings/mcp.json`. - **Only stdio transport is supported** — `command` + `args` + `env`. - HTTP/SSE transport (`url`, `headers`) is NOT supported by Kiro CLI. - The converter skips HTTP-only MCP servers with a warning. ### Example ```json { "mcpServers": { "playwright": { "command": "npx", "args": ["-y", "@anthropic/mcp-playwright"] }, "context7": { "command": "npx", "args": ["-y", "@context7/mcp-server"] } } } ``` ## Hooks - Kiro supports 5 hook trigger types: `agentSpawn`, `userPromptSubmit`, `preToolUse`, `postToolUse`, `stop`. - Hooks are configured inside agent JSON configs (not separate files). - 3 of 5 triggers map to Claude Code hooks (`preToolUse`, `postToolUse`, `stop`). - Not converted by the plugin converter for MVP — a warning is emitted. ## Conversion lossy mappings | Claude Code Feature | Kiro Status | Notes | |---|---|---| | `Edit` tool (surgical replacement) | Degraded -> `write` (full-file) | Kiro write overwrites entire files | | `context: fork` | Lost | No execution isolation control | | `!`command`` dynamic injection | Lost | No pre-processing of markdown | | `disable-model-invocation` | Lost | No invocation control | | `allowed-tools` per skill | Lost | No tool permission scoping per skill | | `$ARGUMENTS` interpolation | Lost | No structured argument passing | | Claude hooks | Skipped | Future follow-up (near-1:1 for 3/5 triggers) | | HTTP MCP servers | Skipped | Kiro only supports stdio transport | ## Overwrite behavior during conversion | Content Type | Strategy | Rationale | |---|---|---| | Generated agents (JSON + prompt) | Overwrite | Generated, not user-authored | | Generated skills (from commands) | Overwrite | Generated, not user-authored | | Copied skills (pass-through) | Overwrite | Plugin is source of truth | | Steering files | Overwrite | Generated from `AGENTS.md` when present, otherwise `CLAUDE.md` | | `mcp.json` | Merge with backup | User may have added their own servers | | User-created agents/skills | Preserved | Don't delete orphans | --- ## File: docs/specs/opencode.md # OpenCode Spec (Config, Agents, Plugins) Last verified: 2026-04-19 ## Primary sources ``` 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. - 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. - `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. - 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. - 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/`. - 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//SKILL.md` - `~/.config/opencode/skills//SKILL.md` - `.claude/skills//SKILL.md` - `~/.claude/skills//SKILL.md` - `.agents/skills//SKILL.md` - `~/.agents/skills//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//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/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 - 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.