---
name: oh-my-opencode-slim
description: Configure and improve oh-my-opencode-slim for the current user. Use when users want to tune agents, models, prompts, custom agents, skills, MCPs, presets, or plugin behavior. Also use when recurring workflow friction suggests a safe config or prompt improvement.
---

# oh-my-opencode-slim Configuration Skill

You help users configure, customize, and safely improve their
oh-my-opencode-slim setup.

The goal is not just to answer configuration questions. When useful, help the
user make their agent system better for future runs: tune models, adjust
agent prompts, add focused custom agents, enable or restrict tools, and document
restart requirements.

## When to Use

Use this skill when the user asks about or is likely to benefit from changes to:

- `~/.config/opencode/oh-my-opencode-slim.json` or `.jsonc`
- `.opencode/` or `~/.config/opencode/` plugin/agent configuration
- agent models, variants, presets, or provider routing
- orchestrator delegation behavior or specialist-agent prompts
- custom agents under `agents.<name>`
- custom agent `prompt` and `orchestratorPrompt` blocks
- skills, MCP permissions, tool access, or disabled agents
- background orchestration, session reuse, multiplexer panes, or deepwork
- recurring workflow friction that could be fixed by a prompt/config change

Also use it proactively, with restraint, when a session reveals a repeatable
improvement opportunity. Example: if the user repeatedly asks the same agent to
follow a project-specific rule, suggest adding that rule to a prompt or config.

## What Is Possible

oh-my-opencode-slim is configured through a plugin config file, usually:

```text
~/.config/opencode/oh-my-opencode-slim.json
```

or:

```text
~/.config/opencode/oh-my-opencode-slim.jsonc
```

Concrete files agents should know:

| Path | Use |
|---|---|
| `~/.config/opencode/opencode.json` | OpenCode core config: plugin registration and providers |
| `~/.config/opencode/oh-my-opencode-slim.jsonc` | User plugin config with comments/trailing commas; takes precedence over `.json` |
| `~/.config/opencode/oh-my-opencode-slim.json` | User plugin config generated by installer |
| `<project>/.opencode/oh-my-opencode-slim.json` | Project-local plugin overrides checked before user config |
| `~/.config/opencode/oh-my-opencode-slim/{agent}.md` | Full prompt replacement for a built-in agent |
| `~/.config/opencode/oh-my-opencode-slim/{agent}_append.md` | Append-only prompt tuning for a built-in agent |
| `~/.config/opencode/oh-my-opencode-slim/{preset}/{agent}.md` | Preset-specific full prompt replacement |
| `~/.config/opencode/oh-my-opencode-slim/{preset}/{agent}_append.md` | Preset-specific append-only prompt tuning |
| `~/.config/opencode/skills/<skill-name>/SKILL.md` | Installed skill prompt payload |

Built-in agent prompt file names are exact agent names:

- `orchestrator.md` / `orchestrator_append.md`
- `oracle.md` / `oracle_append.md`
- `librarian.md` / `librarian_append.md`
- `explorer.md` / `explorer_append.md`
- `designer.md` / `designer_append.md`
- `fixer.md` / `fixer_append.md`
- `observer.md` / `observer_append.md`
- `council.md` / `council_append.md`

Prefer `{agent}_append.md` for small behavior tuning. Use `{agent}.md` only when
the user intentionally wants to replace the bundled prompt entirely.

Prompt override lookup order:

1. If a `preset` is active, check
   `~/.config/opencode/oh-my-opencode-slim/{preset}/` first.
2. Fall back to `~/.config/opencode/oh-my-opencode-slim/`.
3. If both `{agent}.md` and `{agent}_append.md` exist, the replacement prompt is
   loaded first and the append file is added after it.
4. If no prompt files exist, the built-in prompt from the plugin package is used.

Common customizations:

- **Switch presets**: choose which generated or custom preset is active.
- **Tune models**: assign different models/variants per agent.
- **Limit costs**: use cheaper models for `explorer`, `librarian`, and `fixer`.
- **Improve quality**: use stronger models for `orchestrator`, `oracle`, or
  design-heavy `designer` work.
- **Control skills**: set `skills` per agent with `['*']`, explicit names, or
  exclusions like `['*', '!codemap']`.
- **Control MCPs**: set `mcps` per agent with the same allow/exclude style.
- **Enable optional agents**: remove agents from `disabled_agents` and configure
  an appropriate model, such as a vision-capable `observer`.
- **Add custom agents**: define focused specialists under `agents.<name>`.
- **Tune prompts**: override or extend an agent's prompt for local workflow
  preferences.
- **Guide delegation**: add `orchestratorPrompt` for custom agents so the
  Orchestrator knows when to call them and when not to.

Important schema boundary:

- Built-in agents (`orchestrator`, `oracle`, `librarian`, `explorer`,
  `designer`, `fixer`, `observer`, `council`) can set models, variants, skills,
  MCPs, options, and display names in config.
- Built-in agent `prompt` and `orchestratorPrompt` fields are **not** supported
  in `oh-my-opencode-slim.json[c]`; use markdown prompt override files instead.
- Unknown keys under top-level `agents` are custom agents. Custom agents may use
  `prompt` and `orchestratorPrompt` directly in config.

## Config Shapes

### Tune a built-in agent model/skills/MCPs

Edit the active preset under `presets.<preset>.<agent>`:

```jsonc
{
  "preset": "openai",
  "presets": {
    "openai": {
      "orchestrator": {
        "model": "openai/gpt-5.6-terra",
        "variant": "high",
        "skills": ["*"],
        "mcps": ["*", "!context7"]
      },
      "librarian": {
        "model": "openai/gpt-5.6-luna",
        "variant": "low",
        "skills": [],
        "mcps": ["websearch", "context7", "gh_grep"]
      }
    }
  }
}
```

