opencode-config

Q: How do I install opencode-config?

Run npx skills add https://github.com/igorwarzocha/opencode-workflows --skill opencode-config in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/opencode-config/ (personal) or .claude/skills/opencode-config/ (project).

by igorwarzochaBackend & APIs

Edit opencode.json, AGENTS.md, and config files. Use proactively for provider setup, permission changes, model config, formatter rules, or environment variables. Examples: - user: "Add Anthropic as a provider" → edit opencode.json providers, add API key baseEnv var, verify with opencode run test - user: "Restrict this agent's permissions" → add permission block to agent config, set deny/allow for tools/fileAccess - user: "Set GPT-5 as default model" → edit global or agent-level model preference, verify model name format - user: "Disable gofmt formatter" → edit formatters section, set languages.gofmt.enabled = false

Installs: 308
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/igorwarzocha/opencode-workflows --skill opencode-config

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads opencode-config automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

OpenCode Configuration

Help users configure OpenCode through guided setup of config files and rules.

<question_tool>

Batching Rule: Use only for 2+ related questions; single questions use plain text.

Syntax Constraints: header max 12 chars, labels 1-5 words, mark defaults with (Recommended).

Purpose: Clarify config scope (models/permissions/rules), validate approach, and handle multiple valid options.

</question_tool>

File Locations

Type	Global	Project
Config	`~/.config/opencode/opencode.json`	`./opencode.json`
Rules	`~/.config/opencode/AGENTS.md`	`./AGENTS.md`

Precedence: Project > Global. Configs are merged, not replaced.

</reference> <workflow>

Question Tool

Batching: Use the question tool for 2+ related questions. Single questions → plain text.

Syntax: header ≤12 chars, label 1-5 words, add "(Recommended)" to default.

When to ask: Vague request ("configure opencode"), permission/security changes, or multiple valid options exist.

Workflow

Ask the user what they want to configure:

"What would you like to set up?"
- Config file (models, tools, permissions, theme)
- Rules (project instructions via AGENTS.md)

Then guide them through the relevant section below.

</workflow>

<config_file>

Config File (opencode.json)

Basic Setup

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "theme": "opencode",
  "autoupdate": true
}

Key Options

Option	Purpose	Example
`model`	Default model	`"anthropic/claude-sonnet-4-20250514"`
`small_model`	Lightweight tasks	`"anthropic/claude-3-5-haiku-20241022"`
`theme`	UI theme	`"opencode"`, `"catppuccin"`, `"dracula"`
`autoupdate`	Auto-update OpenCode	`true` / `false`
`share`	Session sharing	`"manual"` / `"auto"` / `"disabled"`

Permissions

Control what requires approval using the permission field.

{
  "permission": {
    "edit": "allow",           // "allow" | "ask" | "deny"
    "bash": {
      "npm *": "allow",        // pattern matching
      "git *": "allow",
      "rm *": "ask",
      "*": "ask"               // default for this tool
    },
    "webfetch": "allow",
    "skill": {
      "*": "allow",
      "dangerous-*": "deny"
    }
  }
}

Legacy Configuration

Agents may occasionally work on legacy projects using outdated configuration fields (e.g., tools, maxSteps). You MUST correct these to the modern permission and steps fields when encountered.

Custom Instructions

Include additional instruction files:

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

Full schema reference: See references/config-schema.md

</config_file>

<rules_file>

Rules (AGENTS.md)

Project instructions for all agents. Similar to CLAUDE.md or Cursor rules.

Create with /init

Run /init in OpenCode to auto-generate based on project analysis.

Manual Creation

# Project Name

This is a [framework] project using [language].

## Project Structure
- `src/` - Source code
- `tests/` - Test files

## Code Standards
- Use TypeScript strict mode
- Prefer functional patterns
- Write tests for all features

## Commands
- `npm run build` - Build project
- `npm test` - Run tests

Tips

SHOULD be specific about your project's patterns
SHOULD include common commands
SHOULD document any non-obvious conventions
SHOULD keep it concise (agents have limited context)

</rules_file>

<config_tips>

Comment Out, Don't Delete

OpenCode supports JSONC (JSON with comments). SHOULD comment out unused configs instead of deleting:

{
  "plugin": [
    "opencode-openai-codex-auth@latest",
    //"@tarquinen/opencode-dcp@latest",     // disabled for now
    //"@howaboua/pickle-thinker@0.4.0",     // only for GLM-4.6
    "@ramtinj95/opencode-tokenscope@latest"
  ]
}

Why: You might want to re-enable later. Keeps a record of what you've tried.

Validate After Major Changes

After editing opencode.json, you MUST run this validation (not just suggest it):

opencode run "test"

Execute it yourself using the Bash tool before telling the user the change is complete.

If broken, you'll see a clear error with line number:

Error: Config file at ~/.config/opencode/opencode.json is not valid JSON(C):
--- Errors ---
CommaExpected at line 464, column 5
   Line 464:     "explore": {
              ^
--- End ---

Common JSONC mistakes:

Missing comma after object (especially after adding new sections)
Trailing comma before }
Unclosed brackets

</config_tips>

<common_configurations>

Minimal Safe Config

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Power User Config

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "autoupdate": true,
  "permission": {
    "edit": "allow",
    "bash": {
      "*": "allow",
      "rm -rf *": "deny",
      "sudo *": "ask"
    }
  },
  "instructions": ["CONTRIBUTING.md"]
}

Team Project Config

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "share": "auto",
  "instructions": [
    "docs/development.md",
    "docs/api-guidelines.md"
  ]
}

</common_configurations>

Issue	Solution
Config not loading	Check JSON syntax, ensure valid path
Skill not found	Verify `SKILL.md` (uppercase), check frontmatter
Permission denied unexpectedly	Check global vs project config precedence

</troubleshooting>

References

references/config-schema.md - Full config options

FAQ

What does the opencode-config skill do?

How do I install opencode-config?

Run npx skills add https://github.com/igorwarzocha/opencode-workflows --skill opencode-config in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/opencode-config/ (personal) or .claude/skills/opencode-config/ (project).

Which AI agents can use opencode-config?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is opencode-config safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains opencode-config?

It is published by igorwarzocha in igorwarzocha/opencode-workflows. It has 308 recorded installs.