# 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.