opencode-architect 0.2.4 → 0.4.0

package/assets/agents/opencode-tool-builder.md

@@ -1,5 +1,5 @@
 ---
-description: Creates OpenCode custom tools with schemas and execution logic
+description: Creates OpenCode custom tools in .opencode/tools - Zod schemas and execute logic
 mode: subagent
 tools:
   read: true
@@ -10,28 +10,24 @@ tools:
   bash: false
 ---
 
-If available, prefer Exa MCP over default websearch tools. If available, prefer grepai MCP over default codebase search tools.
+Prefer Exa MCP over default websearch tools and grepai MCP over default codebase search tools, when available.
 
-You create custom tools in '.opencode/tools/' using TypeScript or JavaScript.
+You create custom tools in `.opencode/tools/` using TypeScript or JavaScript.
 
-Tool essentials
+## Essentials
 
-- Use tool() from '@opencode-ai/plugin'.
-- Define args with tool.schema (Zod).
-- Export default tool or multiple named exports.
-- Multiple exports become '<filename>_<exportname>' tool names.
+- Define tools with tool() from '@opencode-ai/plugin'; declare arguments with tool.schema (Zod).
+- Export a default tool or multiple named exports; multiple exports register as '<filename>_<exportname>'.
+- The execution context provides agent, sessionID, messageID, directory, worktree; use context.worktree for repo-root paths.
 
-Execution context
+## References usage
 
-- Context provides agent, sessionID, messageID, directory, worktree.
-- Use context.worktree for repo-root paths.
+Bundled reference files are addressed relative to this agent file's own directory:
 
-Deliverables
+- Use `../references/tools.md` for tool structure, exports, and built-in tool behavior and permissions.
 
-- Create or update tool files.
-- Keep tools narrowly scoped and documented.
+## Live knowledge fallback
 
-Docs usage
+For anything beyond the bundled references, query the deepwiki MCP tools (read_wiki_structure, read_wiki_contents, ask_question) against repo 'anomalyco/opencode' when available; otherwise run 'npx defuddle <url>' on the relevant opencode.ai/docs page if you have a way to execute commands. Degrade gracefully: when neither source is available, rely on the bundled references and your own knowledge - never block on live lookups.
 
-- Use '~/.cache/opencode/opencode-architect/docs/custom-tools.md' for tool structure and exports.
-- Use '~/.cache/opencode/opencode-architect/docs/tools.md' for built-in tool behavior and permissions.
+Done when the tool registers under the expected name, its schema validates every argument, and its scope is narrow: one tool purpose per file.

package/assets/references/agents.md

