Two files, one repository
wshobson/agents ships 3 formats across 5 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 8 | 3 | 0% |
| Commands | 0 | 10 | 0 | 0% |
| Section tags | 2 | 4 | 0 | 33% |
What each file covers
Sections
0 shared · 8 only in A · 3 only in B- − claude-agents — multi-harness agentic plugin marketplace
- − Map
- − Working in this repo
- − Quality gates (run these before pushing)
- − Regenerating per-harness artifacts
- − Skills (cross-harness)
- − Subagents (cross-harness)
- − Why this file is short
- + Authoring portable plugin content
- + Frontmatter
- + Body
Commands
0 shared · 10 only in A · 0 only in B- − make validate STRICT=1
- − make garden
- − make test
- − make smoke-test
- − make generate HARNESS=codex
- − make generate HARNESS=cursor
- − make generate HARNESS=opencode
- − make generate HARNESS=gemini
- − make generate-all
- − task
Section tags
2 shared · 4 only in A · 0 only in B- − test
- − lint-format
- − do-not
- − agent-behaviour
- code-style
- security
Line diff
wshobson/agents · AGENTS.md
@@ −1 @@
1# claude-agents — multi-harness agentic plugin marketplace
2
3Production-ready agentic-workflow building blocks: **94 plugins** (90 local + 4 external), **203 agents**, **175 skills**, **109 commands**. Native source-of-truth for Claude Code; also consumed by OpenAI Codex CLI, Cursor, OpenCode, and Gemini CLI from a single Markdown source.
4
5This file is the canonical context file. Codex / Cursor / OpenCode read it directly. Claude Code reads it via `CLAUDE.md`, a symlink to this file. Gemini CLI reads it via `gemini-extension.json` (`contextFileName`) / `.gemini/settings.json`.
6
7> **Read this file like a table of contents.** Detail lives in `docs/`. Authoring conventions live in `docs/authoring.md`. Per-harness setup and capability deltas live in [`docs/harnesses.md`](docs/harnesses.md). Gemini-specific setup is in `GEMINI.md` (also auto-loaded by Gemini CLI). This file should never grow beyond ~150 lines (per OpenAI's [harness-engineering](https://openai.com/index/harness-engineering/) practice).
8
9## Map
10
11- **[ARCHITECTURE.md](ARCHITECTURE.md)** — top-level architectural overview (adapter framework, source-of-truth invariant, capability matrix summary)
12- **[docs/architecture.md](docs/architecture.md)** — detailed design principles
13- **[docs/plugins.md](docs/plugins.md)** — full plugin catalog (94 plugins by category)
14- **[docs/agents.md](docs/agents.md)** — agent reference (203 agents, model tiers)
15- **[docs/agent-skills.md](docs/agent-skills.md)** — skill reference (progressive disclosure model)
16- **[docs/usage.md](docs/usage.md)** — commands, workflows, examples
17- **[docs/authoring.md](docs/authoring.md)** — portable-content style guide (read before adding plugins)
18- **[docs/harnesses.md](docs/harnesses.md)** — per-harness capability matrix
19- **[docs/plugin-eval.md](docs/plugin-eval.md)** — three-layer quality evaluation framework
20- **[docs/round-trip-results.md](docs/round-trip-results.md)** — real-CLI verification recipes
21- **[CONTRIBUTING.md](CONTRIBUTING.md)** — how to contribute
22
23## Working in this repo
24
25- Python tooling: **uv** (package manager), **ruff** (lint/format), **ty** (type check). Do not use pip / mypy / black.
26- Plugins live under `plugins/<name>/` with auto-discovery — see `docs/authoring.md` for frontmatter shapes.
27- Plugin names: lowercase, hyphen-separated. Never use `__` (it's the adapter namespace separator).
28- Never commit secrets. Never run destructive git (force-push, `reset --hard`, branch -D) without explicit ask.
29
30## Quality gates (run these before pushing)
31
32```bash
33make validate STRICT=1 # structural validation across all harness outputs
34make garden # drift detection (dead links, stale artifacts, oversize skills)
35make test # full pytest suite (plugin-eval + tools/tests/)
36make smoke-test # real-CLI subprocess tests against generated artifacts
37```
38
39CI (`.github/workflows/validate.yml`) runs all four on every PR plus installs OpenCode + Gemini CLI for live verification.
40
41## Regenerating per-harness artifacts
42
43```bash
44make generate HARNESS=codex # .codex/skills, .codex/agents, .codex/plugins/<p>/, .agents/plugins/marketplace.json
45make generate HARNESS=cursor # .cursor-plugin/{marketplace,plugin}.json, .cursor/rules/
46make generate HARNESS=opencode # .opencode/{skills,agents,commands,plugins}/, opencode.json
47make generate HARNESS=gemini # skills/, agents/, commands/ at extension root
48make generate-all # all four
49```
50
51Generated artifacts are **committed** so each harness installs natively from a clone / GitHub URL (native-install commands in [`docs/harnesses.md`](docs/harnesses.md)). Run `make generate-all` before committing source changes — CI fails on drift. Source-of-truth lives only under `plugins/`; never hand-edit generated files.
52
53## Skills (cross-harness)
54
55175 skills under `plugins/*/skills/<n>/SKILL.md` — discoverable by every harness:
56
57- **Claude Code**: auto-discovery via Anthropic's SKILL.md spec
58- **Codex CLI**: mirrored to `.codex/skills/<plugin>__<skill>/` (8 KB body cap; detail in `references/details.md`)
59- **OpenCode**: mirrored to `.opencode/skills/<plugin>-<skill>/` using hyphenated names for global install
60- **Cursor**: reads `.claude/skills/` directly (no re-emit)
61- **Gemini CLI**: native skills at `skills/<plugin>__<skill>/SKILL.md`
62
63Top-level `skills/` is Gemini output; do not use it for OpenCode installs.
64
65## Subagents (cross-harness)
66
67203 subagents under `plugins/*/agents/<name>.md`. Per-harness transpilation:
68
69- **Codex**: `.codex/agents/<plugin>__<agent>.toml` (drop `tools:`, map model alias to the GPT-5.x family, infer `sandbox_mode`)
70- **OpenCode**: `.opencode/agents/<plugin>__<agent>.md` with `mode: subagent` + `permission:` block (locked agents — those with source `tools: []` — get deny-everything except base `skill`/`task`)
71- **Gemini**: `agents/<plugin>__<agent>.md` (April 2026 subagent spec)
72- **Cursor**: reads `.claude/agents/` directly
73
74## Why this file is short
75
76Per OpenAI's harness-engineering practice: this file is a **map**, not an encyclopedia. Procedural detail lives in skills (loaded on demand by agents). Reference material lives in `docs/` (loaded when an agent navigates). A single bloated AGENTS.md crowds out the task, rots quickly, and is hard to verify mechanically. Keep it lean; push detail elsewhere.
77
wshobson/agents · .cursor/rules/020-agent-skill-authoring.mdc
@@ +1 @@
1---
2description: Authoring agent, skill, and command markdown for cross-harness portability
3globs: ["plugins/*/agents/*.md", "plugins/*/skills/*/SKILL.md", "plugins/*/commands/*.md"]
4---
5
6# Authoring portable plugin content
7
8This content ships to Claude Code, Codex CLI, Cursor, OpenCode, and Gemini CLI. The adapter
9framework handles per-harness mechanics, but content choices affect portability.
10
11## Frontmatter
12
13- Agents: `name`, `description` (with "Use when…" trigger), `model: opus|sonnet|haiku|inherit`, optional `tools:`, optional `color:`.
14- Skills: `name`, `description`. Other Anthropic SKILL.md fields are optional and respected only on Claude Code.
15- Commands: `description`, `argument-hint`.
16
17## Body
18
19- Use action verbs, not tool-name vocabulary: prefer *"open the file"* over *"use the Read tool"*. The adapter rewrites a conservative set, but the unrewritten cases bleed through.
20- Cap skill body at ~8 KB. Push longer reference material into `skills/<name>/references/` files. Codex will hard-truncate at 8 KB anyway.
21- Don't name agents `default`, `worker`, or `explorer` — they collide with Codex built-ins.
22- Don't reference `TodoWrite`, the `Task` spawn tool, or hooks as load-bearing — they don't exist in Codex or Cursor.
23
24See `docs/authoring.md` for the full guide.
25
@@ −1 +1 @@
1−# claude-agents — multi-harness agentic plugin marketplace
1+---
2+description: Authoring agent, skill, and command markdown for cross-harness portability
3+globs: ["plugins/*/agents/*.md", "plugins/*/skills/*/SKILL.md", "plugins/*/commands/*.md"]
4+---
25
3−Production-ready agentic-workflow building blocks: **94 plugins** (90 local + 4 external), **203 agents**, **175 skills**, **109 commands**. Native source-of-truth for Claude Code; also consumed by OpenAI Codex CLI, Cursor, OpenCode, and Gemini CLI from a single Markdown source.
6+# Authoring portable plugin content
47
5−This file is the canonical context file. Codex / Cursor / OpenCode read it directly. Claude Code reads it via `CLAUDE.md`, a symlink to this file. Gemini CLI reads it via `gemini-extension.json` (`contextFileName`) / `.gemini/settings.json`.
8+This content ships to Claude Code, Codex CLI, Cursor, OpenCode, and Gemini CLI. The adapter
9+framework handles per-harness mechanics, but content choices affect portability.
610
7−> **Read this file like a table of contents.** Detail lives in `docs/`. Authoring conventions live in `docs/authoring.md`. Per-harness setup and capability deltas live in [`docs/harnesses.md`](docs/harnesses.md). Gemini-specific setup is in `GEMINI.md` (also auto-loaded by Gemini CLI). This file should never grow beyond ~150 lines (per OpenAI's [harness-engineering](https://openai.com/index/harness-engineering/) practice).
11+## Frontmatter
812
9−## Map
13+- Agents: `name`, `description` (with "Use when…" trigger), `model: opus|sonnet|haiku|inherit`, optional `tools:`, optional `color:`.
14+- Skills: `name`, `description`. Other Anthropic SKILL.md fields are optional and respected only on Claude Code.
15+- Commands: `description`, `argument-hint`.
1016
11−- **[ARCHITECTURE.md](ARCHITECTURE.md)** — top-level architectural overview (adapter framework, source-of-truth invariant, capability matrix summary)
12−- **[docs/architecture.md](docs/architecture.md)** — detailed design principles
13−- **[docs/plugins.md](docs/plugins.md)** — full plugin catalog (94 plugins by category)
14−- **[docs/agents.md](docs/agents.md)** — agent reference (203 agents, model tiers)
15−- **[docs/agent-skills.md](docs/agent-skills.md)** — skill reference (progressive disclosure model)
16−- **[docs/usage.md](docs/usage.md)** — commands, workflows, examples
17−- **[docs/authoring.md](docs/authoring.md)** — portable-content style guide (read before adding plugins)
18−- **[docs/harnesses.md](docs/harnesses.md)** — per-harness capability matrix
19−- **[docs/plugin-eval.md](docs/plugin-eval.md)** — three-layer quality evaluation framework
20−- **[docs/round-trip-results.md](docs/round-trip-results.md)** — real-CLI verification recipes
21−- **[CONTRIBUTING.md](CONTRIBUTING.md)** — how to contribute
17+## Body
2218
23−## Working in this repo
19+- Use action verbs, not tool-name vocabulary: prefer *"open the file"* over *"use the Read tool"*. The adapter rewrites a conservative set, but the unrewritten cases bleed through.
20+- Cap skill body at ~8 KB. Push longer reference material into `skills/<name>/references/` files. Codex will hard-truncate at 8 KB anyway.
21+- Don't name agents `default`, `worker`, or `explorer` — they collide with Codex built-ins.
22+- Don't reference `TodoWrite`, the `Task` spawn tool, or hooks as load-bearing — they don't exist in Codex or Cursor.
2423
25−- Python tooling: **uv** (package manager), **ruff** (lint/format), **ty** (type check). Do not use pip / mypy / black.
26−- Plugins live under `plugins/<name>/` with auto-discovery — see `docs/authoring.md` for frontmatter shapes.
27−- Plugin names: lowercase, hyphen-separated. Never use `__` (it's the adapter namespace separator).
28−- Never commit secrets. Never run destructive git (force-push, `reset --hard`, branch -D) without explicit ask.
29−
30−## Quality gates (run these before pushing)
31−
32−```bash
33−make validate STRICT=1 # structural validation across all harness outputs
34−make garden # drift detection (dead links, stale artifacts, oversize skills)
35−make test # full pytest suite (plugin-eval + tools/tests/)
36−make smoke-test # real-CLI subprocess tests against generated artifacts
37−```
38−
39−CI (`.github/workflows/validate.yml`) runs all four on every PR plus installs OpenCode + Gemini CLI for live verification.
40−
41−## Regenerating per-harness artifacts
42−
43−```bash
44−make generate HARNESS=codex # .codex/skills, .codex/agents, .codex/plugins/<p>/, .agents/plugins/marketplace.json
45−make generate HARNESS=cursor # .cursor-plugin/{marketplace,plugin}.json, .cursor/rules/
46−make generate HARNESS=opencode # .opencode/{skills,agents,commands,plugins}/, opencode.json
47−make generate HARNESS=gemini # skills/, agents/, commands/ at extension root
48−make generate-all # all four
49−```
50−
51−Generated artifacts are **committed** so each harness installs natively from a clone / GitHub URL (native-install commands in [`docs/harnesses.md`](docs/harnesses.md)). Run `make generate-all` before committing source changes — CI fails on drift. Source-of-truth lives only under `plugins/`; never hand-edit generated files.
52−
53−## Skills (cross-harness)
54−
55−175 skills under `plugins/*/skills/<n>/SKILL.md` — discoverable by every harness:
56−
57−- **Claude Code**: auto-discovery via Anthropic's SKILL.md spec
58−- **Codex CLI**: mirrored to `.codex/skills/<plugin>__<skill>/` (8 KB body cap; detail in `references/details.md`)
59−- **OpenCode**: mirrored to `.opencode/skills/<plugin>-<skill>/` using hyphenated names for global install
60−- **Cursor**: reads `.claude/skills/` directly (no re-emit)
61−- **Gemini CLI**: native skills at `skills/<plugin>__<skill>/SKILL.md`
62−
63−Top-level `skills/` is Gemini output; do not use it for OpenCode installs.
64−
65−## Subagents (cross-harness)
66−
67−203 subagents under `plugins/*/agents/<name>.md`. Per-harness transpilation:
68−
69−- **Codex**: `.codex/agents/<plugin>__<agent>.toml` (drop `tools:`, map model alias to the GPT-5.x family, infer `sandbox_mode`)
70−- **OpenCode**: `.opencode/agents/<plugin>__<agent>.md` with `mode: subagent` + `permission:` block (locked agents — those with source `tools: []` — get deny-everything except base `skill`/`task`)
71−- **Gemini**: `agents/<plugin>__<agent>.md` (April 2026 subagent spec)
72−- **Cursor**: reads `.claude/agents/` directly
73−
74−## Why this file is short
75−
76−Per OpenAI's harness-engineering practice: this file is a **map**, not an encyclopedia. Procedural detail lives in skills (loaded on demand by agents). Reference material lives in `docs/` (loaded when an agent navigates). A single bloated AGENTS.md crowds out the task, rots quickly, and is hard to verify mechanically. Keep it lean; push detail elsewhere.
24+See `docs/authoring.md` for the full guide.
7725
