Skills
skills/modelscope.cn/opencode

opencode

SKILL.md

OpenCode Skill

OpenCode is an open source AI coding agent available as a terminal interface (TUI), desktop app, or IDE extension. It enables developers to work on code projects through conversational interactions with intelligent assistance for code explanation, implementation planning, code modification, and more.

Key Value Proposition: A flexible, multi-provider AI assistant with customizable agents, granular permissions, and extensive tool integrations that can be tailored for specific workflows like code review, documentation, security auditing, or development.

When to Use This Skill

  • Setting up OpenCode for a new development environment
  • Creating custom agents for specialized coding workflows
  • Configuring permissions for team-based development
  • Building automated scripts with OpenCode CLI
  • Integrating MCP servers for extended capabilities
  • Troubleshooting OpenCode configuration or tool issues
  • Comparing OpenCode features with other AI coding assistants

When NOT to Use This Skill

  • For Claude Code/Claude CLI specific features (different product)
  • For GitHub Copilot configuration (use copilot-specific docs)
  • For Cursor IDE settings (different AI editor)
  • For generic LLM API usage (use provider-specific skills)

Core Concepts

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         OpenCode                                 │
│            Terminal UI / Desktop App / IDE Extension             │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│    Agents     │    │    Tools      │    │  Permissions  │
├───────────────┤    ├───────────────┤    ├───────────────┤
│ • Build       │    │ • read/write  │    │ • allow       │
│ • Plan        │    │ • edit/patch  │    │ • ask         │
│ • Custom...   │    │ • bash        │    │ • deny        │
│ • Subagents   │    │ • grep/glob   │    │ • Wildcards   │
└───────────────┘    │ • webfetch    │    └───────────────┘
                     │ • lsp         │
                     │ • MCP servers │
                     └───────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  LLM Providers │   │   Sessions    │    │   Commands    │
├───────────────┤    ├───────────────┤    ├───────────────┤
│ • OpenAI      │    │ • SQLite      │    │ • /init       │
│ • Claude      │    │ • Persistence │    │ • /undo       │
│ • Gemini      │    │ • Export/     │    │ • /share      │
│ • Groq        │    │   Import      │    │ • Custom...   │
│ • Bedrock     │    └───────────────┘    └───────────────┘
└───────────────┘

Agent Types

Type Description Use Case
Primary Agent Main assistant for direct interaction Day-to-day development
Subagent Specialized assistant for specific tasks Research, exploration
Build (built-in) Full tool access for development Writing and modifying code
Plan (built-in) Read-only for analysis Planning without changes
General (subagent) Multi-step task execution Research and investigation
Explore (subagent) Codebase navigation Quick file/code searching

Installation

Quick Install (Recommended)

# Install script
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

# Homebrew (macOS/Linux)
brew install opencode-ai/tap/opencode

# npm
npm install -g opencode

# Go
go install github.com/opencode-ai/opencode@latest

Verify Installation

opencode --version

Configuration

Configuration Files