@@ -0,0 +1,68 @@
+# OpenCode agents — fundamentals
+
+Agents are markdown-defined AI assistants. Locations (plural directory names):
+
+- Project: `.opencode/agents/`
+- Global: `~/.config/opencode/agents/`
+
+The filename becomes the agent name (`review.md` → `review` agent). The markdown body is the system prompt.
+
+## Types
+
+- `primary` — main assistant the user interacts with (Tab to cycle).
+- `subagent` — invoked by primary agents via the Task tool or by `@` mention.
+- `all` — both: usable as primary and invokable as subagent (the default mode).
+
+## Frontmatter fields
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `description` | yes | What the agent does and when to use it. Drives subagent selection. |
+| `mode` | no | `primary`, `subagent`, or `all` (default `all`). |
+| `model` | no | `provider/model-id` (e.g. `anthropic/claude-sonnet-4-5`). Unset: primary uses the configured global model; subagents inherit the invoking agent's model. |
+| `temperature` | no | 0.0–1.0. Low (0.0–0.2) focused/deterministic; high (0.6+) creative. Model-specific defaults apply if unset. |
+| `steps` | no | Max agentic iterations before forced text-only summary. `maxSteps` is deprecated. |
+| `tools` | no | **Deprecated** boolean map (`write: false`, `bash: false`, `mymcp_*: false`). Prefer `permission`. |
+| `permission` | no | Allow/ask/deny control, per key or per glob pattern (see below). |
+| `hidden` | no | `true` hides a `subagent` from the `@` menu; still invokable via Task tool. |
+| `disable` | no | `true` disables the agent. |
+| `color` | no | Hex (e.g. `#ff6b6b`) or theme color (`primary`, `accent`, ...). |
+| `top_p` | no | Alternative randomness control, 0.0–1.0. |
+| other keys | no | Passed through to the provider as model options (e.g. `reasoningEffort`). |
+
+## Permissions
+
+Values: `"allow"`, `"ask"`, `"deny"`. Either shorthand or an object of glob/pattern → action.
+
+Keys: `read`, `edit`, `glob`, `grep`, `list`, `bash`, `task`, `webfetch`, `websearch`, `external_directory`, `todowrite`, `skill`, `lsp`, `question`, `doom_loop`.
+
+- `edit` gates all file modifications: `write`, `edit`, `apply_patch`.
+- `todowrite` gates `todowrite` and `todoread`.
+- Shorthand-only keys: `webfetch`, `websearch`, `external_directory`, `question`, `doom_loop`, `lsp` (also accepts patterns — check schema when in doubt).
+
+Bash command scoping (last matching rule wins; put `*` first, specific rules after):
+
+```yaml
+permission:
+  bash:
+    "*": ask
+    "git status *": allow
+    "git push": ask
+  webfetch: deny
+```
+
+Task (subagent) scoping with globs — denied subagents are removed from the Task tool description:
+
+```yaml
+permission:
+  task:
+    "*": deny
+    "orchestrator-*": allow
+    "code-reviewer": ask
+```
+
+Users can always invoke any subagent directly via `@` regardless of task permissions.
+
+## JSON alternative
+
+Agents can also be configured under the `agent` key in `opencode.json` with the same options plus `prompt` (inline string or `{file:./path}` relative to the config file). Markdown files are preferred for readability.

package/assets/references/commands.md

@@ -0,0 +1,49 @@
+# OpenCode commands — fundamentals
+
+Custom commands are prompt templates invoked as `/name` in the TUI, in addition to built-ins (`/init`, `/undo`, `/redo`, `/share`, `/help`).
+
+Locations:
+
+- Project: `.opencode/commands/`
+- Global: `~/.config/opencode/commands/`
+
+The filename becomes the command name (`test.md` → `/test`).
+
+## Markdown format
+
+The frontmatter defines properties; the body is the prompt template.
+
+```markdown
+---
+description: Run tests with coverage
+agent: build
+model: anthropic/claude-haiku-4-5
+---
+
+Run the full test suite with coverage report and show any failures.
+Focus on the failing tests and suggest fixes.
+```
+
+## Frontmatter keys
+
+| Key | Required | Notes |
+| --- | --- | --- |
+| `description` | no* | Shown in the TUI command list. |
+| `template` | no* | The prompt (JSON config only; in markdown the body is the template). |
+| `agent` | no | Which agent executes it. Defaults to the current agent. |
+| `model` | no | Overrides the default model. |
+| `subtask` | no | `true` forces a subagent invocation (keeps primary context clean), even for `primary`-mode agents. |
+
+*In JSON config (`command.<name>` in `opencode.json`), `template` is required and `description` identifies the command.
+
+## Template features
+
+- `$ARGUMENTS` — full argument string: `/component Button` → `Button`.
+- `$1`, `$2`, `$3` — positional args: `/create-file config.json src "content"` → `$1`=`config.json`, `$2`=`src`, `$3`=`content`.
+- `` !`command` `` — inject shell output into the prompt (runs in the project root), e.g. ``!`git log --oneline -10` ``.
+- `@path/to/file` — include file content in the prompt.
+
+## Notes
+
+- A custom command with the same name as a built-in overrides it.
+- Keep prompts concise and task-focused; the template is the whole instruction the model receives.

