69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# 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.
|