本文详细介绍 OpenCode 中三个核心概念的区别与使用方法：Agent（智能体）、Skills（技能）和 MCP（模型上下文协议），帮助你更好地理解和使用 OpenCode 的扩展能力。

# OpenCode 中 Agent、Skills 与 MCP 的区别与使用

在使用 OpenCode 进行开发时，我们经常会遇到三个核心概念：Agent、Skills 和 MCP。它们分别代表了不同的扩展机制，帮助 AI 助手获得更强的能力。本文将详细介绍这三者的区别与使用方法。

# 一分钟理解三者区别

概念	定位	作用	类比
Agent	AI 助手	执行特定任务的智能体	员工 / 专家
Skills	指令集	提供任务相关的指导文档	手册 / 最佳实践
MCP	工具桥	连接外部服务和工具	USB 接口

# Agent（智能体）

# 权威定义

An AI agent 是一种以 large language model 作为推理引擎的 AI 系统，能够自主感知其环境、规划行动、使用工具，并执行多步任务以实现目标 —— 无需在每一步都有人类输入。
DeepMind（2022 ReAct 顶会论文）：将大语言模型的推理能力与外部环境的行动能力结合，通过思考 - 行动 - 观察的迭代闭环，自主完成复杂目标的智能系统。
核心定义：Agent 是具备感知、思考、决策、行动能力的自主智能实体，能够基于给定目标，自主调用工具和技能，完成复杂任务，不需要人类一步步指令。

# 底层本质

Agent 不是大模型本身，大模型只是 Agent 的「大脑」，Agent 是以 LLM 为核心的完整闭环系统。它解决了原生大模型的三大核心痛点：

知识截止：无法获取实时数据与最新信息
能力边界：无法与外部系统、数据源、硬件进行交互
复杂任务拆解：无法自主完成多步骤、长链路的确定性任务

# Agent 类型

OpenCode 中的 Agent 分为两类：

# Primary Agent（主智能体）

Primary Agent 是直接与用户交互的主要助手。OpenCode 内置两个 Primary Agent：

Build：默认的开发智能体，拥有所有工具权限，可以进行文件编辑、命令执行等操作
Plan：计划与分析智能体，默认限制编辑和 bash 权限，用于分析和规划而不实际修改代码

# Subagent（子智能体）

Subagent 是专门的助手，可以被主智能体调用执行特定任务。OpenCode 内置两个 Subagent：

General：通用任务智能体，可以执行多步骤的研究和任务
Explore：代码探查智能体，只能读取文件，用于快速搜索和理解代码库

# 使用 Agent

	# 切换主智能体 - 使用 Tab 键循环切换
	<Tab>

	# 调用子智能体 - 使用 @ 提及
	@explore 查找认证相关的代码

# 创建自定义 Agent

可以通过配置文件创建自定义 Agent：

