opencode

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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的安装、设置或配置相关问题
  • 提及opencode.ai命令如/init、/connect、/undo
  • 需要AGENTS.md或自定义命令相关帮助
  • 询问TUI功能、模式切换或工具相关内容
  • 想要创建Agent、技能或自定义命令
  • 涉及opencode配置文件(opencode.json)
  • 正在处理包含.opencode目录的项目
此技能为OpenCode工作流提供专业知识支持。

OpenCode Agent Guide

OpenCode Agent指南

Quick Start

快速开始

Installation

安装

bash
undefined
bash
undefined

Recommended: Install script

推荐方式:安装脚本

curl -fsSL https://opencode.ai/install | bash
curl -fsSL https://opencode.ai/install | bash

Or use npm

或使用npm

npm install -g opencode-ai
npm install -g opencode-ai

Or use Homebrew (macOS/Linux)

或使用Homebrew(macOS/Linux)

brew install anomalyco/tap/opencode
[Source: https://opencode.ai/docs]
brew install anomalyco/tap/opencode
[来源: https://opencode.ai/docs]

Setup

设置

bash
undefined
bash
undefined

Navigate to your project

进入你的项目目录

cd /path/to/project
cd /path/to/project

Start OpenCode

启动OpenCode

opencode
opencode

Configure your AI provider

配置AI提供商

/connect
/connect

Initialize project (creates AGENTS.md)

初始化项目(创建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]
/init
[来源: https://opencode.ai/docs]

**核心命令**:/init、/help、/exit、/new、/sessions [来源: https://opencode.ai/docs/tui]

**文件引用**:`@path/to/file` - 模糊文件搜索与内容注入 [来源: https://opencode.ai/docs]

**Bash命令**:`!npm install` - 直接执行Shell命令 [来源: https://opencode.ai/docs]

**撤销/重做**:/undo(基于Git)、/redo恢复更改 [来源: 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]
@filename                    # 模糊搜索单个文件
@src/components/*.tsx       # 模式匹配
@path/to/file.ts:42         # 指定行的引用
使用@进行模糊文件匹配,Agent会自动读取文件内容 [来源: https://opencode.ai/docs]

Bash Commands

Bash命令

!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]
!npm install                # 运行npm命令
!git status && git diff     # 链式命令
!`git log --oneline -5`     # 在自定义命令中注入输出
执行Shell命令,使用workdir参数替代cd模式 [来源: https://opencode.ai/docs/tools]

Agent Switching

Agent切换

TUI Commands

TUI命令

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]
会话:/sessions、/new、/exit、/share、/unshare [来源: https://opencode.ai/docs/tui]
配置:/connect、/models、/editor、/themes [来源: https://opencode.ai/docs/tui]
视图:/compact、/details、/thinking [来源: https://opencode.ai/docs/tui]
Git:/undo、/redo、/export、/import [来源: https://opencode.ai/docs/tui]
帮助:/help、/init(创建AGENTS.md) [来源: https://opencode.ai/docs/tui]

CLI Usage

CLI使用

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]
默认:
opencode
启动TUI。非交互式模式:
opencode run <prompt>
[来源: https://opencode.ai/docs/cli]
命令:agent、attach、auth、github、mcp、models、run、serve、session、stats、export、import、web [来源: https://opencode.ai/docs/cli]
全局标志:--help、--version、--print-logs、--log-level [来源: https://opencode.ai/docs/cli]
环境变量:OPENCODE_AUTO_SHARE、OPENCODE_CONFIG、OPENCODE_DISABLE_CLAUDE_CODE [来源: 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:
json
{
  "agents": {
    "default": {
      "model": "provider/model",
      "temperature": 0.7
    }
  },
  "tools": {
    "bash": {
      "permissions": "allow"
    }
  }
}
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
配置文件
.opencode/opencode.json
(项目级)、
~/.config/opencode/config.json
(全局级) [来源: https://opencode.ai/docs]
opencode.json基础结构:
json
{
  "agents": {
    "default": {
      "model": "provider/model",
      "temperature": 0.7
    }
  },
  "tools": {
    "bash": {
      "permissions": "allow"
    }
  }
}
初始设置:/connect命令用于配置连接 [来源: https://opencode.ai/docs]
Agent配置项:tools、permissions、model、temperature [来源: https://opencode.ai/docs/agents]
Claude兼容性:当AGENTS.md不存在时,会读取CLAUDE.md [来源: https://opencode.ai/docs/rules]
高级配置(远程配置、插件、格式化工具)请查看 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]
markdown
---
description: Run tests with coverage
agent: Build
template: |
  !npm run test -- --coverage && !npm run lint
  $ARGUMENTS
---
存储位置
.opencode/commands/
~/.config/opencode/commands/
[来源: https://opencode.ai/docs/commands]
格式:带YAML前置元数据的Markdown文件 [来源: https://opencode.ai/docs/commands]
markdown
---
description: 运行带覆盖率的测试
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]
运行测试与代码检查。参数将直接传递。

**参数**:$ARGUMENTS(所有参数)、$1、$2、$3(位置参数) [来源: https://opencode.ai/docs/commands]

**Shell注入**:`!`command`` - 将输出注入到命令模板中 [来源: https://opencode.ai/docs/commands]

**文件引用**:命令中可使用@filename [来源: https://opencode.ai/docs/commands]

**配置选项**:template、description、agent、subtask、model [来源: https://opencode.ai/docs/commands]

Agents

Agent

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]
模式:Build(默认)、Plan - 使用Tab键切换 [来源: https://opencode.ai/docs/agents]
子Agent:General、Explore - 通过@提及调用 [来源: https://opencode.ai/docs/agents]
配置文件
.opencode/agents/
目录下的JSON或Markdown文件 [来源: https://opencode.ai/docs/agents]
配置选项:description、temperature、max_steps、disable、prompt、model、tools、permissions、mode、hidden、task_permissions、color、top_p [来源: https://opencode.ai/docs/agents]
创建方式
opencode agent create <name>
[来源: https://opencode.ai/docs/agents]
切换方式:Tab键在Build模式和Plan模式之间循环切换;@subagent调用子Agent [来源: 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]
内置工具:
  • bash
    - 执行Shell命令
  • edit
    - 原地编辑文件
  • write
    - 写入新文件
  • read
    - 读取文件内容
  • grep
    - 搜索文件内容
  • glob
    - 按模式查找文件
  • list
    - 列出目录内容
  • lsp
    - 语言服务器协议(实验性)
  • patch
    - 应用补丁
  • skill
    - 加载Agent技能
  • todowrite/todoread
    - 任务管理
  • webfetch
    - 获取网页内容
  • question
    - 交互式提示 [来源: https://opencode.ai/docs/tools]
权限:每个工具可设置allow、deny、ask [来源: https://opencode.ai/docs/tools]
自定义工具:在opencode.json中配置 [来源: https://opencode.ai/docs/tools]
MCP服务器:外部工具集成 [来源: https://opencode.ai/docs/tools]
忽略模式:项目根目录下的.ignore文件 [来源: https://opencode.ai/docs/tools]
最佳实践:使用workdir参数替代cd模式。批量执行独立工具调用。优先使用grep而非bash grep [来源: 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]
格式:带YAML前置元数据的SKILL.md文件 [来源: https://opencode.ai/docs/skills]
存储位置
.opencode/skills/<name>/
~/.config/opencode/skills/<name>/
.claude/skills/<name>/
~/.claude/skills/<name>/
[来源: https://opencode.ai/docs/skills]
前置元数据:name(必填)、description(必填)、license(可选)、compatibility(可选)、metadata(可选) [来源: https://opencode.ai/docs/skills]
名称验证:1-64个字符,小写字母数字加连字符,正则:
^[a-z0-9]+(-[a-z0-9]+)*$
[来源: https://opencode.ai/docs/skills]
描述要求:1-1024个字符 [来源: https://opencode.ai/docs/skills]
发现机制:从当前工作目录向上遍历到Git工作区,同时从全局配置加载 [来源: https://opencode.ai/docs/skills]
加载方式:通过skill工具按名称加载 [来源: https://opencode.ai/docs/skills]
权限:基于模式的allow/deny/ask设置 [来源: https://opencode.ai/docs/skills]

Rules and AGENTS.md

规则与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]
AGENTS.md:由/init命令在项目根目录创建的文件 [来源: https://opencode.ai/docs/rules]
类型:项目级(本地)、全局级(~/.config/opencode/AGENTS.md)、Claude Code兼容版 [来源: https://opencode.ai/docs/rules]
自定义指令:opencode.json中的instructions字段 [来源: https://opencode.ai/docs/rules]
外部引用:可在AGENTS.md中引用外部文件 [来源: https://opencode.ai/docs/rules]
优先级:本地AGENTS.md > 全局AGENTS.md > Claude CLAUDE.md [来源: 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"
1. 切换到Plan模式(Tab键)
2. 规划:"为/settings路由添加用户认证。参考@src/notes.ts"
3. 审阅并迭代规划方案
4. 切换到Build模式(Tab键)
5. 构建:"开始实现"
6. 测试:!npm test
7. 提交:!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
1. 定位错误位置:@src/api/error.ts:42
2. 检查相关文件:@src/components/*
3. 带调试输出运行:!npm run dev -- --verbose
4. 根据错误添加断点
5. 测试修复:!npm run test -- --watch
6. 若问题仍存在:使用/undo撤销更改,优化提示词

Git Workflow

Git工作流

!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]
!git status
@path/to/changed/file.ts
!git add . && git commit -m "message"
使用/undo通过Git撤销更改,/redo恢复更改 [来源: https://opencode.ai/docs/tui]

Multi-Mode Task

多模式任务

@plan-agent: Create implementation plan
Tab to Build mode, execute plan
@plan-agent: 创建实现规划
按Tab键切换到Build模式,执行规划

Custom Command Workflow

自定义命令工作流

Create command in .opencode/commands/
Use @file references for context
Use $ARGUMENTS for user input
Test with /help command
在.opencode/commands/目录下创建命令
使用@file引用获取上下文
使用$ARGUMENTS接收用户输入
通过/help命令测试