### Append instructions to a built-in prompt

Create, for example:

```text
~/.config/opencode/oh-my-opencode-slim/orchestrator_append.md
```

or for only the `openai` preset:

```text
~/.config/opencode/oh-my-opencode-slim/openai/orchestrator_append.md
```

Example content:

```markdown
## Local Orchestrator Preference

- Before spawning parallel writer agents, identify non-overlapping file ownership.
- If file ownership overlaps, ask the user or serialize the work.
```

### Replace a built-in prompt entirely

Create:

```text
~/.config/opencode/oh-my-opencode-slim/orchestrator.md
```

Use this rarely. Full replacements must restate all essential plugin behavior,
because they replace the bundled prompt.

## Safe Improvement Rules

Configuration changes affect future agent behavior, so treat them as user-owned.

1. **Ask before changing config or prompts.**
   - Explain the proposed improvement briefly.
   - State which file would change.
   - Ask for confirmation unless the user explicitly requested the exact edit.
2. **Prefer narrow changes.**
   - Do not rewrite large prompts when a small rule solves the problem.
   - Do not add custom agents for one-off tasks.
3. **Preserve existing user settings.**
   - Merge with current config rather than regenerating from scratch.
   - Keep comments and formatting where practical for JSONC files.
4. **Avoid hidden behavior changes.**
   - Mention cost, permissions, or delegation changes before applying them.
   - Be explicit if a model/provider change may increase spend.
5. **Tell the user about restart requirements.**
   - OpenCode may need a restart for config, prompt, agent, skill, MCP, or plugin
     changes to take effect.
   - Phrase it as: "This should apply on the next OpenCode run; restart OpenCode
     if you need it immediately."

## Configuration Workflow

When making or proposing changes:

1. **Inspect current setup**
   - Read the existing oh-my-opencode-slim config file.
   - Identify active `preset` and relevant agent blocks.
   - Check whether the user has local project `.opencode/` overrides.
2. **Decide the smallest useful change**
   - Model/preset tuning for performance, quality, or cost.
   - Prompt tuning for recurring behavior.
   - Custom agent when a repeatable specialty deserves a separate lane.
   - Skill/MCP permission change when access is too broad or too narrow.
3. **Ask for confirmation**
   - Show a concise proposal.
   - Include the target file path.
4. **Apply the edit carefully**
   - Preserve unrelated settings.
   - Prefer JSONC-compatible output if editing a JSONC file.
   - Keep agent names and skill/MCP names exact.
5. **Validate**
   - Ensure the file remains parseable.
   - Run available config checks if the repository provides them.
6. **Explain activation**
   - Tell the user whether the change applies immediately or on next OpenCode
     run/restart.

## Custom Agent Pattern

Custom agents work best when they are narrow, repeatable, and easy for the
Orchestrator to route.

Use this shape as a starting point:

```jsonc
{
  "agents": {
    "api-reviewer": {
      "model": "openai/gpt-5.6",
      "variant": "high",
      "prompt": "You review API design, compatibility, error semantics, and migration risk. Return concise findings with file references.",
      "orchestratorPrompt": "Delegate to @api-reviewer for API contract changes, public SDK changes, backwards-compatibility questions, or migration-risk review. Do not use it for routine implementation.",
      "skills": [],
      "mcps": []
    }
  }
}
```

Good custom agents have:

- a specific job;
- clear trigger conditions in `orchestratorPrompt`;
- explicit non-use conditions;
- only the skills and MCPs they actually need;
- a model appropriate to the task's judgment/cost needs.

Avoid custom agents that duplicate existing specialists:

- codebase scouting → `explorer`
- external docs/research → `librarian`
- architecture/debugging/review → `oracle`
- UI/UX polish → `designer`
- scoped mechanical implementation → `fixer`

## Prompt Tuning Pattern

Prompt edits are best for recurring behavior that should happen across many
sessions.

Good reasons to tune a prompt:

- The Orchestrator repeatedly delegates too much or too little for this user's
  workflow.
- A specialist repeatedly misses a project-specific convention.
- The user wants a stable communication or verification style.
- The team has a recurring review checklist or deployment rule.

Poor reasons to tune a prompt:

- A one-off task failed once.
- The current problem can be solved by normal instruction in this session.
- The change would make the agent worse for general use.

When suggesting a prompt improvement, say:

```text
I noticed this is recurring. I can add a small rule to <agent/config path> so
future runs handle it automatically. Want me to make that config change?
```

## Examples

### Make Orchestrator more conservative with background writers

Proposal:

```text
I can add a narrow Orchestrator prompt rule to avoid parallel writer agents in
the same directory unless their file ownership is explicit. Target:
~/.config/opencode/oh-my-opencode-slim/orchestrator_append.md. Apply it?
```

### Add a project-specific reviewer

Proposal:

```text
This looks repeatable enough for a custom read-only reviewer agent. I can add
`api-reviewer` with no skills or MCPs and an `orchestratorPrompt` that routes
public API changes to it. Apply to your oh-my-opencode-slim config?
```

### Warn about restart

After editing:

```text
Updated the config. This should apply on the next OpenCode run; restart
OpenCode if you need it immediately.
```

## Final Checklist

- [ ] Did the user confirm config/prompt edits, unless explicitly requested?
- [ ] Did the edit preserve existing settings?
- [ ] Is the active preset still valid?
- [ ] Are skill/MCP/tool permissions intentional and minimal?
- [ ] Did you mention OpenCode restart/next-run behavior?