{
  "agent": {
    "review": {
      "description": "代码审查智能体",
      "mode": "subagent",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

或者创建 Markdown 格式的智能体（保存在 ~/.config/opencode/agents/ 或 .opencode/agents/ ）：

	---
	description: 代码审查智能体
	mode: subagent
	tools:
	write: false
	edit: false
	---

	你是一个代码审查专家。专注于：
	- 代码质量和最佳实践
	- 潜在的 bug 和边缘情况
	- 性能和安全问题

# Skills（技能）

# 权威定义

官方定义（Agent Skills 官网）：Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently.

# 底层本质

Skills 是 Agent 的「手脚」，是连接大模型语言理解能力与现实世界操作能力的唯一桥梁。没有 Skills 的 Agent，只能是「纸上谈兵」的文本生成器，无法完成任何需要实际操作的任务。

Skills 的 5 个核心标准特征（工业级落地必须严格遵守）：

单一职责原则：一个 Skill 只完成一件明确的事，禁止复合功能封装。例如「查询指定城市实时天气」是合格的 Skill，「查天气 + 生成出行建议 + 发邮件」是不合格的复合 Skill。
标准化接口规范：必须有明确的入参、出参、异常处理规范，完全兼容 JSON Schema 与 OpenAI Function Calling 格式。
可被 LLM 理解：必须有清晰、无歧义的功能描述（Description），明确说明「该 Skill 的用途、适用场景、入参含义、限制范围」，这是 LLM 准确调度的核心前提。
可观测可追溯：必须包含完整的调用日志、执行耗时、结果状态、异常信息上报，支持 Agent 的决策闭环与问题排查。
无状态与幂等性：Skill 执行不依赖全局状态，相同入参多次执行的结果一致，避免 LLM 重试调用时出现数据不一致问题。

# Skill 文件位置

OpenCode 从以下位置发现 Skills：

项目配置： .opencode/skills/<name>/SKILL.md
全局配置： ~/.config/opencode/skills/<name>/SKILL.md
Claude 兼容： .claude/skills/<name>/SKILL.md 、 ~/.claude/skills/<name>/SKILL.md
Agent 兼容： .agents/skills/<name>/SKILL.md 、 ~/.agents/skills/<name>/SKILL.md

# 创建 Skill

创建 .opencode/skills/git-release/SKILL.md ：

	---
	name: git-release
	description: 创建一致的发布和变更日志
	license: MIT
	compatibility: opencode
	---

	## 我能做什么
	- 从合并的 PR 中起草发布说明
	- 提出版本升级建议
	- 提供可复制的 `gh release create` 命令

	## 使用场景
	当你准备标记发布时使用此技能。
	如果目标版本方案不明确，请提出澄清问题。

# 使用 Skill

在对话中告诉 Agent 使用某个 Skill：

使用 git-release 技能帮我创建发布

# 配置 Skill 权限

可以在 opencode.json 中配置 Skill 权限：

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

权限说明：

allow ：立即加载
deny ：对 Agent 隐藏，拒绝访问
ask ：加载前提示用户确认

# MCP（模型上下文协议）

# 权威定义

The Model Context Protocol（MCP） 是由 Anthropic 于 2024 年 11 月发布的一个开放标准，定义了连接 AI 模型到外部工具、数据源和服务的通用接口。在 MCP 之前，每个 AI 集成都需要定制的、一次性的实现。MCP 标准化了 AI 客户端与外部能力的通信方式 —— 因此一次集成即可适配任何兼容的 AI 系统。

架构定义：MCP 是一种客户端 - 服务器协议 ——MCP 客户端是希望使用外部能力的 AI 系统（例如 Claude、Cursor、带 Copilot 的 VS Code），MCP 服务器是通过标准化 API 向外部能力（例如 GitHub、数据库、文件系统、浏览器）暴露这些能力的服务。
官方定义：MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems.

# 底层本质

MCP 不是工具、不是 Skill、不是插件，而是一套全球统一的「电网标准与插座规范」。

类比：Skill 是电器，MCP 是国家统一的 220V 插座规范；无论你是哪个厂家、用什么技术生产的电器（Skill），只要符合插座规范（MCP），就能插到任何符合规范的插座（支持 MCP 的 Agent）上使用，无需单独适配。

MCP 诞生的核心背景：解决 Agent 生态的碎片化痛点

在 MCP 诞生之前，Agent 生态处于严重的碎片化状态：

每个 Agent 框架（LangChain、LlamaIndex、AutoGPT）都有自己的 Tool 定义规范，互不兼容
Python 写的 Skill 无法被 Java 写的 Agent 调用，反之亦然，跨语言互操作成本极高
本地部署的 Skill 无法被云端 Agent 安全调用，环境隔离问题无法解决
开发者需要为每一个 Skill 单独编写适配代码，开发成本极高、扩展性极差

MCP 的出现，彻底解决了这些问题，为全球的 Agent 与 Skill 制定了一套统一的互操作标准。

# MCP 的核心设计原则（来自官方 v1.0 规范）

语言与运行时无关：无论 Skill 用 Java、Python、Go、Node.js 编写，只要符合 MCP 规范，就能被任何 Agent 调用
双向通信能力：既支持 LLM 向服务端发起 Skill 调用，也支持服务端向 LLM 推送事件、更新上下文
安全优先设计：内置细粒度权限控制、沙箱隔离、调用审计、签名校验，解决工具调用的核心安全问题
标准化能力模型：统一了 Tool（Skill）、上下文提示（Prompts）、资源（Resources）的定义规范，完全兼容 OpenAI Function Calling
轻量易实现：基于 JSON-RPC 2.0 标准，传输层支持 STDIO、HTTP、WebSocket，兼容性极强，开发成本极低

# MCP 的核心组件

MCP Client：部署在 Agent 端，负责向 MCP Host 发起能力发现、Skill 调用请求，接收执行结果
MCP Host：部署在 Skill 提供端，负责 Skill 的注册、暴露、请求校验、权限控制，转发请求给对应 Skill 执行
MCP Protocol：基于 JSON-RPC 2.0 的标准化通信规范，定义了所有请求、响应、事件的格式

# MCP 能做什么？

通过 MCP，OpenCode 可以连接各种外部服务：

GitHub：Issue 管理、PR 操作、代码搜索
Playwright：浏览器自动化
Sentry：错误监控
Context7：文档搜索
数据库：数据查询和操作
等等

# MCP 类型

# Local（本地部署）

本地部署 MCP Server：

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "@playwright/mcp@latest"
      ],
      "enabled": true
    }
  }
}

