Files
opencode-primer/CONTRIBUTING.md
Wesam Abousaid ccac453cdb chore(oss): add OSS infrastructure — CoC, security, contributing, CI
Community and contributor support:
- CONTRIBUTING.md: what we welcome, what we don't, style guide,
  templates for MCP walkthroughs and specialized-agent prompts.
- CODE_OF_CONDUCT.md: Contributor Covenant 2.1.
- SECURITY.md: scope (this is a docs repo, not application code), how
  to report a vulnerability in the example plugins or in misleading
  documentation, where OpenCode-core bugs should go instead.

GitHub plumbing:
- .github/PULL_REQUEST_TEMPLATE.md: type, sources, hygiene checklist.
- .github/ISSUE_TEMPLATE/{bug_report,feature_request}.md and config.yml
  that redirects OpenCode-tool issues to the right place.
- .github/workflows/lint-docs.yml: three jobs on every push and PR —
  markdownlint, link check (with sensible ignore patterns for
  ../../issues, security advisories, localhost), codespell with a
  project-specific ignore list.

Lint/style configs:
- .markdownlint.json + .markdownlintignore: ATX headings, ordered list
  numbering, line-length and inline-HTML rules tuned for our content.
- .editorconfig: LF, UTF-8, 2-space indent, trim trailing whitespace
  except in markdown (where trailing spaces are line breaks).
2026-05-18 20:00:51 +02:00

4.0 KiB
Raw Permalink Blame History

Contributing

Thank you for considering a contribution. This repo is a community-maintained guide to OpenCode — every typo fix, fact correction, and new example helps the next reader.

What we welcome

Contribution What's helpful
Fact corrections OpenCode moves fast. If something here is out of date, fix it and cite the source.
New MCP walkthroughs A short page in mcp-servers/ with verified setup steps, example prompts, and gotchas.
New specialized-agent prompts A new role under specialized-agents/system-prompts/ + a one-page description.
Better examples Real-world patterns that worked for you.
Typo and grammar fixes Just send the PR.
Image / diagram contributions Drop PNG/SVG in Images/ and reference them inline.

What we don't accept

  • Unverified claims. Every factual statement must trace back to opencode.ai/docs, the OpenCode GitHub repo, or a primary source. No "I heard that…".
  • Marketing language. This guide is practical, not a sales pitch.
  • Affiliate links or sponsored content without prior agreement.
  • AI-generated content that hasn't been read and verified by you. If you used an AI to draft, that's fine — but read it carefully, fact-check, and remove fluff before submitting.

How to contribute

  1. Open an issue first for non-trivial changes (new sections, restructuring) so we can align on scope.
  2. Fork → branch → PR. One topic per PR; smaller is better.
  3. Match the existing style. See AGENTS.md for style conventions (markdown, tone, link form).
  4. Cite your sources. If you're updating a fact, include a link to the source in the PR description.
  5. Update the "Last reviewed" date at the bottom of the README if you've made material changes.

Style basics

  • Short lines, plain English.
  • Lead with the mental model, then the syntax, then the example.
  • Comparison tables when there's a choice to make.
  • Code fences with language tags. JSON examples should be valid opencode.json snippets.
  • Emoji callouts: > 💡 Pro Tip, > ⚠️ Warning, > 🆕 New, > 📚 Further reading.

Tips for adding a new MCP walkthrough

A good walkthrough has:

  1. When to reach for it — one-line use case
  2. Setup — exact JSON snippet for opencode.json and any auth steps
  3. Example prompts — 2–3 realistic prompts (not "hello world")
  4. What it can do / won't do — set expectations
  5. Gotchas — things you wish you'd known
  6. Resources — links to the upstream project

See mcp-servers/playwright.md as a template.

Tips for adding a new specialized-agent prompt

A good system prompt has:

  1. Frontmatter with description, mode, model, temperature, permission — use the format in docs/agents.md.
  2. Principles — 3–5 numbered, prescriptive items. What the agent prioritizes.
  3. Workflow — concrete steps the agent should follow.
  4. Defaults — the stack and tools the agent uses.
  5. What I won't do — explicit constraints. This is what makes specialized agents different from a generic LLM.
  6. Communication style — how the agent talks (terse, surfaces trade-offs, etc.).

Add the matching short description under specialized-agents/descriptions/ and update the table in specialized-agents/README.md.

Local check

There's no build system to run, but a quick mental checklist before submitting:

  • All links resolve (in-page anchors and external URLs)
  • Code fences have language tags
  • No trailing whitespace
  • No emoji clutter
  • Facts cite a source

Questions

Open a GitHub Discussion or an issue. Drive-by PRs are welcome too — we'll suggest changes in review.


Thanks for making this resource better.