# Cross-harness capability matrix

claude-agents is a multi-harness plugin marketplace. Source-of-truth lives under `plugins/`
as Claude Code markdown. Per-harness artifacts are generated by adapters under `tools/adapters/`.

> This file mirrors the capability matrix in `tools/adapters/capabilities.py`. Edit there;
> regenerate via `make docs`.

## Supported harnesses

| Harness | Status | Generated paths |
|---|---|---|
| **Claude Code** | source-of-truth | `plugins/`, `.claude-plugin/marketplace.json` |
| **OpenAI Codex CLI** | supported | committed: `.agents/plugins/marketplace.json`, `plugins/*/.codex-plugin/plugin.json`; gitignored: `.codex/skills/`, `.codex/agents/` |
| **Cursor** (2.5+) | supported | committed: `.cursor-plugin/`, `.cursor/rules/` (curated) — points at source `plugins/` |
| **OpenCode** (`sst/opencode`) | supported | gitignored: `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/`, `opencode.json` |
| **Gemini CLI** | supported | committed: `gemini-extension.json`; gitignored: `skills/`, `agents/`, `commands/` (at extension root) |

## Capability matrix

| Capability | Claude Code | Codex | Cursor | OpenCode | Gemini |
|---|---|---|---|---|---|
| Skills (SKILL.md native) | ✅ | ✅ | ✅ via `.claude/` | ✅ via `.opencode/skills/` | ✅ (auto-discovered) |
| Subagents (markdown native) | ✅ | TOML format | ✅ via `.claude/` | ✅ (different frontmatter) | ✅ (April 2026 spec) |
| Slash commands | ✅ | converted to skills | ✅ | ✅ | TOML at `commands/` |
| Plugin marketplace | ✅ | — | ✅ (2.5+) | — | — (direct URL install) |
| Parallel subagents | ✅ | ✅ | ✅ | ✅ | ✅ (April 2026) |
| Per-agent tool allowlist | ✅ (`tools:`) | only `sandbox_mode` | only `readonly:` | ✅ (`permission:` block) | ✅ (`tools:`) |
| `TodoWrite` tool | ✅ | — | — | ✅ | — |
| `Task`/`Agent` spawn tool | ✅ | name in prose | ✅ | ✅ (`task`) | `@agent` syntax |
| MCP servers | ✅ | ✅ | ✅ | ✅ | ✅ |
| Lifecycle hooks | ✅ | — | — | ✅ (TS plugins) | — |
| Context file | `CLAUDE.md` | `AGENTS.md` (32 KiB cap) | `AGENTS.md` | `AGENTS.md` / `~/.claude/CLAUDE.md` | `GEMINI.md` |
| Context file recommended cap | 150 lines / 500 tokens | 150 lines / 500 tokens | 150 lines / 500 tokens | 150 lines / 500 tokens | 150 lines / 500 tokens |
| Skill body hard cap | none | **8 KB** | none | none | none |
| Tool name case | CamelCase (`Read`) | action verbs (no tool vocab) | lowercase | lowercase (strict) | lowercase (Gemini names) |
| Bare model aliases | ✅ (`fable`/`opus`/`sonnet`/`haiku`) | mapped to GPT-5.x family | use `inherit` | full provider/model-id | mapped to `gemini-2.5-*` |

## Claude Code native features

Claude Code is the source-of-truth harness. It reads the canonical context file via `CLAUDE.md`,
a symlink to `AGENTS.md`. Features it supports that other harnesses degrade or lack:

- **Per-agent tool allowlist** — `tools:` frontmatter honored verbatim (Cursor / Codex are coarser; the OpenCode adapter translates this into a `permission:` block).
- **`Task` / `Agent` spawn tool** — fan-out parallel subagent execution. (Codex requires naming an agent in prose to delegate.)
- **`TodoWrite`** — native progress tracking. (Not available in Codex / Cursor / Gemini.)
- **Slash-command marketplace** — full `/plugin install`, `/plugin marketplace` workflow.

Claude-Code-only paths:

- `.claude-plugin/marketplace.json` — plugin registry (source of truth)
- `plugins/<name>/.claude-plugin/plugin.json` — per-plugin manifest

## Graceful degradation

Each adapter handles incompatibilities mechanically — authors don't need to know the per-harness
rules to write portable content.