package/assets/references/config.md

@@ -0,0 +1,50 @@
+# OpenCode config — fundamentals
+
+OpenCode is configured with `opencode.json` (or `.jsonc`). Schema: `https://opencode.ai/config.json`. TUI settings live in a separate `tui.json` (`https://opencode.ai/tui.json`).
+
+## Locations and precedence
+
+Configs are **merged, not replaced**; later sources override earlier ones only for conflicting keys:
+
+1. Remote config (`.well-known/opencode`, organizational defaults)
+2. Global config (`~/.config/opencode/opencode.json`)
+3. Custom config (`OPENCODE_CONFIG` env var)
+4. Project config (`opencode.json` at project root, searched up to the git root)
+5. `.opencode/` directories (agents, commands, plugins, skills, tools)
+6. Inline config (`OPENCODE_CONFIG_CONTENT` env var)
+7. Managed files (`/etc/opencode/`, `%ProgramData%\opencode`, macOS app support) and macOS MDM preferences — highest, not user-overridable
+
+So: defaults/remote < global < project; managed settings override everything.
+
+## Key schema options
+
+| Key | Purpose |
+| --- | --- |
+| `model` | Default model, `provider/model-id`. |
+| `small_model` | Cheap model for lightweight tasks (titles, summaries). |
+| `provider` | Provider config; `options` supports `timeout`, `headerTimeout`, `chunkTimeout`. |
+| `enabled_providers` / `disabled_providers` | Provider allowlist/blocklist (`disabled_providers` wins). |
+| `agent` | Inline agent definitions; `default_agent` picks the default primary agent. |
+| `command` | Inline command definitions (`template`, `description`, `agent`, `model`). |
+| `mode` | Inline mode/agent-group definitions. |
+| `mcp` | MCP server config (see mcp-servers reference). |
+| `plugin` | npm plugin packages to load. |
+| `tools` | Global tool enable/disable map with globs (`"write": false`). |
+| `permission` | Global `allow`/`ask`/`deny` map (see agents reference for keys). |
+| `instructions` | Extra instruction files/globs (e.g. `["CONTRIBUTING.md", "docs/rules/*.md"]`). |
+| `lsp` | LSP servers (`true` for defaults, or object with per-server overrides). |
+| `formatter` | Formatters (`true` for defaults, or object; custom: `command`, `extensions`, `environment`). |
+| `keybinds` | TUI shortcuts (in `tui.json`; merged with defaults). |
+| `share` | `"manual"` (default) / `"auto"` / `"disabled"`. |
+| `autoupdate` | `true` / `false` / `"notify"`. |
+| `snapshot` | `false` disables undo snapshots. |
+| `compaction` | `{ auto, prune, reserved }` context compaction behavior. |
+| `watcher` | `{ ignore: [globs] }` file watcher exclusions. |
+| `server` | `port`, `hostname`, `mdns`, `cors` for `opencode serve`/`web`. |
+| `shell` | Shell for interactive terminal and tool calls (e.g. `pwsh`). |
+| `subagent_depth` | Subagent nesting depth (default 1; 0 disables subagents). |
+| `experimental` | Options under active development (e.g. `policies`). |
+
+## Directory conventions
+
+`.opencode/` and `~/.config/opencode/` use **plural** subdirectory names: `agents/`, `commands/`, `plugins/`, `skills/`, `tools/`, `themes/` (singular accepted for backwards compatibility). Configs are safe to check into git; `prompt` paths in agent config resolve relative to the config file.

package/assets/references/mcp-servers.md

