1---2name: opencode-config3description: Author and modify OpenCode config in this repository — opencode.json, agents, skills, commands, permissions. Use when editing opencode.json, adding or changing an agent, writing a skill or command, adjusting model routing/permissions, or the task mentions "opencode config", "agent prompt", "SKILL.md", "command", or "permission".4---56# OpenCode Config Authoring7For generic opencode config shapes, see the built-in `customize-opencode` skill;8this file only covers this repository's local conventions.910## Repository layout11| Path | Role |12| --- | --- |13| `opencode.jsonc` | Global config: model, permissions, plugins, agents, commands, compaction |14| `AGENTS.md` | Global rules auto-loaded into every agent's context |15| `agents/<name>.md` | One custom agent per file (frontmatter + system prompt) |16| `skills/<name>/SKILL.md` | On-demand skills, auto-discovered from the config dir |1718## Hard constraints19- Only `deepseek/deepseek-v4-pro` and the natively multimodal `deepseek/deepseek-flash`. Never a third model; flash handles both text and visual input.20- Use the singular keys (`plugin`, `snapshot`), not the fork's plural (`plugins`, `snapshots`).2122## Config key shapes (authoritative)23- **references** — alias → `{"repository" | "path", "branch"?, "description"?}`. `repository` takes a Git URL / host-path / `owner/repo` (+ `branch` to pin a ref); `path` takes relative / absolute / `~/`; `description` tells agents *when* to use it. String shorthand (`"alias": "../docs"`) allowed.24- **skills.paths** — extra skill dirs: `"skills": { "paths": ["../shared-skills"] }`; supports `~/` and relative paths; `skills.urls` pulls remote skills.25- **agent (inline)** — override built-ins or define agents inline in `opencode.jsonc`: `"agent": { "build": { "model": "…", "mode": "subagent" } }`. Inline keys override file-based `agents/<name>.md`.26- **compaction** — `{ "auto": bool, "prune": bool, "reserved": number }` (defaults: `auto` true, `prune` false). `reserved` is the token buffer kept to avoid overflow during compaction.27- **Environment escape hatches** — `OPENCODE_CONFIG_DIR` points at a custom config dir (searched like `.opencode`, loaded after it so it *overrides*); `OPENCODE_CONFIG` points at a single custom config file (loaded between global and project).2829## Agent frontmatter (`agents/<name>.md`)30| Key | Convention |31| --- | --- |32| `name` | kebab-case, matches filename |33| `description` | When to use this agent (drives routing + @-menu) |34| `mode` | `primary` \| `subagent` |35| `model` | `deepseek/deepseek-v4-pro` \| `deepseek/deepseek-flash` (natively multimodal) |36| `steps` | step budget; heavier agents get more |37| `color` | "#RRGGBB" |38| `hidden` | optional: hide from @-menu |39| `permission` | optional tool locks; read-only agents (`oracle`, `reviewer`, `explore`, `librarian`) must set `edit: deny` + read-only bash whitelist |4041- Each prompt references `AGENTS.md` (not restating it) plus a short Model Leverage (pro) / Model Awareness (flash) note.4243## Skill file format (`skills/<name>/SKILL.md`)44- One folder per skill; file must be `SKILL.md` (uppercase).45- Frontmatter requires `name` (kebab-case, matches folder) and `description` stating **what** and **when**, front-loading trigger keywords.46- Names must be unique across all sources (this repo + `superpowers`); check collisions before naming.4748## Commands (`opencode.json` → `command`)49```jsonc50"command": {51 "name": {52 "description": "Shown in the command menu",53 "agent": "<agent name>",54 "template": "Instruction sent as the user message."55 }56}57```5859- `template` inlines live shell output with `!`, run at invocation and injected:60 ```jsonc61 "template": "Current status:\n!`git status --short`\nNow stage and commit."62 ```6364## Permissions (`opencode.json` → `permission`)65- Default-allow, deny the dangerous: `deny` `.env*` reads (except `.env.example`); `ask` on destructive bash (`rm -rf`, `git push -f`, `git reset --hard`, PowerShell/cmd equivalents) and `external_directory`. Cover shell variants (Unix + Windows) so guards can't be bypassed.6667## Before you finish681. Re-read every changed file end-to-end.692. Run `node scripts/validate-jsonc.js` to validate JSONC syntax (strips comments + trailing commas, parses as JSON).703. Keep `README.md` in sync — agent, skills, and command tables, repo-structure tree.714. Confirm no third model slipped in and no new dependency/plugin without justification.
znlgis