Files
opencode-primer/AGENTS.md
Wesam Abousaid 7d347eef74 docs: rewrite README and AGENTS.md with verified, balanced content
README
- Match the structure of common practical-guide repos: title, badges,
  install one-liner, "Choose your path", "When to use what" decision
  tree (mermaid) + table, "What's inside" topical map, deep dives,
  Limitations, FAQ, Updates, References.
- Add explicit not-affiliated-with-OpenCode disclaimer per OpenCode's
  own README request for third-party projects using "opencode" in the
  name.
- Add AI-coding caveat (you're still the reviewer, hallucinations are
  real) at the top.
- Add balanced "When OpenCode isn't the right tool" subsection naming
  Claude Code, Cursor, Aider, Copilot, Codeium, Supermaven as better
  fits for specific use cases.
- All factual claims verified against opencode.ai/docs and the JSON
  config schema. Pricing/model table dated 2026-05-18.

AGENTS.md
- Repurpose from generic React boilerplate to actually describe this
  repo: a documentation guide. Includes editing rules, style guide,
  emoji policy, and "when to update what" matrix.
2026-05-18 19:59:14 +02:00

6.3 KiB

AGENTS.md

Project instructions for OpenCode. Read every session.

What this repo is

A practical, opinionated guide to using OpenCode — README, supporting docs, drop-in agent prompts, MCP walkthroughs, and a worked example of a fully-configured .opencode/ directory. It's a documentation repository, not application code.

Repo layout

.
├── README.md                       # Main guide (the centerpiece)
├── AGENTS.md                       # This file
├── CONTRIBUTING.md                 # How to contribute
├── LICENSE                         # MIT
├── docs/
│   ├── quickstart.md               # 5-minute getting-started
│   ├── zen.md                      # Zen model gateway details
│   ├── tui.md                      # TUI mastery
│   ├── agents.md                   # Custom agent deep dive
│   ├── commands.md                 # Custom slash commands
│   ├── skills.md                   # Agent skills
│   ├── plugins.md                  # Plugin/hook system
│   ├── mcp.md                      # MCP integration
│   ├── workflows.md                # Real-world recipes
│   ├── migration.md                # Migration from Claude Code / Cursor
│   ├── faq.md                      # FAQ + troubleshooting
│   └── reference/
│       ├── cli.md                  # All CLI commands
│       ├── slash-commands.md       # All TUI slash commands
│       ├── permissions.md          # Permission model
│       ├── changelog.md            # OpenCode releases
│       └── further-reading.md      # External resources
├── .opencode/
│   ├── agents/                     # Example custom agents
│   ├── commands/                   # Example custom commands
│   └── skills/                     # Example agent skills
├── mcp-servers/                    # MCP server walkthroughs
├── specialized-agents/             # Drop-in specialist prompts
│   ├── system-prompts/             # System prompts (10 roles)
│   └── descriptions/               # Role descriptions
└── Images/                         # Diagrams and screenshots

Editing rules

Always

  • Cite the source. Every factual claim about OpenCode must trace back to opencode.ai/docs, the GitHub repo, or an official release note. Don't paraphrase from memory.
  • Verify version-specific claims. Pricing, model names, commands, and flags change. When in doubt, check the docs page that owns the topic.
  • Use OpenCode's actual terminology. "Custom commands" not "slash skills"; "agents" and "subagents" not "personas"; "plugins" not "hooks" (OpenCode plugins serve the hook role).
  • Match the README's tone. Practical, mental-model-first, prescriptive ("Reach for it when…"). No marketing fluff.
  • Update the Last reviewed date at the bottom of the README when making material changes.

Never

  • Don't invent commands, flags, or features. If you can't verify it, leave it out.
  • Don't hardcode prices without a "verified" date. Always show the date next to any pricing table.
  • Don't add Co-Authored-By lines to commits unless the user asks for them.
  • Don't git push --force to main, ever, without explicit permission.
  • Don't introduce affiliate links or sponsorship blocks without the maintainer's approval.

Style conventions

Markdown

  • One blank line between sections. No trailing whitespace.
  • Code fences with language tags: ```bash, ```json, ```markdown.
  • Internal links use anchor form: [label](#section-id). Anchors are auto-derived from headings (lowercased, spaces → dashes, special chars stripped).
  • Tables: header row, separator row, no leading/trailing pipes. Keep column widths reasonable for desktop reading.
  • Callouts use blockquotes with emoji prefixes:
    • > 💡 **Pro Tip:** … for tips
    • > ⚠️ **Warning:** … for foot-guns
    • > 🆕 … for new features
    • > 📚 … for deeper-reading pointers
  • Emoji policy:
    • OK — one leading emoji on H2 navigation headings (🧭 🧠 📚 📖), and the callout-prefix set above.
    • Not OK — decorative emoji inside prose, in code, or on H3/H4 headings. One per spot, never decorative density.

Code samples

  • JSON examples in this repo are valid opencode.json snippets — paste-ready. Include the $schema line on full-file examples.
  • Shell examples assume a POSIX shell. Use bash fence; quote variables ("$VAR").
  • Markdown front-matter uses YAML with --- fences. Match the exact key spelling from the OpenCode docs (e.g., description, mode, model, permission, tools).

Tone

  • Be concrete. "Reach for it when X" beats "useful for X."
  • Lead with the mental model, then the syntax, then the example.
  • Compare options side-by-side when there's a choice to make (custom commands vs. skills, etc.).
  • Emoji discipline. Allowed: H2 navigation marker, and the callout prefixes listed under "Markdown" above. Not allowed: decoration inside prose or on H3/H4 headings.

Commands

This repo has no build/test stack — it's pure markdown. Useful housekeeping:

# Spell-check (if installed)
codespell README.md docs/

# Find broken internal links
grep -nE '\]\(#[a-z0-9-]+\)' README.md docs/*.md

How OpenCode should work in this repo

  • Default agent: build is fine — edits are local-file-only and easily reversible.
  • No network-dependent tools needed for editing docs. webfetch/websearch are useful only when verifying external claims.
  • Bash: read-only commands (ls, grep, git status, git diff) are safe to auto-allow. Writes (rm, mv, git push) should always require confirmation.

When to update what

Trigger What to update
New OpenCode release docs/reference/changelog.md + version line in README footer
Pricing change Pricing table in README + docs/zen.md, with new "verified" date
New built-in command Slash-command list in README + docs/reference/slash-commands.md
Discovered factual error Fix the source location; grep for repeats

This file is read by OpenCode at every session. Keep it short, accurate, and actionable.