When to Use This Skill

Load this skill when the user:

• Asks about OpenCode installation, setup, or configuration
• Mentions opencode.ai commands like /init, /connect, /undo
• Needs help with AGENTS.md or custom commands
• Asks about TUI features, mode switching, or tools
• Wants to create agents, skills, or custom commands
• References opencode configuration (opencode.json)
• Is working on a project with .opencode directory

This skill provides specialized knowledge for OpenCode workflows.

OpenCode Agent Guide

Quick Start

Installation

# Recommended: Install script
curl -fsSL https://opencode.ai/install | bash

# Or use npm
npm install -g opencode-ai

# Or use Homebrew (macOS/Linux)
brew install anomalyco/tap/opencode

[Source: https://opencode.ai/docs]

Setup

# Navigate to your project
cd /path/to/project

# Start OpenCode
opencode

# Configure your AI provider
/connect

# Initialize project (creates AGENTS.md)
/init

[Source: https://opencode.ai/docs]

Essential commands: /init, /help, /exit, /new, /sessions [Source: https://opencode.ai/docs/tui]

File references: @path/to/file - fuzzy file search and content injection [Source: https://opencode.ai/docs]

Bash commands: !npm install - execute shell commands directly [Source: https://opencode.ai/docs]

Undo/redo: /undo (Git-based), /redo restore changes [Source: https://opencode.ai/docs/tui]

Core Usage Patterns

File References

@filename                    # Fuzzy search single file
@src/components/*.tsx       # Pattern matching
@path/to/file.ts:42         # Line-specific reference

Use @ for fuzzy file matching. Agent reads file content automatically [Source: https://opencode.ai/docs]

Bash Commands

!npm install                # Run npm commands
!git status && git diff     # Chain commands
!`git log --oneline -5`     # Output injection in custom commands

Execute shell commands. Use workdir parameter instead of cd patterns [Source: https://opencode.ai/docs/tools]

Agent Switching

• Tab key: Switch between Build mode (default) and Plan mode [Source: https://opencode.ai/docs/agents]
• @subagent: Invoke subagents (General, Explore) via @mention [Source: https://opencode.ai/docs/agents]
• Ctrl+x: Default leader key for shortcuts [Source: https://opencode.ai/docs/tui]

TUI Commands

Session: /sessions, /new, /exit, /share, /unshare [Source: https://opencode.ai/docs/tui]

Configuration: /connect, /models, /editor, /themes [Source: https://opencode.ai/docs/tui]

View: /compact, /details, /thinking [Source: https://opencode.ai/docs/tui]

Git: /undo, /redo, /export, /import [Source: https://opencode.ai/docs/tui]

Help: /help, /init (creates AGENTS.md) [Source: https://opencode.ai/docs/tui]

CLI Usage

Default: opencode starts TUI. Non-interactive: opencode run <prompt> [Source: https://opencode.ai/docs/cli]

Commands: agent, attach, auth, github, mcp, models, run, serve, session, stats, export, import, web [Source: https://opencode.ai/docs/cli]

Global flags: --help, --version, --print-logs, --log-level [Source: https://opencode.ai/docs/cli]

Environment: OPENCODE_AUTO_SHARE, OPENCODE_CONFIG, OPENCODE_DISABLE_CLAUDE_CODE [Source: https://opencode.ai/docs/cli]

Configuration

Files: .opencode/opencode.json (project), ~/.config/opencode/config.json (global) [Source: https://opencode.ai/docs]

Basic opencode.json structure:

{
  "agents": {
    "default": {
      "model": "provider/model",
      "temperature": 0.7
    }
  },
  "tools": {
    "bash": {
      "permissions": "allow"
    }
  }
}

[Source: https://opencode.ai/docs/agents]

Initial setup: /connect command configures connection [Source: https://opencode.ai/docs]

Agent config: tools, permissions, model, temperature [Source: https://opencode.ai/docs/agents]

Claude compatibility: Reads CLAUDE.md when AGENTS.md not present [Source: https://opencode.ai/docs/rules]

For advanced configuration (remote config, plugins, formatters), see CONFIGURATION.md

Custom Commands

Location: .opencode/commands/ or ~/.config/opencode/commands/ [Source: https://opencode.ai/docs/commands]

Format: Markdown with YAML frontmatter [Source: https://opencode.ai/docs/commands]

---
description: Run tests with coverage
agent: Build
template: |
  !npm run test -- --coverage && !npm run lint
  $ARGUMENTS
---
# Test Runner

Run tests and lint. Arguments passed directly.

Arguments: $ARGUMENTS (all), $1, $2, $3 (positional) [Source: https://opencode.ai/docs/commands]

Shell injection: !command`` - injects output into command template [Source: https://opencode.ai/docs/commands]

File references: @filename in commands [Source: https://opencode.ai/docs/commands]

Config options: template, description, agent, subtask, model [Source: https://opencode.ai/docs/commands]

Agents

Modes: Build (default), Plan - switch with Tab key [Source: https://opencode.ai/docs/agents]

Subagents: General, Explore - invoke via @mention [Source: https://opencode.ai/docs/agents]

Configuration: JSON or Markdown files in .opencode/agents/ [Source: https://opencode.ai/docs/agents]

Options: description, temperature, max_steps, disable, prompt, model, tools, permissions, mode, hidden, task_permissions, color, top_p [Source: https://opencode.ai/docs/agents]

Creation: opencode agent create <name> [Source: https://opencode.ai/docs/agents]

Switching: Tab key cycles between Build mode and Plan mode; @subagent invokes subagents [Source: https://opencode.ai/docs/agents]

Tools

Built-in tools:

• bash - Execute shell commands
• edit - Edit files in place
• write - Write new files
• read - Read file contents
• grep - Search file contents
• glob - Find files by pattern
• list - List directory contents
• lsp - Language Server Protocol (experimental)
• patch - Apply patches
• skill - Load agent skills
• todowrite/todoread - Task management
• webfetch - Fetch web content
• question - Interactive prompts [Source: https://opencode.ai/docs/tools]

Permissions: allow, deny, ask per tool [Source: https://opencode.ai/docs/tools]

Custom tools: Configure in opencode.json [Source: https://opencode.ai/docs/tools]

MCP servers: External tool integrations [Source: https://opencode.ai/docs/tools]

Ignore patterns: .ignore file in project root [Source: https://opencode.ai/docs/tools]

Best practices: Use workdir param instead of cd patterns. Batch independent tool calls. Prefer grep over bash grep [Source: https://opencode.ai/docs/tools]

Skills System

Format: SKILL.md with YAML frontmatter [Source: https://opencode.ai/docs/skills]

Locations: .opencode/skills/<name>/, ~/.config/opencode/skills/<name>/, .claude/skills/<name>/, ~/.claude/skills/<name>/ [Source: https://opencode.ai/docs/skills]

Frontmatter: name (req), description (req), license (opt), compatibility (opt), metadata (opt) [Source: https://opencode.ai/docs/skills]

Name validation: 1-64 chars, lowercase alphanumeric with hyphens, regex: ^[a-z0-9]+(-[a-z0-9]+)*$ [Source: https://opencode.ai/docs/skills]

Description: 1-1024 characters [Source: https://opencode.ai/docs/skills]

Discovery: Walks up from CWD to git worktree, loads from global configs [Source: https://opencode.ai/docs/skills]

Loading: skill tool loads by name [Source: https://opencode.ai/docs/skills]

Permissions: pattern-based allow/deny/ask [Source: https://opencode.ai/docs/skills]

Rules and AGENTS.md

AGENTS.md: Project root file created by /init command [Source: https://opencode.ai/docs/rules]

Types: Project (local), Global (~/.config/opencode/AGENTS.md), Claude Code Compatible [Source: https://opencode.ai/docs/rules]

Custom instructions: instructions field in opencode.json [Source: https://opencode.ai/docs/rules]

External refs: Reference external files from AGENTS.md [Source: https://opencode.ai/docs/rules]

Precedence: local AGENTS.md > global AGENTS.md > Claude CLAUDE.md [Source: https://opencode.ai/docs/rules]

Common Workflows

Add a New Feature

1. Switch to Plan mode (Tab key)
2. Plan: "Add user authentication to /settings route. Check @src/notes.ts for reference"
3. Review and iterate on the plan
4. Switch to Build mode (Tab key)
5. Build: "Go ahead and implement"
6. Test: !npm test
7. Commit: !git add . && git commit -m "feat: add authentication"

Debug an Issue

1. Identify error location: @src/api/error.ts:42
2. Check related files: @src/components/*
3. Run with debug output: !npm run dev -- --verbose
4. Add breakpoints based on error
5. Test fix: !npm run test -- --watch
6. If issue persists: /undo to revert, refine prompt

Git Workflow

!git status
@path/to/changed/file.ts
!git add . && git commit -m "message"

Use /undo to revert changes via Git, /redo to restore [Source: https://opencode.ai/docs/tui]

Multi-Mode Task

@plan-agent: Create implementation plan
Tab to Build mode, execute plan

Custom Command Workflow

Create command in .opencode/commands/
Use @file references for context
Use $ARGUMENTS for user input
Test with /help command