awesome-opencode/contributing.md

Contribution Guidelines

Thank you for contributing to awesome-opencode! Every entry is a YAML file under data/; the README and the search site are generated from those files. Never edit README.md directly: PRs that do are rejected by the validate check.

Option 1: the issue form (recommended)

Open an "Add an entry" issue. A bot validates the fields, checks OpenCode V2 compatibility for plugins, comments with the result, and opens the pull request for you. To fix something, edit the issue; the PR updates itself.

Option 2: a pull request

1. Fork and clone the repo, then run npm ci.

2. Create the entry. The scaffolder writes a correctly formatted file and runs the V2 check:

   npm run new -- --category plugins --repo https://github.com/owner/repo \
     --tagline "Short summary" --topics memory,context [--npm package-name] [--path packages/x]
   

   Or write data/<category>/<name>.yaml by hand (kebab-case filename):

   name: Quota Board
   repo: https://github.com/owner/opencode-quota-board
   npm: opencode-quota-board
   tagline: Provider quotas and reset countdowns in the OpenCode sidebar
   description: Adds quota bars, reset countdowns and credit balances to the OpenCode V2 TUI.
   kind: plugin
   topics:
     - cost
     - providers
   compat: v2
   

3. Run npm run validate, then open the PR. CI runs the same checks and comments with anything to fix.

Fields

Field	Required	Notes
name	yes	Max 80 characters
repo	yes	Repository root URL (GitHub, GitLab, Codeberg, Gitee; gists allowed). No /tree/, /blob/, npm pages or websites
path	no	Folder inside a monorepo, e.g. packages/my-plugin
npm	no	Package name; strongly recommended for plugins (used for the V2 check and health checks)
tagline	yes	Max 120 characters. Quote it if it contains : (e.g. tagline: "Plain: no jargon")
description	yes	Max 1500 characters
kind	yes	plugin, theme, agent, skill, mcp-server, client, tool, config, guide or fork
topics	yes	1–3 of: memory, context, orchestration, workflow, providers, cost, notifications, sessions, code-quality, security, git, remote, web, ui, voice, media, docs, environment, observability, integrations, code-intel, prompting, domain. The first is used for README grouping
compat	plugins	v2, v1 or unknown; CI verifies it. Other categories may omit it
also	no	Secondary kinds, e.g. [mcp-server] for a plugin that also ships an MCP server
scope, tags, min_version, homepage, installation	no	See docs/schema-design.md

Unknown fields are rejected, so typos like repository: or install: are caught.

Which category? plugins for OpenCode plugin packages, themes for color themes, agents for agent configs and skill packs, projects for clients, GUIs, MCP servers, tools and forks, resources for guides, configs and starters.

What gets accepted

See the catalog policy. In short:

• Relevant: works with OpenCode.
• Public: the repository is public and not archived.
• V2 for new plugins: depends on @opencode/plugin and uses Plugin.define. V1 plugin PRs are held with the needs-v2 label; a nightly job re-checks them and unblocks the PR automatically once the plugin migrates.
• Unique: one entry per repository (per path for monorepos).
• No crypto: no cryptocurrency, token or trading projects.

What happens after you submit

1. validate check: schema, duplicates, generated-file edits and the V2 check. Required to merge.
2. Triage: a bot labels the PR (ready, needs-v2, needs-metadata or needs-human) and comments with the results.
3. Maintainer review and merge.
4. README, registry and search site regenerate automatically.