home / skills / third774 / dotfiles / customizing-opencode

customizing-opencode skill

Q: How do I inject file contents or environment variables into config?

Use variable substitution syntax, e.g. "model": "{env:OPENCODE_MODEL}" or "instructions": ["{file:./rules.md}"] to embed values at runtime.

safe

/opencode/skills/customizing-opencode

This skill helps you tailor OpenCode configuration across global and project scopes using opencode.json, agents, commands, MCP, tools, plugins, themes, and

npx playbooks add skill third774/dotfiles --skill customizing-opencode

Review the files below or copy the command above to add this skill to your agents.

Files (10)

SKILL.md

3.4 KB

---
name: customizing-opencode
description: Configure OpenCode via opencode.json, agents, commands, MCP servers, custom tools, plugins, themes, keybinds, and permissions. Use when setting up or modifying OpenCode configuration.
---

# Customizing OpenCode

Configure OpenCode behavior through config files, agents, commands, and extensions.

## Config File Locations

| Location | Path | Purpose |
|----------|------|---------|
| Global | `~/.config/opencode/opencode.json` | User-wide preferences |
| Project | `./opencode.json` | Project-specific settings |
| Custom | `$OPENCODE_CONFIG` env var | Override path |

**Precedence** (later overrides earlier): Remote `.well-known/opencode` < Global < Custom < Project

## Quick Reference

| Task | Where | Reference |
|------|-------|-----------|
| Set theme, model, autoupdate | `opencode.json` | [config-schema.md](references/config-schema.md) |
| Define specialized agents | `.opencode/agents/*.md` or config | [agents.md](references/agents.md) |
| Create slash commands | `.opencode/commands/*.md` or config | [commands.md](references/commands.md) |
| Add external tools via MCP | `opencode.json` `mcp` section | [mcp-servers.md](references/mcp-servers.md) |
| Write custom tool functions | `.opencode/tools/*.ts` | [custom-tools.md](references/custom-tools.md) |
| Extend with plugins/hooks | `.opencode/plugins/*.ts` or npm | [plugins.md](references/plugins.md) |
| Control tool access | `opencode.json` `permission` section | [permissions.md](references/permissions.md) |
| Customize keyboard shortcuts | `opencode.json` `keybinds` section | [keybinds.md](references/keybinds.md) |
| Change colors/appearance | `opencode.json` `theme` or custom JSON | [themes.md](references/themes.md) |

## Directory Structure

```
~/.config/opencode/           # Global config
├── opencode.json
├── AGENTS.md                 # Global rules
├── agents/                   # Global agents
├── commands/                 # Global commands
├── plugins/                  # Global plugins
├── skills/                   # Global skills
├── tools/                    # Global custom tools
└── themes/                   # Global custom themes

.opencode/                    # Project config (same structure)
├── agents/
├── commands/
├── plugins/
├── skills/
├── tools/
└── themes/
```

## When to Use What

| Need | Solution |
|------|----------|
| Change model/theme for all projects | Global `opencode.json` |
| Project-specific agent behavior | Project `.opencode/agents/` |
| Reusable prompt templates | Commands (`.opencode/commands/`) |
| External service integration | MCP servers |
| Custom logic the LLM can call | Custom tools |
| React to OpenCode events | Plugins |
| Restrict dangerous operations | Permissions |

## Variable Substitution

Use in any config value:

```jsonc
{
  "model": "{env:OPENCODE_MODEL}",           // Environment variable
  "instructions": ["{file:./rules.md}"]      // File contents
}
```

## Rules (AGENTS.md)

Project instructions loaded into LLM context:

| File | Scope |
|------|-------|
| `./AGENTS.md` | Project (traverses up to git root) |
| `~/.config/opencode/AGENTS.md` | Global |
| `instructions` array in config | Additional files/globs |

```jsonc
{
  "instructions": ["CONTRIBUTING.md", "docs/*.md"]
}
```

## Docs

Full documentation: https://opencode.ai/docs/config/

Overview

This skill configures OpenCode behavior via opencode.json, agents, commands, MCP servers, custom tools, plugins, themes, keybinds, and permission rules. It centralizes where settings live (global, project, or custom path) and explains precedence and directory layout. Use it to set defaults, add integrations, define reusable prompts, and lock down risky operations.

How this skill works

The skill inspects configuration files in three main places: global (~/.config/opencode/opencode.json), project (.opencode/ or ./opencode.json), and an override set by $OPENCODE_CONFIG. Later sources override earlier ones. It also recognizes ancillary folders (.opencode/agents, commands, plugins, tools, themes) and supports variable substitution from environment variables and file contents.

When to use it

Set a default model, theme, or autoupdate behavior across all projects
Define project-specific agents, prompts, or command templates
Integrate external services and tools through MCP servers
Add custom tool functions that the LLM can call during runs
Enforce permissions to restrict potentially dangerous operations

Best practices

Keep global defaults in ~/.config/opencode/opencode.json and override per-project only when necessary
Store reusable prompts and workflows as commands in .opencode/commands/ to enable sharing
Place executable custom tools in .opencode/tools/*.ts and keep them small and tested
Use variable substitution ({env:VAR} and {file:path}) for secrets and shared content instead of hardcoding
Define a clear permission policy in opencode.json to limit access to powerful tools and MCP endpoints

Example use cases

Set a company-wide theme, model preference, and auto-update schedule in the global config
Create a project agent in .opencode/agents/ that loads CONTRIBUTING.md and enforces code style in PRs
Add an MCP server entry in opencode.json to call an external analysis service from within OpenCode
Write a custom tool that runs tests and returns structured results for the LLM to act on
Create keyboard shortcuts in opencode.json keybinds to trigger common slash commands

FAQ

Which config wins when the same setting appears in multiple places?

Precedence is: remote .well-known/opencode < Global (~/.config/opencode) < Custom ($OPENCODE_CONFIG) < Project (./opencode.json or .opencode/). Later entries override earlier ones.

How do I inject file contents or environment variables into config?

Use variable substitution syntax, e.g. "model": "{env:OPENCODE_MODEL}" or "instructions": ["{file:./rules.md}"] to embed values at runtime.