一款开源 AI 编程助手的进阶玩法# OpenCode 进阶玩法：Skills、MCP 与 Custom Agents 实战指南

一、什么是 OpenCode

OpenCode 是一款开源的 AI 编程代理（Coding Agent），拥有 160K+ GitHub Stars，每月服务 750 万+ 开发者。它可以在终端、桌面应用或 IDE 扩展中运行，支持接入 Claude、GPT、DeepSeek、Gemini 等主流大模型。

核心特点

  • LSP 集成 — 自动加载项目 LSP，让 LLM 理解代码语义
  • 多会话 — 在同一个项目中并行启动多个代理
  • 任意编辑器 — 终端 CLI、桌面 App、IDE 扩展均可
  • 隐私优先 — 不存储你的代码或上下文数据

快速安装

# 一键安装
curl -fsSL https://opencode.ai/install | bash

# 或使用 npm
npm install -g opencode-ai

进入项目目录后运行 opencode，首次使用执行 /init 初始化即可。

二、深入理解 Skills（技能系统）

Skills 是 OpenCode 的一大亮点，它支持你编写可复用的指令集，代理能够按需发现和加载这些技能。

2.1 Skills 的工作原理

当你向 OpenCode 提问时，它会根据当前上下文判断需要调用哪个 Skill。Skills 通过 skill 工具按需加载，而非一次性注入所有指令，这大大节省了宝贵的上下文 Token。

2.2 创建你的第一个 Skill

Skill 就是一个包含 YAML 前置元数据的 SKILL.md 文件。

存放位置（任意一个均可）：

位置 路径
项目级 .opencode/skills/<name>/SKILL.md
全局级 ~/.config/opencode/skills/<name>/SKILL.md
Claude 兼容 .claude/skills/<name>/SKILL.md

示例：创建一个 Git 发布技能

---
name: git-release
description: Create consistent releases and changelogs
---

## What I do
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me
Use this when you are preparing a tagged release.

命名规则：

  • 1-64 个字符
  • 小写字母数字，单连字符分隔
  • 不能以 - 开头或结尾
  • 不能有连续 --

2.3 Skill 权限管理

你可以在 opencode.json 中精细控制哪些 Skill 可用：

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

三种权限级别：

权限 行为
allow 直接加载
deny 隐藏且拒绝访问
ask 需要用户确认

2.4 按代理覆盖

特定代理可以使用不同的 Skill 权限：

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

2.5 推荐 Skill 实践

项目级 Skills：

  • code-review — 代码审查规范
  • git-commit — 提交信息格式约定
  • testing — 测试规范和命令
  • deploy — 部署流程

团队级 Skills：

  • architecture — 架构决策记录
  • onboarding — 新人指引
  • coding-standards — 编码规范

三、MCP 服务器深度集成

MCP（Model Context Protocol）是 AI 模型与外部工具之间的标准协议。OpenCode 原生支持 MCP，让你的 AI 代理能够调用任意外部工具。

3.1 MCP 配置基础

所有 MCP 服务器在 opencode.json 中配置：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-server"],
      "enabled": true
    }
  }
}

3.2 本地 MCP vs 远程 MCP

本地 MCP

适合本地运行的 CLI 工具：

{
  "mcp": {
    "db-tools": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
      "environment": {
        "DATABASE_URL": "postgresql://..."
      }
    }
  }
}
远程 MCP

适合云端 API 服务：

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

3.3 OAuth 认证

OpenCode 会自动处理远程 MCP 的 OAuth 流程：

# 手动触发认证
opencode mcp auth sentry

# 查看所有 MCP 状态
opencode mcp list

# 登出某个 MCP
opencode mcp logout sentry

3.4 推荐的 MCP 服务器

MCP 服务器 类型 用途 配置参考
Sentry 远程 查询错误和性能数据 url: https://mcp.sentry.dev/mcp
Context7 远程 搜索技术文档 url: https://mcp.context7.com/mcp
Grep by Vercel 远程 搜索 GitHub 代码片段 url: https://mcp.grep.app
Playwright 本地 浏览器自动化测试 command: npx @playwright/mcp
GitHub 本地 管理 Issue/PR command: npx @modelcontextprotocol/server-github

3.5 按代理分配 MCP

如果你有很多 MCP 服务器，可以为不同代理分配不同的工具集：

{
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "debug": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}

也可以使用 glob 模式批量控制：

{
  "mcp": {
    "gh_issue": { ... },
    "gh_pr": { ... },
    "gh_search": { ... }
  },
  "tools": {
    "gh_*": false
  },
  "agent": {
    "git-work": {
      "tools": {
        "gh_*": true
      }
    }
  }
}

3.6 MCP + Skills 联动最佳实践

将 MCP 调用指令写入 AGENTS.md，让代理自动使用：

# AGENTS.md

## Debugging
When investigating errors, use the `sentry` MCP tools to query issue details.

## Research
When you need to search documentation, use `context7` tools.

## Code Search
If unsure how to implement something, use `gh_grep` to find examples.

四、高级技巧：Custom Agents

结合 Skills 和 MCP，你可以创建高度定制化的代理：

---
name: security-auditor
description: Performs security audits and identifies vulnerabilities
mode: subagent
permission:
  edit: deny
  bash:
    "*": deny
    "npm audit *": allow
    "snyk *": allow
