AGENTS.md

What this repository is

This is the user's global opencode configuration directory (~/.config/opencode). It holds the settings, custom agents, and skills that opencode loads for every session on this machine. It is not an application codebase — there is no build, test, or lint step. The "source" is the config itself, and the way to verify a change is to confirm the config still loads (restart opencode).

Layout

opencode.jsonc          Global config: providers, MCP servers, skills path, shell
agent/                  Custom agent definitions (markdown + frontmatter)
  assistant.md          Read-only code Q&A primary agent
skills/                 Custom skills, one folder per skill (each has SKILL.md)
  change-code-review/       Review only the last set of changes
  incremental-implementation/  Deliver changes in thin, verifiable slices
  repo-code-review/         Review the repo in its current state
  resume-coach/             Recruiter-style resume review/rewrite
  simplified-technical-english/  ASD-STE100 controlled-language writing
package.json            Declares @opencode-ai/plugin (pinned version)

node_modules/, package.json, package-lock.json, bun.lock, and .gitignore are listed in .gitignore and are intentionally not tracked.

Editing config (`opencode.jsonc`)

Keep "$schema": "https://opencode.ai/config.json" at the top.
The schema at that URL is the source of truth. Fetch and read it before writing any field not already present; opencode hard-fails on invalid config, so a wrong shape breaks startup.
skills.paths is an object with a paths array, not a bare array.
Config is loaded once at startup and is not hot-reloaded. After changing any config, agent, skill, or plugin file, tell the user to quit and restart opencode.
Never commit secrets. Provider keys and MCP tokens should use {env:VAR} interpolation rather than literals.

Adding or editing agents

File form: agent/<name>.md. The markdown body is the prompt; do not also put prompt: in the frontmatter.
Allowed frontmatter fields: name, model, variant, description, mode, hidden, color, steps, options, permission, disable, temperature, top_p.
mode is one of primary, subagent, all.
Permissions: permission accepts an action string or an object keyed by tool. Within an object the last matching pattern wins, so put broad rules first and narrow rules last.

Adding or editing skills

One folder per skill: skills/<name>/SKILL.md (filename exactly SKILL.md).
Required frontmatter: name (lowercase-hyphenated, matches the folder) and a description that states both what the skill does and when to trigger it, front-loading concrete keywords. Skills without a description are filtered out and never surfaced.
Optional frontmatter: license, compatibility, metadata.
Put long reference material in sibling files (e.g. references/, examples/) and point to them from the body instead of inlining everything.

Style

Markdown. Keep files focused and avoid redundancy.
Do not add comments or content the user did not ask for.

3.1 KiB Raw Permalink Blame History