@@ -0,0 +1,55 @@
+# OpenCode MCP servers — fundamentals
+
+MCP (Model Context Protocol) servers add external tools alongside built-ins. Configure them under the `mcp` key in `opencode.json` with a unique name per server.
+
+Caution: MCP tools add to context — enable only what you need.
+
+## Local servers
+
+```json
+{
+  "mcp": {
+    "my-local-mcp": {
+      "type": "local",
+      "command": ["npx", "-y", "my-mcp-command"],
+      "enabled": true,
+      "environment": { "MY_ENV_VAR": "value" }
+    }
+  }
+}
+```
+
+Options: `type` (required, `"local"`), `command` (required array), `cwd`, `environment`, `enabled`, `timeout` (ms to fetch tools, default 5000).
+
+## Remote servers
+
+```json
+{
+  "mcp": {
+    "my-remote-mcp": {
+      "type": "remote",
+      "url": "https://mcp.example.com/mcp",
+      "enabled": true,
+      "headers": { "Authorization": "Bearer {env:MY_API_KEY}" }
+    }
+  }
+}
+```
+
+Options: `type` (required, `"remote"`), `url` (required), `headers`, `oauth`, `enabled`, `timeout`.
+
+## OAuth (remote)
+
+- Automatic: OpenCode detects the 401, runs the OAuth flow (dynamic client registration, RFC 7591), and stores tokens. No config needed for most servers.
+- Pre-registered credentials: `"oauth": { "clientId": "...", "clientSecret": "...", "scope": "tools:read" }` (use `{env:VAR}` for secrets).
+- `"oauth": false` disables auto-OAuth (e.g. API-key servers).
+- CLI: `opencode mcp auth <name>`, `opencode mcp list`, `opencode mcp logout <name>`, `opencode mcp debug <name>`.
+
+## Tool scoping
+
+MCP tools register as `<servername>_<toolname>`, so glob patterns control them like any tool:
+
+- Disable globally: `"tools": { "my-mcp*": false }` or via permission `"my-mcp_*": "ask"` (permission patterns match built-ins, custom tools, and MCP tools alike).
+- Enable per agent only: disable globally in `tools`, then set `"tools": { "my-mcp*": true }` inside the agent's config.
+- Glob syntax: `*` (any chars), `?` (one char); last matching permission rule wins.
+- Per-server enable/disable: `"enabled": false` on the server entry hides all its tools without deleting config.

package/assets/references/opencode-architect-oneshots.md

@@ -34,27 +34,19 @@ Reference examples for routing decisions. Each shows: request → analysis → a
 **Execution:**
 1. Single: `opencode-mcp-integrator` - configure server in opencode.json with permission rules
 
-**Config produced:**
+**Config produced** (disable the tools globally, enable them for `build` only):
 ```json
 {
   "mcp": {
     "my-company-tools": {
-      "command": "npx",
-      "args": ["-y", "@my-company/mcp-server"]
-    }
-  },
-  "permission": {
-    "tool": {
-      "deploy-*": "deny"
+      "type": "local",
+      "command": ["npx", "-y", "@my-company/mcp-server"]
     }
   },
+  "tools": { "deploy-*": false },
   "agent": {
     "build": {
-      "permission": {
-        "tool": {
-          "deploy-*": "allow"
-        }
-      }
+      "tools": { "deploy-*": true }
     }
   }
 }
@@ -116,23 +108,18 @@ export const CommitValidatorPlugin = async (ctx) => {
 **Execution:**
 1. Single: `opencode-agent-designer` - create agent frontmatter
 
-**Agent structure:**
+**Agent structure** (`.opencode/agents/pr-reviewer.md`; the filename becomes the agent name):
 ```markdown
 ---
-name: pr-reviewer
 description: Review pull requests with security and quality focus
-tools:
-  bash: false
-  write: false
-  edit: false
-  github: true
-  read: true
-  grep: true
-  glob: true
+mode: subagent
+model: anthropic/claude-sonnet-4-5
 permission:
+  bash: deny
+  edit: deny
+  "github_*": allow
   skill:
-    "git-release": "allow"
-model: anthropic/claude-3.5-sonnet
+    "git-release": allow
 ---
 
 ## Role