---

You are a security expert.
Use `snyk` MCP tools to scan dependencies.
Focus on:
- Input validation vulnerabilities
- Authentication flaws
- Dependency vulnerabilities

在 opencode.json 中挂载：

{
  "agent": {
    "security-auditor": {
      "mode": "subagent"
    }
  }
}

使用时通过 @security-auditor 调用：

@security-auditor 请审查当前项目的依赖安全性

五、OpenCode 项目实战：看看官方怎么用

以下示例全部来自 OpenCode 官方 GitHub 仓库（github.com/anomalyco/opencode），它自身就是 OpenCode 的重度用户。

5.1 官方 Skill 示例：Effect

OpenCode 项目使用 Effect 框架，因此编写了一个 Skill 来指导 AI 代理正确编写 Effect 代码。

位置：.opencode/skills/effect/SKILL.md

---
name: effect
description: Work with Effect v4 / effect-smol TypeScript code in this repo
---
## Source Of Truth
Use the current Effect v4 / effect-smol source, not memory or older Effect v2/v3 examples.

1. Clone `https://github.com/Effect-TS/effect-smol` to `.opencode/references/effect-smol`
2. Search references for exact APIs before implementing
3. Prefer Effect `Schema` for API and domain data shapes
4. Use `Effect.gen(function* () { ... })` for multi-step workflows

这个 Skill 的核心思路：告诉 AI 不要"凭空想象"，而是先拉取官方源码作为参考。这在处理新框架或不熟悉的库时极为有用。

5.2 官方配置文件解析

OpenCode 项目自己的 .opencode/opencode.jsonc：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "permission": {},
  "mcp": {},
  "tools": {
    "github-triage": false,
    "github-pr-search": false,
  }
}

可以看到他们用 tools 关闭了一些 GitHub 工具，避免非必需的上下文占用。

5.3 官方 Custom Agents

OpenCode 团队还创建了自定义代理来处理 GitHub Issue 和 PR 工作流。例如：

triage 代理 — 用于 Issue 分类
duplicate-pr 代理 — 用于检测重复 PR

这些代理配置在 .opencode/agent/ 目录下，通过 Markdown 文件定义。

5.4 从官方实践中学到的

  1. Skill 要具体 — 针对特定技术栈（如 Effect）编写，而非笼统的"写代码规范"
  2. 引用外部源码 — Skill 可以指导 AI 先 clone 参考仓库，保证技术准确性
  3. 按需关闭工具 — 不需要的 MCP 工具设为 false，节省 Token
  4. 代理分工 — 不同任务用不同代理（triage / duplicate-pr），职责清晰

六、常见问题与避坑指南

6.1 MCP 占用上下文太多

MCP 工具会快速占用 Token 预算。建议：

  • 只启用真正需要的 MCP
  • 按代理分配 MCP，而非全局开启
  • 对 GitHub 等重型 MCP 尤其注意

6.2 Skill 不显示

排查步骤：

  1. 文件名必须是 SKILL.md（全大写）
  2. YAML 前置元数据必须有 name 和 description
  3. Skill 名称在所有位置必须唯一
  4. 检查权限配置是否为 deny

6.3 远程 MCP 认证失败

# 调试 MCP 连接
opencode mcp debug my-server

七、总结

特性 作用 最佳实践
Skills 可复用的指令集，按需加载 团队标准化流程、项目规范
MCP 接入外部工具和 API 按代理分配，避免全局滥用
Custom Agents 自定义代理角色 用 Skills + MCP 组合构建专属助手

OpenCode 的真正威力在于 Skills 的指令复用 + MCP 的工具生态 + Custom Agents 的角色分工。三者结合，你可以打造一个高度定制化的 AI 编程团队。

写在最后

写完这篇教程，最大的感触是：OpenCode 不仅仅是一个 AI 编程工具，它更像一个可以不断进化的"数字队友"。

Skills 让它可以记住团队的编码规范，MCP 让它能调用任何外部系统，Custom Agents 让它能在不同角色间切换。这三者结合起来，本质上是在打造一个属于你自己的 AI 开发流水线。

但也要承认，用好 OpenCode 需要投入学习成本。配置 Skills、选型 MCP、调教 Agent 都不是一蹴而就的事。我的建议是：从小处着手，从解决一个具体的痛点开始。比如先写一个 code-review 的 Skill，再慢慢扩展到更多场景。

AI 编程代理的未来不是取代开发者，而是让开发者从重复劳动中解放出来，把精力放在真正需要创造力的地方。而 OpenCode 的开源属性，让我们每个人都能参与塑造这个未来。

工具是免费的，但思考如何用好它，才是真正的价值所在。

更多内容请访问 opencode.ai/docs 或加入 Discord 社区。

# python # java # c++
Logo
MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

cover

【Bug已解决】Workspace path with spaces / Special characters in path — Claude Code 路径含空格或特殊字符解决方案

avatar MCP技术社区
cover

【Bug已解决】Memory leak / High memory usage / Process killed — Claude Code 内存泄漏解决方案

avatar MCP技术社区
cover

MCP协议、熔断器与OAuth——Agent接入外部世界的工程方案

avatar MCP技术社区