wehub-resource-sync
164 lines
8.8 KiB
Markdown
164 lines
8.8 KiB
Markdown
# 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
|