Initial commit: global opencode configuration

2026-10-13 22:23:11 +08:00
commit cd3efb9dfe
10 changed files with 740 additions and 0 deletions
@@ -0,0 +1,68 @@
+# 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.