@@ -144,6 +131,8 @@ Review PRs for code quality, security vulnerabilities, and test coverage.
 3. Provide structured feedback
 ```
 
+`read`/`grep`/`glob` need no entry (tools are enabled by default); `edit` denies `write` and `apply_patch` too.
+
 ---
 
 ## Example 5: Multi-Component Plugin Package
@@ -175,18 +164,14 @@ opencode-devtools/
 
 ---
 
-## Example 6: Local-Only Session Notification Plugin (plugin-engineer, NOT packager)
+## Example 6: Local-Only Session Notification Plugin (plugin-engineer)
 
 **User Request:**
 > Create a plugin that sends a desktop notification when a session completes or errors. This is for my local machine only, not for publishing.
 
 **Analysis:**
 - Plugin with event hooks → `opencode-plugin-engineer`
-- **NOT** packager because:
-  - No npm distribution needed
-  - No skills or commands to bundle
-  - Single local plugin file, not a package
-  - User explicitly said "local machine only"
+- Local machine only, single plugin file → `opencode-plugin-engineer` (distribution intent is the packager test; see the table below)
 
 **Execution:**
 1. Single: `opencode-plugin-engineer` - create local plugin with event hooks
@@ -214,23 +199,17 @@ export const SessionNotifyPlugin: Plugin = async ({ $ }) => {
 | Local-only plugin                    | Local package for sharing          |
 | Event hooks / behavior modification  | Bundling skills + commands as assets|
 | Single `.ts`/`.js` file              | Full package structure with package.json |
-| No distribution intent              | Intended for local file:// sharing |
-| Injecting env vars, notifications    | Combining multiple opencode artifacts |
+| Single-machine use                   | Local file:// sharing across projects |
 
 ---
 
-## Example 7: Plugin with Embedded Static Instructions (plugin-engineer, NOT packager)
+## Example 7: Plugin with Embedded Static Instructions (plugin-engineer)
 
 **User Request:**
 > Create a customer support plugin that injects a "support-agent" prompt into sessions. The prompt should be embedded in the plugin file itself, not as separate files.
 
 **Analysis:**
-- Plugin that injects static content → `opencode-plugin-engineer`
-- **NOT** packager because:
-  - Instructions are embedded as string literals in code
-  - No separate `.md` files to bundle
-  - Content is generated/managed programmatically within the plugin
-  - Not a distributable asset package
+- Prompt embedded as a string literal in the plugin file, managed programmatically at runtime → `opencode-plugin-engineer`
 
 **Execution:**
 1. Single: `opencode-plugin-engineer` - create plugin with embedded prompt string
@@ -270,24 +249,6 @@ export const SupportAgentPlugin: Plugin = async ({ client }) => {
 | Instructions embedded as string in code          | Separate `.md` files as assets     |
 | Content generated programmatically               | Static markdown files to distribute|
 | Single file contains logic + content             | Package structure with multiple files |
-| Runtime-generated prompts                        | Pre-authored skill/command files  |
-| Agent definitions with inline prompts            | Skill SKILL.md + command .md bundles |
-
-**Real-world pattern (reference):**
-```typescript
-// Agent with embedded prompt - NO separate .md files
-export const agent: AgentConfig = {
-  name: "data-analyzer",
-  prompt: `
-    Analyze data files and produce reports.
-    
-    ## Steps
-    1. Read input files
-    2. Parse and validate
-    3. Generate summary statistics
-  `
-}
-```
 
 ---
 

package/assets/references/plugins.md

@@ -0,0 +1,76 @@
+# OpenCode plugins — fundamentals
+
+Plugins are JS/TS modules that hook into OpenCode events and customize behavior.
+
+Locations:
+
+- Project: `.opencode/plugins/`
+- Global: `~/.config/opencode/plugins/`
+
+Files in these directories load automatically at startup. npm packages can be loaded via the `plugin` array in `opencode.json`. Load order: global config → project config → global plugin dir → project plugin dir.
+
+## Plugin shape
+
+A plugin exports one or more async functions. Each receives a context and returns a hooks object:
+
+```ts
+import type { Plugin } from "@opencode-ai/plugin"
+
+export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
+  return {
+    // hook implementations
+  }
+}
+```
+
+Context: `project` (project info), `directory` (cwd), `worktree` (git worktree root), `client` (opencode SDK client), `$` (Bun shell API).
+
+## Config hooks
+
+Returning a `tool` object adds custom tools; a plugin tool that shares a built-in tool's name takes precedence:
+
+```ts
+import { type Plugin, tool } from "@opencode-ai/plugin"
+
+export const CustomToolsPlugin: Plugin = async (ctx) => {
+  return {
+    tool: {
+      mytool: tool({
+        description: "What the tool does",
+        args: { foo: tool.schema.string() },
+        async execute(args, context) {
+          const { directory, worktree } = context
+          return `Hello ${args.foo} from ${directory}`
+        },
+      }),
+    },
+  }
+}
+```
+
+## Event hooks
+
+Hooks are named event handlers: `"<event>": async (input, output) => { ... }`.
+
+Key events:
+
+- Commands: `command.executed`
+- Files: `file.edited`, `file.watcher.updated`
+- Messages: `message.updated`, `message.part.updated`, `message.part.removed`, `message.removed`
+- Permissions: `permission.asked`, `permission.replied`
+- Sessions: `session.created`, `session.idle`, `session.updated`, `session.error`, `session.compacted`, `session.deleted`, `session.diff`, `session.status`
+- Tools: `tool.execute.before`, `tool.execute.after`
+- Shell: `shell.env`
+- TUI: `tui.prompt.append`, `tui.command.execute`, `tui.toast.show`
+- Other: `installation.updated`, `lsp.client.diagnostics`, `lsp.updated`, `server.connected`, `todo.updated`
+
+A catch-all `event: async ({ event }) => {...}` hook receives every event (`event.type` switches on it).
+
+`tool.execute.before` can inspect/modify `output.args` or throw to block; `shell.env` mutates `output.env`.
+
+Compaction hook `experimental.session.compacting` can append via `output.context.push(...)` or fully replace the prompt via `output.prompt`.
+
+## Dependencies and logging
+
+- Local plugins can use npm packages: add a `package.json` to the config directory (`.opencode/package.json`); OpenCode runs `bun install` at startup.
+- Prefer structured logging via `client.app.log({ body: { service, level, message, extra } })` over `console.log`. Levels: `debug`, `info`, `warn`, `error`.

package/assets/references/prompt-engineering.md

@@ -0,0 +1,46 @@
+# Prompt engineering — distilled best practices
+
+Distilled from Anthropic's Claude prompting best practices and skill-authoring best practices. Apply to agent prompts, skill bodies, and command templates.
+
+## Core principles
+
+- **Be clear and direct.** State the desired output, format, and constraints explicitly. If you want above-and-beyond behavior, ask for it. The colleague test: could someone with minimal context follow your prompt?
+- **Explain why.** Give context/motivation for rules ("never use ellipses because a TTS engine reads this aloud"). The model generalizes from the explanation.
+- **Sequence matters.** Use numbered steps or bullets when order or completeness matters. Put critical instructions at the end of long prompts.
+- **Give a role.** A one-sentence persona in the system prompt focuses tone and behavior ("You are a code reviewer focused on security...").
+
+## Examples and structure
+
+- Few-shot examples (3–5) are the most reliable way to steer format, tone, and structure. Make them relevant, diverse, and wrapped in tags (`<example>` inside `<examples>`).
+- Use XML tags to separate instructions, context, documents, and inputs in complex prompts (`<instructions>`, `<context>`, `<documents>`). Consistent, descriptive tag names.
+- Long context: put longform data near the top and the query/instructions at the end; wrap each document in `<document>` tags with metadata; ask the model to quote relevant passages before answering.
+
+## Output control
+
+- Say what to do, not what not to do ("write flowing prose paragraphs" beats "don't use bullets").
+- Match your prompt's style to the desired output style (markdown-heavy prompts yield markdown-heavy answers).
+- Use structured outputs (JSON/XML schemas) when precise parsing is needed; request verbatim structure with an explicit template.
+
+## Tool use and agentic behavior
+
+- Models may suggest instead of act. Be explicit: "Change this function" vs "Can you suggest changes". Prompt blocks can set a default-to-action or do-not-act bias.
+- Independent tool calls can run in parallel; this is steerable ("make all independent calls in parallel" / "execute sequentially").
+- Prefer general guidance over aggressive over-prompting ("Use this tool when..." beats "CRITICAL: you MUST..."). Over-instruction causes overtriggering.
+- Self-check: "Before you finish, verify your answer against the criteria" catches errors; ask for it only when quality demands it.
+- Guard rails for agents: confirm before irreversible or shared-system actions; avoid over-engineering (only requested changes, no speculative abstractions); investigate files before answering (never speculate about unread code); write general solutions, don't hardcode to tests.
+- Subagents: use for parallelizable, context-isolated workstreams; work directly for simple sequential tasks.
+
+## Skill and instruction authoring
+
+- **Concise is key** — the context window is a public good. Only add context the model doesn't already have; make every paragraph justify its tokens.
+- **Set degrees of freedom** to match fragility: high freedom (heuristics) for flexible tasks; low freedom (exact scripts, "do not modify this command") for fragile operations.
+- **Descriptions drive selection**: third person, what it does + when to use it, with specific trigger terms. Avoid vague names (`helper`, `utils`) and vague descriptions.
+- **Progressive disclosure**: overview in the main file; details in separately linked files, one level deep (nested references cause partial reads). Table of contents for files over 100 lines.
+- **Workflows and feedback loops**: numbered steps with copy-paste checklists for complex tasks; validate → fix → repeat loops for quality-critical operations; create verifiable intermediate outputs before destructive or batch operations.
+- **Stability**: no time-sensitive information; consistent terminology (pick one term per concept); avoid Windows-style paths — always forward slashes.
+- **Provide a default, not a menu**: one recommended approach with an escape hatch for exceptions, not five equivalent options.
+
+## Iteration
+
+- Test with real tasks and observe how the instructions are actually navigated; iterate on observed failures, not assumptions.
+- Build evaluations before extensive documentation: identify gaps, write minimal instructions to close them, measure against baseline.

package/assets/references/skills.md

@@ -0,0 +1,55 @@
+# OpenCode skills — fundamentals
+
+Skills are reusable instruction packages discovered on-demand via the native `skill` tool. Agents see each skill's name and description in `<available_skills>` and load the full SKILL.md only when relevant.
+
+Locations (one folder per skill):
+
+- Project: `.opencode/skills/<name>/SKILL.md`
+- Global: `~/.config/opencode/skills/<name>/SKILL.md`
+- Compatible paths: `.claude/skills/<name>/SKILL.md`, `.agents/skills/<name>/SKILL.md` (project and home variants)
+
+## Frontmatter rules
+
+Only these fields are recognized; unknown fields are ignored:
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `name` | yes | 1–64 chars, lowercase alphanumeric with single hyphens (`^[a-z0-9]+(-[a-z0-9]+)*$`), no leading/trailing `-`, no `--`, must match the folder name. |
+| `description` | yes | 1–1024 chars. Third person; state what the skill does AND when to use it. This drives skill selection — be specific and include key trigger terms. |
+| `license` | no | e.g. `MIT`. |
+| `compatibility` | no | e.g. `opencode`. |
+| `metadata` | no | String-to-string map. |
+
+If a skill does not show up: verify `SKILL.md` capitalization, required frontmatter, unique names across locations, and that permissions don't `deny` it.
+
+## Progressive disclosure
+
+- Metadata (name + description) is pre-loaded at startup; the body is read on demand; bundled files are read only as needed — no context penalty until accessed.
+- Keep SKILL.md under ~500 lines; split deeper content into separate files.
+- Default assumption: the model is already smart — only add context it doesn't have.
+
+## Co-located references pattern
+
+Bundle detail files next to SKILL.md in the skill folder:
+
+```
+my-skill/
+├── SKILL.md          # overview + navigation (loaded when triggered)
+├── reference.md      # loaded as needed
+├── examples.md       # loaded as needed
+└── scripts/tool.py   # executed, not loaded
+```
+
+- Keep references **one level deep** from SKILL.md — nested references cause partial reads. Link each file directly from SKILL.md.
+- Add a table of contents at the top of reference files over 100 lines.
+- Make execution intent explicit: "Run `scripts/foo.py`" (execute) vs "See `scripts/foo.py`" (read as reference).
+
+## Base-directory convention
+
+Address co-located files **relative to the skill's own directory** (its base directory), always with **forward slashes** (`reference/guide.md`, not `reference\guide.md` or absolute paths). Forward-slash relative paths work on every platform.
+
+## Authoring quick rules
+
+- General authoring rules (degrees of freedom, workflows, defaults, terminology): see `prompt-engineering.md`.
+- Gerund names read well (`processing-pdfs`); vague names (`helper`, `utils`) hide the skill from selection.
+- Gate access with `permission.skill` glob patterns (`"internal-*": "deny"`); disable entirely with `tools: { skill: false }`.

package/assets/references/tools.md

@@ -0,0 +1,49 @@
+# OpenCode tools — fundamentals
+
+By default all tools are enabled and need no permission to run. Control them via the `permission` config (global or per agent).
+
+## Built-in tools
+
+| Tool | Purpose | Permission key |
+| --- | --- | --- |
+| `bash` | Execute shell commands | `bash` |
+| `read` | Read files (supports line ranges) | `read` |
+| `edit` | Exact string replacement in files | `edit` |
+| `write` | Create/overwrite files | `edit` |
+| `apply_patch` | Apply patch files | `edit` |
+| `grep` | Regex content search | `grep` |
+| `glob` | File pattern matching | `glob` |
+| `skill` | Load a SKILL.md | `skill` |
+| `todowrite` | Task lists (disabled for subagents by default) | `todowrite` |
+| `webfetch` | Fetch a URL | `webfetch` |
+| `websearch` | Web search (provider/env gated) | `websearch` |
+| `question` | Ask the user structured questions | `question` |
+| `lsp` | LSP intelligence (experimental) | `lsp` |
+
+`edit`, `write`, and `apply_patch` share the single `edit` permission. `grep`/`glob` use ripgrep and respect `.gitignore` (a `.ignore` file can re-include paths). Hooks must check `input.tool === "apply_patch"` and use `output.args.patchText` (paths embedded in marker lines).
+
+## Custom tools
+
+Defined in `.opencode/tools/` (project) or `~/.config/opencode/tools/` (global). The filename becomes the tool name (`database.ts` → `database` tool).
+
+```ts
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Query the project database",
+  args: {
+    query: tool.schema.string().describe("SQL query to execute"),
+  },
+  async execute(args, context) {
+    return `Executed: ${args.query}`
+  },
+})
+```
+
+Key API points:
+
+- `tool.schema` is Zod (`tool.schema.string()`, `.number()`, `.describe(...)`); or import `zod` directly and export a plain object.
+- `execute(args, context)` — context provides `agent`, `sessionID`, `messageID`, `directory` (session cwd), `worktree` (git worktree root). Use `context.worktree` for repo-root paths.
+- Multiple named exports in one file become separate tools named `<filename>_<exportname>` (`math_add`, `math_multiply`).
+- A custom tool with a built-in tool's name overrides it (prefer unique names; use permissions to just disable).
+- The definition is TS/JS, but `execute` can invoke scripts in any language (e.g. via `Bun.$`).