Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
170 lines (126 loc) · 4.59 KB

CONTRIBUTING.md

File metadata and controls

170 lines (126 loc) · 4.59 KB
Raw

Contributing to Docket Curated

This repository is Docket's private plugin marketplace for both Codex and Claude Code. Plugins live under plugins/<name>/ and register in the catalog for whichever host(s) they target.

Host Catalog
Codex CLI .agents/plugins/marketplace.json
Claude Code .claude-plugin/marketplace.json

A plugin can target one host or both. The manifests coexist in the same plugins/<name>/ directory without conflict (.codex-plugin/ vs .claude-plugin/).

Codex plugins

Layout

plugins/<name>/
  .codex-plugin/
    plugin.json        # Codex manifest
  skills/
    <skill-name>/
      SKILL.md         # skill entry point (name + description frontmatter)
  scripts/             # adapter/helper scripts the skill invokes (optional)
  tests/               # plugin tests (optional but expected)
  README.md

See plugins/claude-code/ for a working example.

Manifest (.codex-plugin/plugin.json)

{
  "name": "<name>",
  "version": "0.1.0",
  "description": "One-line description of what the plugin does.",
  "author": { "name": "<your name>" },
  "skills": "./skills/",
  "interface": {
    "displayName": "<Display Name>",
    "shortDescription": "<short summary>",
    "longDescription": "<longer summary>",
    "developerName": "<your name>",
    "category": "Developer Tools",
    "capabilities": ["Interactive"],
    "defaultPrompt": ["Use the <skill-name> skill for this task."]
  }
}

name must match the directory name and the marketplace entry name.

Skill (skills/<skill-name>/SKILL.md)

---
name: <skill-name>
description: One line describing what the skill does and when to use it.
---

# <Title>

Instructions the model follows when the skill is invoked.

Scripts a skill invokes should derive their own absolute path from the loaded SKILL.md location rather than assuming a working directory — see invoke-claude/SKILL.md for the pattern.

Registering in the catalog

Add an entry to .agents/plugins/marketplace.json:

{
  "name": "<name>",
  "source": { "source": "local", "path": "./plugins/<name>" },
  "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
  "category": "Developer Tools"
}

Validate and test

python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/plugin-creator/scripts/validate_plugin.py" plugins/<name>
node --test plugins/<name>/tests/*.test.mjs

Both must pass. Include the output as evidence in the PR.

Claude Code plugins

Layout

plugins/<name>/
  .claude-plugin/
    plugin.json        # Claude Code manifest
  skills/
    <skill-name>/
      SKILL.md         # skill entry point (description frontmatter)
  agents/              # custom subagent definitions (optional)
  hooks/
    hooks.json         # event handlers (optional)
  .mcp.json            # MCP server config (optional)
  README.md

Manifest (.claude-plugin/plugin.json)

{
  "name": "<name>",
  "description": "One-line description of what the plugin does.",
  "version": "1.0.0",
  "author": { "name": "<your name>" }
}

name becomes the skill namespace — e.g., a skill review in plugin my-tool is invoked as /my-tool:review.

Skill (skills/<skill-name>/SKILL.md)

---
description: One line describing what the skill does and when to use it.
---

Instructions the model follows when the skill is invoked.

Registering in the catalog

Add an entry to .claude-plugin/marketplace.json:

{
  "name": "<name>",
  "source": "./plugins/<name>",
  "description": "One-line description."
}

Paths in source resolve relative to the marketplace root (this repo), not the .claude-plugin/ directory.

Validate and test

claude plugin validate plugins/<name>
claude --plugin-dir ./plugins/<name>   # smoke-test locally

Both hosts

A plugin can register in both catalogs. The .codex-plugin/ and .claude-plugin/ directories coexist in the same plugin directory. Add entries to both marketplace.json files and add rows to both tables in README.md.

Commits and PRs

  • Branch off main; do not commit directly to main.
  • Keep changes scoped to one plugin per PR where possible.
  • Bump the plugin's plugin.json version when you change its behavior.
  • PR description should state what changed and include validation/test output.
  • Add a row to the appropriate Available plugins table in README.md.