一款开源 AI 编程助手的进阶玩法# OpenCode 进阶玩法Skills、MCP 与 Custom Agents 实战指南一、什么是 OpenCodeOpenCode 是一款开源的 AI 编程代理Coding Agent拥有160K GitHub Stars每月服务750 万 开发者。它可以在终端、桌面应用或 IDE 扩展中运行支持接入 Claude、GPT、DeepSeek、Gemini 等主流大模型。核心特点LSP 集成— 自动加载项目 LSP让 LLM 理解代码语义多会话— 在同一个项目中并行启动多个代理任意编辑器— 终端 CLI、桌面 App、IDE 扩展均可隐私优先— 不存储你的代码或上下文数据快速安装# 一键安装curl-fsSLhttps://opencode.ai/install|bash# 或使用 npmnpminstall-gopencode-ai进入项目目录后运行opencode首次使用执行/init初始化即可。二、深入理解 Skills技能系统Skills 是 OpenCode 的一大亮点它支持你编写可复用的指令集代理能够按需发现和加载这些技能。2.1 Skills 的工作原理当你向 OpenCode 提问时它会根据当前上下文判断需要调用哪个 Skill。Skills 通过skill工具按需加载而非一次性注入所有指令这大大节省了宝贵的上下文 Token。2.2 创建你的第一个 SkillSkill 就是一个包含 YAML 前置元数据的SKILL.md文件。存放位置任意一个均可位置路径项目级.opencode/skills/name/SKILL.md全局级~/.config/opencode/skills/name/SKILL.mdClaude 兼容.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 实践项目级 Skillscode-review— 代码审查规范git-commit— 提交信息格式约定testing— 测试规范和命令deploy— 部署流程团队级 Skillsarchitecture— 架构决策记录onboarding— 新人指引coding-standards— 编码规范三、MCP 服务器深度集成MCPModel 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# 登出某个 MCPopencode mcplogoutsentry3.4 推荐的 MCP 服务器MCP 服务器类型用途配置参考Sentry远程查询错误和性能数据url: https://mcp.sentry.dev/mcpContext7远程搜索技术文档url: https://mcp.context7.com/mcpGrep by Vercel远程搜索 GitHub 代码片段url: https://mcp.grep.appPlaywright本地浏览器自动化测试command: npx playwright/mcpGitHub本地管理 Issue/PRcommand: npx modelcontextprotocol/server-github3.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 示例EffectOpenCode 项目使用 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 AgentsOpenCode 团队还创建了自定义代理来处理 GitHub Issue 和 PR 工作流。例如triage代理— 用于 Issue 分类duplicate-pr代理— 用于检测重复 PR这些代理配置在.opencode/agent/目录下通过 Markdown 文件定义。5.4 从官方实践中学到的Skill 要具体— 针对特定技术栈如 Effect编写而非笼统的写代码规范引用外部源码— Skill 可以指导 AI 先 clone 参考仓库保证技术准确性按需关闭工具— 不需要的 MCP 工具设为false节省 Token代理分工— 不同任务用不同代理triage / duplicate-pr职责清晰六、常见问题与避坑指南6.1 MCP 占用上下文太多MCP 工具会快速占用 Token 预算。建议只启用真正需要的 MCP按代理分配 MCP而非全局开启对 GitHub 等重型 MCP 尤其注意6.2 Skill 不显示排查步骤文件名必须是SKILL.md全大写YAML 前置元数据必须有name和descriptionSkill 名称在所有位置必须唯一检查权限配置是否为deny6.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 社区。
OpenCode 教程:Skills 与 MCP 从入门到精通
发布时间:2026/5/31 1:34:08
一款开源 AI 编程助手的进阶玩法# OpenCode 进阶玩法Skills、MCP 与 Custom Agents 实战指南一、什么是 OpenCodeOpenCode 是一款开源的 AI 编程代理Coding Agent拥有160K GitHub Stars每月服务750 万 开发者。它可以在终端、桌面应用或 IDE 扩展中运行支持接入 Claude、GPT、DeepSeek、Gemini 等主流大模型。核心特点LSP 集成— 自动加载项目 LSP让 LLM 理解代码语义多会话— 在同一个项目中并行启动多个代理任意编辑器— 终端 CLI、桌面 App、IDE 扩展均可隐私优先— 不存储你的代码或上下文数据快速安装# 一键安装curl-fsSLhttps://opencode.ai/install|bash# 或使用 npmnpminstall-gopencode-ai进入项目目录后运行opencode首次使用执行/init初始化即可。二、深入理解 Skills技能系统Skills 是 OpenCode 的一大亮点它支持你编写可复用的指令集代理能够按需发现和加载这些技能。2.1 Skills 的工作原理当你向 OpenCode 提问时它会根据当前上下文判断需要调用哪个 Skill。Skills 通过skill工具按需加载而非一次性注入所有指令这大大节省了宝贵的上下文 Token。2.2 创建你的第一个 SkillSkill 就是一个包含 YAML 前置元数据的SKILL.md文件。存放位置任意一个均可位置路径项目级.opencode/skills/name/SKILL.md全局级~/.config/opencode/skills/name/SKILL.mdClaude 兼容.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 实践项目级 Skillscode-review— 代码审查规范git-commit— 提交信息格式约定testing— 测试规范和命令deploy— 部署流程团队级 Skillsarchitecture— 架构决策记录onboarding— 新人指引coding-standards— 编码规范三、MCP 服务器深度集成MCPModel 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# 登出某个 MCPopencode mcplogoutsentry3.4 推荐的 MCP 服务器MCP 服务器类型用途配置参考Sentry远程查询错误和性能数据url: https://mcp.sentry.dev/mcpContext7远程搜索技术文档url: https://mcp.context7.com/mcpGrep by Vercel远程搜索 GitHub 代码片段url: https://mcp.grep.appPlaywright本地浏览器自动化测试command: npx playwright/mcpGitHub本地管理 Issue/PRcommand: npx modelcontextprotocol/server-github3.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 示例EffectOpenCode 项目使用 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 AgentsOpenCode 团队还创建了自定义代理来处理 GitHub Issue 和 PR 工作流。例如triage代理— 用于 Issue 分类duplicate-pr代理— 用于检测重复 PR这些代理配置在.opencode/agent/目录下通过 Markdown 文件定义。5.4 从官方实践中学到的Skill 要具体— 针对特定技术栈如 Effect编写而非笼统的写代码规范引用外部源码— Skill 可以指导 AI 先 clone 参考仓库保证技术准确性按需关闭工具— 不需要的 MCP 工具设为false节省 Token代理分工— 不同任务用不同代理triage / duplicate-pr职责清晰六、常见问题与避坑指南6.1 MCP 占用上下文太多MCP 工具会快速占用 Token 预算。建议只启用真正需要的 MCP按代理分配 MCP而非全局开启对 GitHub 等重型 MCP 尤其注意6.2 Skill 不显示排查步骤文件名必须是SKILL.md全大写YAML 前置元数据必须有name和descriptionSkill 名称在所有位置必须唯一检查权限配置是否为deny6.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 社区。