mirror of https://github.com/wshobson/agents synced 2026-06-21 14:13:58 +00:00

Files

T

Seth Hobson 608c3840ca feat: native plugin-install for Codex/Cursor/Gemini + CLAUDE.md→AGENTS.md symlink

Add lean, native plugin-install entry points so each harness's own plugin
manager can install this marketplace (mirroring obra/superpowers) — committing
only small JSON registries, not duplicated skill/agent content trees.

- Codex: committed marketplace registry (.agents/plugins/marketplace.json) +
  per-plugin manifests (plugins/*/.codex-plugin/plugin.json). Entries point at
  source ./plugins/<name>; Codex reads SKILL.md directly. Transformed
  .codex/skills|agents stay gitignored.
- Cursor: commit the existing .cursor-plugin/ marketplace + .cursor/rules/
  (these already point at source plugins/).
- Gemini: gemini-extension.json already committed (contextFileName: AGENTS.md);
  transformed trees stay gitignored (install via clone + make generate).
- OpenCode: unchanged — install via `make install-opencode` (transformed tree
  stays gitignored).
- CLAUDE.md is now a symlink to AGENTS.md; Claude-Code addenda moved to
  docs/harnesses.md.
- CI: new step fails if `make generate-all` drifts from the committed registries.

Net new committed: ~720 KB of manifests (no skill/agent duplication). Adds
round-trip tests for the new registries + the symlink. Docs updated across
README, docs/harnesses.md, ARCHITECTURE.md, CONTRIBUTING.md, GEMINI.md,
docs/authoring.md, and the PR template.

2026-05-29 13:02:40 -04:00

3.2 KiB

Raw Permalink Blame History

Contributing to claude-agents

Thanks for your interest in contributing. This marketplace ships to six agentic harnesses (Claude Code, OpenAI Codex CLI, Cursor, OpenCode, Gemini CLI, GitHub Copilot) from a single Markdown source.

Start here

AGENTS.md — canonical context (table of contents)
ARCHITECTURE.md — top-level architectural map
docs/authoring.md — portable-content style guide (read this before adding new components)
docs/harnesses.md — per-harness capability matrix
docs/plugin-eval.md — quality evaluation framework

Adding a plugin

Create plugins/<name>/ with .claude-plugin/plugin.json.
Add agents in agents/, commands in commands/, skills in skills/.
Update .claude-plugin/marketplace.json with your entry.
Naming: lowercase, hyphen-separated. Never use __ (the adapter namespace separator).
Run make generate-all to refresh the committed native-install registries (CI gates registry drift).
Run make validate and make garden to surface any issues before submitting.

Full frontmatter conventions in docs/authoring.md.

Quality gates

Every PR runs these on CI (.github/workflows/); run them locally before pushing:

make validate STRICT=1     # structural validation across all harness outputs
make garden STRICT=1       # drift, dead-link, stale-artifact detection
make test                  # full pytest suite (plugin-eval + tools/tests/)
make smoke-test            # real-CLI subprocess tests (OpenCode, Gemini, Codex, Claude)

Code-quality checks (also in CI):

cd plugins/plugin-eval
uv run ruff check ../../tools/ src/plugin_eval/
uv run ruff format --check ../../tools/ src/plugin_eval/
uv run ty check ../../tools/ src/plugin_eval/

Cross-harness portability checklist

Your content ships to five harnesses — some have stricter conventions than Claude Code:

Codex hard-truncates skill bodies at 8 KB. Keep SKILL.md short; push detail into references/details.md.
OpenCode requires lowercase tool names. Don't write `Read` inline — write "open the file" or use the lowercase form.
Cursor doesn't honor per-agent tools: allowlists — use it as a hint only.
Copilot maps Claude model aliases (opus/sonnet/haiku) to the GPT-5 family; agent description must be a plain string.
All harnesses use ≤150-line context files. Don't bloat AGENTS.md / CLAUDE.md.

plugin-eval's harness_portability dimension catches most of these mechanically; read docs/authoring.md for the full guide.

Workflow

Open an issue first (template-driven). Use the appropriate issue template.
Fork the repo, branch from main.
Make changes; run quality gates.
Open a PR referencing the issue.
CI must pass; reviewers approve; squash merge.

Reporting

Bugs / features / new components: use the GitHub issue templates.
Code of Conduct violations: see .github/CODE_OF_CONDUCT.md.
Discussions: https://github.com/wshobson/agents/discussions.

3.2 KiB Raw Permalink Blame History