| Source pattern | Codex | Cursor | OpenCode | Gemini |
|---|---|---|---|---|
| `tools: Read, Grep` (agent allowlist) | dropped; `sandbox_mode = "read-only"` heuristic | dropped (Cursor doesn't honor) | converted to `permission:` deny block | passed through |
| `color: blue` (agent) | dropped | dropped | dropped | dropped |
| `model: opus` (agent) | mapped to `gpt-5.5` | rewritten to `inherit` | rewritten to `anthropic/claude-opus-4-8` | mapped to `gemini-2.5-pro` |
| `model: fable` (agent) | mapped to `gpt-5.5` | rewritten to `inherit` | rewritten to `anthropic/claude-fable-5` | mapped to `gemini-2.5-pro` |
| `TodoWrite` in body | no equivalent — leave as-is | no equivalent — leave as-is | works as-is | no equivalent |
| Skill body > 8 KB | split into `references/details.md` | passed through | passed through | passed through |
| Agent named `worker` | namespaced to `<plugin>__worker` | passed through | passed through | passed through |
| Slash command (`commands/<x>.md`) | converted to skill | passed through | rewritten to `.opencode/commands/` | TOML at `commands/<plugin>/<x>.toml` |

## Output paths (committed vs gitignored)

Native install is **lean**: only small JSON registries (pointing at the source `plugins/`) are
committed. The large transformed skill/agent trees stay gitignored — regenerate them locally.

**Committed:**

```
.claude-plugin/marketplace.json        # SOURCE OF TRUTH
plugins/                               # SOURCE OF TRUTH
AGENTS.md                              # canonical context file
.agents/plugins/marketplace.json       # Codex marketplace registry (source.path: ./plugins/<name>)
plugins/*/.codex-plugin/plugin.json    # per-plugin Codex manifest (skills: ./skills/)
.cursor-plugin/, .cursor/rules/        # Cursor marketplace + curated rules (point at source)
gemini-extension.json                  # Gemini extension manifest (contextFileName: AGENTS.md)
```

**Gitignored (regenerate with `make generate`):**

```
.codex/skills/, .codex/agents/         # transformed Codex trees (for ~/.codex/skills symlink recipe)
.opencode/agents/, .opencode/commands/, .opencode/skills/, opencode.json
skills/, agents/, commands/            # Gemini trees at extension root (not for OpenCode install)
.copilot/agents/, .copilot/skills/, .copilot/commands/
```

## Native install

- **Codex** — `npx codex-marketplace add wshobson/agents` (or it's auto-discovered as a project
  marketplace when the repo is the cwd), then install individual plugins. Codex reads `SKILL.md`
  straight from `plugins/<name>/skills/`; skills over the 8 KB cap are truncated by Codex at load.
  The gitignored `.codex/skills/` copies remain for the `~/.codex/skills` symlink recipe.
- **Cursor** — add the marketplace, then `/plugin install <name>`. Entries point at source
  `./plugins/<name>`; Cursor reads `SKILL.md` + `.md` agents from source directly.
- **Gemini** — no one-step-from-URL install (the lean tradeoff). Clone the repo, then
  `make generate HARNESS=gemini` and `gemini extensions install .` (local path).
- **OpenCode** — no one-step-from-URL install. Clone the repo, then `make install-opencode`
  (runs generate + symlinks `.opencode/` → `~/.config/opencode/`).

## Regenerating

The committed registries point at source; the transformed trees are regenerated on demand.
Contributors must run `make generate-all` before committing source changes — CI fails on drift
of the committed registries.

```bash
make generate HARNESS=codex
make generate HARNESS=cursor
make generate HARNESS=opencode
make generate HARNESS=gemini
# Or all at once (run before committing source changes):
make generate-all

# Optional global OpenCode install:
make install-opencode
make uninstall-opencode
```

## External Pensyve integrations

The Claude Code marketplace includes Pensyve as an external `git-subdir` plugin.
For generated harnesses, use Pensyve's upstream harness-native integration:

| Harness | Upstream integration |
|---|---|
| Claude Code | `https://github.com/major7apps/pensyve.git`, path `integrations/claude-code` |
| Codex CLI | `integrations/codex-plugin` |
| Cursor | `integrations/cursor` |
| OpenCode | `integrations/opencode-plugin` |
| Gemini CLI | `gemini extensions install https://github.com/major7apps/pensyve` |
| Copilot | `.copilot/` (repo-level) or `~/.copilot/` (global install via `make install-copilot`) |

## Global install

OpenCode and Copilot support installing generated artifacts globally for user-level discovery:

```bash
make install-opencode    # symlink .opencode/ → ~/.config/opencode/
make uninstall-opencode

make install-copilot     # symlink .copilot/ → ~/.copilot/
make uninstall-copilot

# Force-replace conflicting symlinks:
make install-copilot FORCE=1
```

> Copilot discovers agents from `.copilot/agents/` and skills from `.copilot/skills/` at the repo level, and from `~/.copilot/agents/` and `~/.copilot/skills/` at the user level. The adapter emits to `.copilot/`; use `make install-copilot` for user-level discovery.

## See also

- [`authoring.md`](authoring.md) — portable-content style guide for plugin authors
- [`architecture.md`](architecture.md) — overall design principles
- [`plugin-eval.md`](plugin-eval.md) — the `harness_portability` scoring dimension