Skip to content

Contributing

Versioning

  • Each plugin has independent versioning in its own plugin.json.
  • Adding a skill to an existing plugin is a plugin minor bump; compatible updates to existing capabilities are plugin patch bumps.
  • Adding a new plugin is a marketplace minor bump (0.x.0).
  • Adding or updating a skill within an existing plugin is a marketplace patch bump (0.x.y).
  • plugins/project/bin/project-bump-version keeps Claude, Codex, Copilot, and marketplace declarations synchronized for ordinary version bumps. A skill added within an existing plugin uses the helper's cascading marketplace patch bump.

Releases and citation

  • The marketplace version lives in .claude-plugin/marketplace.json and .github/plugin/marketplace.json (the Codex .agents/plugins/marketplace.json carries no top-level version).
  • GitHub release tags mirror the marketplace top-level version: marketplace 0.15.13 gets tag v0.15.13, not a separately incrementing release sequence.
  • The repository is archived to Zenodo on every GitHub release, minting a versioned DOI under a stable concept DOI. When the marketplace version bumps for a release, CITATION.cff's version and date-released fields get bumped alongside it, and .zenodo.json stays in sync.
  • The concept DOI (in CITATION.cff's doi: field and the README badge) is stable across versions and does not change.

Development conventions

  • Detailed project rules live in .rules/; check the relevant rule file before changing manifests, skills, agents, tests, CI, or language tooling.
  • Use Bun for JavaScript/TypeScript work; see .rules/javascript.md.
  • Use UV for Python work (this docs site included); see .rules/python.md.
  • No mocks in tests; see .rules/testing.md.
  • No emojis in commits or code; see .rules/git.md.

Run the contributor validation gate

Run the same deterministic gate used by pull-request CI before opening a PR:

./scripts/validate

It checks plugin shell-script syntax, runs the full filesystem-backed test suite (including manifest, skill, installer, and figure checks), and builds the documentation with strict link validation. The separate CI typo job still uses typos; install and run it locally when changing substantial prose.

Cross-agent compatibility

Any plugin update must check Claude Code, Codex, and GitHub Copilot CLI manifests and install paths together; see Cross-Agent Compatibility for the researched registration paths, and .rules/cross-agent-compatibility.md for the update policy itself.

Building these docs locally

uv sync --group docs
uv run mkdocs serve   # http://127.0.0.1:8000/
uv run mkdocs build --strict

CI builds and deploys this site to the gh-pages branch on every push to main that touches docs/**, mkdocs.yml, or pyproject.toml. Run mkdocs build --strict locally before pushing; it fails on any broken nav entry or image link, which is the easiest way to catch a typo'd path.

Adding to these docs

A new plugin gets a page at docs/plugins/<name>.md following the same skeleton every existing plugin page uses, in this order:

  1. # Title and a one-paragraph intro (what the plugin does, in plain terms).
  2. All of the plugin's workflow sections, one to three of them, each pairing a short explanation with one diagram, if a diagram exists that illustrates that workflow well. Not every section needs one; presentation.md has none.
  3. ## Skills, after every workflow section, not interleaved with them: every skill in the plugin, one bullet each, one line of accurate description. Pull the wording from README.md's existing plugin section rather than re-describing from scratch, so the two don't drift.
  4. ## Try it: a fenced code block of 2-4 realistic example prompts (or commands, for project), taken from or matching the README's examples.
  5. ## Learn more: a link to the matching Agentic Research Course week, if one exists; otherwise say so plainly (see presentation.md).

Then add the page to mkdocs.yml's nav.Plugins list; nav entries are manual, not auto-discovered.

New diagrams go in docs/assets/diagrams/ as flat files (no subfolders) and get referenced with a path relative to the current page's depth: assets/diagrams/foo.svg from a top-level page like index.md, ../assets/diagrams/foo.svg from a page under docs/plugins/. mkdocs build --strict catches a wrong relative depth immediately.

If a diagram is reused from an external repo (as the current set is, from agentic-research-course), copy it rather than symlinking, since a separate repo's files aren't guaranteed to stay at that path, and caption it based on what it actually depicts, not what the surrounding prose would like it to depict. When no existing diagram fits a new section well, prose-only is preferable to a mismatched image.