OpenCode uses opencode.json in your project root or global config at ~/.config/opencode/:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },
  "agent": {
    "build": {
      "model": "claude-sonnet-4-20250514"
    },
    "plan": {
      "model": "claude-sonnet-4-20250514",
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

Environment Variables

# API Keys (choose your provider)
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."
export GROQ_API_KEY="..."

# OpenCode Settings
export OPENCODE_CONFIG="~/.config/opencode/opencode.json"
export OPENCODE_PERMISSION="ask"  # Default permission level
export OPENCODE_AUTO_SHARE="true"  # Auto-share sessions
export OPENCODE_EXPERIMENTAL_LSP_TOOL="true"  # Enable LSP

Tools Reference

Built-in Tools

Tool Description Permission
read Read file contents from codebase allow
write Create or overwrite files edit
edit Modify files using exact string replacements edit
patch Apply patch files to code edit
grep Search file contents using regex allow
glob Find files by pattern (e.g., **/*.js) allow
list List files and directories allow
bash Execute shell commands ask
webfetch Fetch and read web pages ask
lsp Language Server Protocol (experimental) allow
skill Load SKILL.md file content allow
question Ask user questions during execution allow
todoread/todowrite Task tracking during sessions allow

Tool Configuration

{
  "permission": {
    "*": "ask",
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "list": "allow",
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny"
    }
  }
}

Creating Custom Agents

Interactive Creation

opencode agent create

This guides you through:

  1. Selecting storage location (global or project)
  2. Defining agent purpose
  3. Auto-generating system prompts
  4. Choosing accessible tools
  5. Creating markdown configuration

Agent Configuration (JSON)

{
  "agent": {
    "reviewer": {
      "description": "Code review specialist",
      "mode": "subagent",
      "model": "claude-sonnet-4-20250514",
      "temperature": 0.3,
      "prompt": ".opencode/agent/reviewer.md",
      "tools": {
        "read": true,
        "grep": true,
        "glob": true,
        "edit": false,
        "bash": false
      },
      "permission": {
        "webfetch": "deny"
      },
      "maxSteps": 20
    }
  }
}

Agent Configuration (Markdown)

Create .opencode/agent/reviewer.md:

---
description: Code review specialist for quality and security
mode: subagent
model: claude-sonnet-4-20250514
temperature: 0.3
tools:
  read: true
  grep: true
  glob: true
  edit: false
  bash: false
---

You are a code review specialist focused on:

1. Code quality and best practices
2. Security vulnerabilities
3. Performance issues
4. Maintainability concerns

When reviewing code:
- Identify issues by severity (critical, major, minor)
- Provide specific line references
- Suggest concrete improvements
- Consider the project's existing patterns

Agent Parameters

Parameter Type Description
description string Brief explanation (required)
mode string primary, subagent, or all
model string Override default model
temperature float Response randomness (0.0-1.0)
prompt string Path to system prompt file
tools object Enable/disable specific tools
permission object Override permissions
maxSteps number Limit iterations before text-only

Custom Commands

Command Structure

Create .opencode/command/review.md:

---
description: Review code changes
agent: reviewer
---

Review the following code changes:

$ARGUMENTS

Focus on:
1. Security vulnerabilities
2. Performance issues
3. Code style violations
4. Missing tests

Using Arguments

---
description: Create a component
---

Create a new React component named $1 in the $2 directory.

Requirements:
- TypeScript
- Styled with Tailwind
- Include tests

Usage: /component Button components/ui

Including Shell Output

---
description: Review recent changes
---

Review the following git diff:

`!git diff HEAD~1`

Summarize changes and identify any issues.

File References

---
description: Explain architecture
---

Based on the architecture documentation:

@ARCHITECTURE.md

Explain how the authentication system works.

CLI Reference

TUI Mode (Default)

# Start in current directory
opencode

# Start in specific project
opencode /path/to/project

# Continue last session
opencode --continue

# Use specific session
opencode --session <session-id>

# Override model
opencode --model claude-sonnet-4-20250514

Non-Interactive Mode

# Run single prompt
opencode run "explain this codebase"

# Run with file context
opencode run --file src/main.ts "add error handling"

# Run custom command
opencode run --command review

# Output format
opencode run --format json "list all functions"

Server Mode

# Start headless server
opencode serve --port 8080

# Start with web interface
opencode web --port 8080

# Connect to remote server
opencode attach http://localhost:8080

Agent Management

# Create new agent
opencode agent create

# List all agents
opencode agent list

MCP Integration

# Add MCP server
opencode mcp add <server-name>

# List MCP servers
opencode mcp list

# Debug MCP connection
opencode mcp debug <server-name>

Session Management

# List sessions
opencode session list --max-count 10

# Export session
opencode export <session-id>

# Import session
opencode import session.json

# View usage stats
opencode stats --days 7

Project Initialization

Generate AGENTS.md

opencode
/init

This analyzes your project and generates AGENTS.md containing:

  • Project structure overview
  • Key patterns and conventions
  • Technology stack
  • Important files and directories

Best Practice: Commit AGENTS.md to version control so OpenCode understands your codebase.

Permissions System

Permission Levels

Level Behavior
allow Executes without approval
ask Prompts for user approval
deny Blocks execution

Approval Responses

When prompted:

  • once - Approve single request
  • always - Approve matching requests for session
  • reject - Deny the request

Default Permissions

Most tools default to allow, except:

  • doom_loop - ask (safety feature)
  • external_directory - ask (safety feature)
  • .env* files - deny (security)

Agent-Level Overrides

Agent permissions take precedence over global:

{
  "permission": {
    "bash": "ask"
  },
  "agent": {
    "build": {
      "permission": {
        "bash": "allow"
      }
    }
  }
}

Common Use Cases

Code Review Agent

---
description: Systematic code review
mode: subagent
tools:
  read: true
  grep: true
  edit: false
  bash: false
---

You are a code reviewer. For each review:

1. Check for security vulnerabilities
2. Identify performance bottlenecks
3. Ensure code follows project patterns
4. Verify test coverage
5. Suggest improvements

Format findings as:
- CRITICAL: [issue]
- MAJOR: [issue]
- MINOR: [issue]

Documentation Agent

---
description: Documentation writer
mode: subagent
tools:
  read: true
  glob: true
  write: true
  bash: false
---

You write clear, comprehensive documentation.

When documenting:
1. Follow project's existing doc style
2. Include code examples
3. Document edge cases
4. Keep language accessible

Security Audit Agent

---
description: Security vulnerability scanner
mode: subagent
tools:
  read: true
  grep: true
  bash: false
  webfetch: true
---

You are a security auditor. Scan for:

1. Injection vulnerabilities (SQL, XSS, command)
2. Authentication/authorization issues
3. Sensitive data exposure
4. Insecure dependencies
5. Misconfigurations

Reference OWASP Top 10 for classification.

Troubleshooting

Agent Not Invoking

Issue: Custom agent doesn't respond to @mention

Solutions:

  1. Verify agent file is in correct location (.opencode/agent/ or ~/.config/opencode/agent/)
  2. Check mode is set correctly (subagent for @mentions)
  3. Ensure YAML frontmatter is valid
  4. Try opencode agent list to verify registration

Permission Denied

Issue: Tool execution blocked unexpectedly

Solutions:

  1. Check global permissions in opencode.json
  2. Verify agent-specific overrides
  3. Use opencode run --permission allow for testing
  4. Check for conflicting wildcard patterns

Tool Not Working

Issue: grep/glob returns no results

Solutions:

  1. Check if files are in .gitignore (excluded by default)
  2. Create .ignore file to include ignored directories
  3. Verify pattern syntax is correct

LLM Connection Issues

Issue: Provider not responding

Solutions:

  1. Verify API key is set correctly
  2. Check network connectivity
  3. Run opencode models to list available models
  4. Try opencode models --refresh to refresh cache

Resources

Official Documentation

Source Code

Related Projects

Version History

  • 1.0.0 (2026-01-12): Initial skill release
    • Complete OpenCode agent system documentation
    • Built-in and custom agent configuration
    • Tools reference with permission system
    • CLI commands and usage patterns
    • Custom commands and SKILL.md integration
    • MCP server integration
    • Common agent templates (review, docs, security)
    • Troubleshooting guide
Weekly Installs
1
Source
modelscope.cn/s…opencode
First Seen
2 days ago
Installed on
amp1
cline1
openclaw1
opencode1
cursor1
kimi-cli1