# Remote（远程部署）

连接远程 MCP Server：

{
  "mcp": {
    "github": {
      "type": "remote",
      "url": "https://api.githubcopilot.com/mcp/",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {file:~/.config/opencode/.secrets/github-pat}"
      }
    }
  }
}

# 使用 MCP

配置完成后，可以通过以下方式使用：

使用 github 列出我的所有仓库

或者在 AGENTS.md 中设置默认行为：

当你需要搜索文档时，使用 `context7` 工具。

# 常用 MCP Server

# GitHub MCP

{
  "mcp": {
    "github": {
      "type": "remote",
      "url": "https://api.githubcopilot.com/mcp/",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {file:~/.config/opencode/.secrets/github-pat}"
      }
    }
  }
}

# Context7 文档搜索

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    }
  }
}

# Sentry 错误监控

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

认证 Sentry：

opencode mcp auth sentry

# 三者对比与选择

# 什么时候用 Agent？

需要长期存在的任务执行单元
需要指定不同的模型
需要独立的工具权限控制

示例：创建一个代码审查 Agent，专门用于代码质量检查

# 什么时候用 Skills？

提供任务相关的指导文档
需要在多个 Agent 间共享的指令
轻量级的任务描述

示例：创建一个 Git 发布 Skill，提供发布流程指导

# 什么时候用 MCP？

需要连接外部服务或 API
需要扩展工具能力
需要访问第三方数据

示例：配置 GitHub MCP 来管理仓库

# 各层级的核心职责

# 1. 顶层：Agent 智能体层

唯一的决策主体，负责理解用户目标、拆解任务、制定执行计划
自主决策：基于推理结果，决策「什么时候、调用哪个 Skill、传入什么参数」
迭代推理：接收 Skill 执行结果，迭代推理，直到完成用户目标，形成完整闭环
异常处理：处理异常情况，执行重试、降级、终止等操作

# 2. 中间层：MCP 协议层

能力注册与发现：Agent 通过 MCP 获取所有可用的 Skill 列表
通信协议转换：将 Agent 的决策指令转换为标准化的 Skill 调用请求
全链路管控：负责请求校验、权限控制、限流熔断、调用审计
结果标准化返回：将 Skill 的执行结果封装为统一格式，返回给 Agent

# 3. 底层：Skills 能力层

唯一执行主体：负责完成具体的、单一的操作任务
外部交互：与外部环境、系统、数据源进行交互，完成实际操作
结果返回：处理执行过程中的异常，返回标准化的执行结果或错误信息
被动执行：不具备决策能力，只负责被动执行指令

# 总结

概念	选择场景
Agent	需要独立执行单元、专属模型、权限控制时
Skills	需要指导文档、多 Agent 共享指令时
MCP	需要连接外部服务、扩展工具能力时

在实际使用中，这三者常常配合使用。例如：你可以通过 Agent 创建专门的代码审查智能体，使用 Skills 来提供审查标准，并通过 MCP 来连接代码库获取信息。

通过灵活运用这三个概念，你可以将 OpenCode 打造成最适合自己工作流程的 AI 开发助手。

参考文档：

OpenCode 官方文档
OpenCode Agents
OpenCode Skills
OpenCode MCP Servers

# OpenCode 中 Agent、Skills 与 MCP 的区别与使用

# 一分钟理解三者区别

# Agent（智能体）

# 权威定义

# 底层本质

# Agent 类型

# Primary Agent（主智能体）

# Subagent（子智能体）

# 使用 Agent

# 创建自定义 Agent

# Skills（技能）

# 权威定义

# 底层本质

# Skill 文件位置

# 创建 Skill

# 使用 Skill

# 配置 Skill 权限

# MCP（模型上下文协议）

# 权威定义

# 底层本质

# MCP 的核心设计原则（来自官方 v1.0 规范）

# MCP 的核心组件

# MCP 能做什么？

# MCP 类型

# Local（本地部署）

# Remote（远程部署）

# 使用 MCP

# 常用 MCP Server

# GitHub MCP

# Context7 文档搜索

# Sentry 错误监控

# 三者对比与选择

# 什么时候用 Agent？

# 什么时候用 Skills？

# 什么时候用 MCP？

# 各层级的核心职责

# 1. 顶层：Agent 智能体层

# 2. 中间层：MCP 协议层

# 3. 底层：Skills 能力层

# 总结

23 种设计模式完整指南 - C++实现详解

在 OpenCode 里使用 GitHub MCP Server 访问 GitHub