Imported from marcusrbrown/.dotfiles (.config/opencode/skills/oh-my-opencode-slim/SKILL.md). Install upstream with npx skills add marcusrbrown/.dotfiles --skill oh-my-opencode-slim. Copyright stays with the author.

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:

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

or:

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

Concrete files agents should know:

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.

Preset scope and merge semantics:

• Preset agent blocks merge into the top-level agents config; they do not replace it. A preset may therefore list a custom agent with only model and variant to re-route it per preset while its global prompt and orchestratorPrompt survive untouched.
• Only agents already present in the resolved config receive preset overrides. A preset entry for an agent that is defined nowhere else is ignored.
• Preset agent names are unconstrained strings, so custom agents are valid preset keys alongside the built-ins.
• The active preset is the root preset key, overridable per machine with the OH_MY_OPENCODE_SLIM_PRESET environment variable. Prefer the environment variable for machine-specific routing so the config file stays portable.
• Council seats are not preset-scoped. council.presets.<name>.<seat> lives at the config root with no binding to the active agent preset, so an agent preset cannot override a seat model. Changing a seat changes it for every preset.

Config Shapes

Tune a built-in agent model/skills/MCPs

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

{
  "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": ["context7", "gh_grep"]
      }
    }
  }
}

Append instructions to a built-in prompt

Create, for example:

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

or for only the openai preset:

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

Example content:

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

~/.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:

{
  "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:

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:

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:

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:

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?