Agent Skills实战：用OpenCode搭建AI技能系统完整教程

什么是Agent Skills：让模型临时学会新能力

最近Agent Skills（技能机制）被业界热议，很多人对它的理解并不精准——有人以为它是Prompt的升级版，有人认为它是工具调用的整合，还有人把它当成插件系统。这些理解都不够到位。

用一句话概括：Agent Skills是一套让模型在合适的时候临时学会新能力的机制。这里有三个关键词值得拆解：

合适的时候：只在真正需要时才触发调用，不浪费算力，也不过度消耗token。
临时能力：按需调用，而非常驻内存。
突破原生限制：比如解析PDF、执行脚本，让模型能做原本做不到的事。

这正是Agent Skills与MCP等既有方案产生差异的核心。要理解这一点，我们得先看清裸模型的局限。

Agent Skills技能加载机制示意

裸模型的天生短板

一个纯粹的大语言模型，如果不接入外部工具，很多事情根本做不了。举个直观的例子：在OpenCode里add一个PDF文件，让模型总结内容，它会直接告诉你「做不到」。

这不是因为模型参数不够智能，而是因为模型天生只会理解和生成文本，它并不知道PDF是什么结构，也无法解析它。大语言模型的核心架构是基于Transformer的自回归文本生成系统，它的训练数据是token化的文本序列，推理过程也是逐token预测下一个词。这意味着模型从根本上只理解序列化的文本信息——它没有"眼睛"去解析图像像素，没有"手"去操作文件系统，也没有内置的二进制解码器去理解PDF这种由Adobe定义的复杂文档格式。PDF文件内部包含交叉引用表、字体嵌入、图形流等结构化二进制数据，这些完全超出了语言模型的感知范围。模型本身的能力是受限的，这是一个绕不开的现实。

Skills与MCP的本质区别：渐进式披露

过去要突破这种限制，业界主要有三种方式：在Prompt里塞规则、用Function Calling执行外部代码返回结果、以及使用MCP这样的全量工具协议。而Agent Skills走的是第四条路。

Function Calling是OpenAI在2023年中期率先推广的一种机制，它允许模型在对话中生成结构化的JSON输出，声明自己想要调用某个预定义的外部函数及其参数。系统接收到这个声明后，在模型外部执行实际的函数逻辑，再将执行结果返回给模型继续推理。这种机制本质上是一种"模型出决策、外部出执行"的分工模式，但它要求在每次请求的system prompt中完整描述所有可用函数的schema定义，包括函数名、参数类型、参数描述等，这正是上下文膨胀问题的来源之一。

而MCP（Model Context Protocol，模型上下文协议）是Anthropic于2024年底正式发布的开放标准协议，旨在为AI模型与外部数据源、工具之间建立统一的连接方式。它的设计哲学类似于USB-C——提供一个标准化的"插口"，让任何工具都能以统一的方式接入模型。MCP采用客户端-服务器架构，通过JSON-RPC 2.0进行通信，支持工具调用、资源访问和提示模板三种核心原语。

传统方案的三大痛点

无论是Prompt还是MCP，本质上都是提前告诉模型「你可以做A、B、C，每一个怎么做，规则是这样那样……」，然后跟上一大堆说明。问题在于：不管你用不用，每次对话都要把这些规则全塞进上下文。

这会带来三个严重后果：

上下文越来越长，使用成本随之升高；
token消耗持续攀升；
模型注意力被大量规则和解释分散，无法聚焦在核心业务上。

这里的第三点值得深入理解——Transformer的自注意力计算复杂度与序列长度的平方成正比（O(n²)），当大量无关的工具描述占据上下文窗口时，不仅增加了计算开销，还会稀释模型对真正关键信息的注意力权重分配，导致推理质量下降。MCP的"全量暴露"特性意味着所有已注册的工具描述都需要在每次交互中注入上下文窗口，当工具数量增长到几十甚至上百个时，这种上下文占用会急剧膨胀。

Skills的两层信息设计

Agent Skills反其道而行之。它平时只告诉模型有哪些技能的名字和描述，具体怎么做暂时不说。因此每个Skill对模型可见的只有两层信息：

名称：技能叫什么；
描述：告诉模型什么时候该用它。

而具体的执行规则、调用方式、操作细节，对模型是隐藏的。只有当模型执行任务、恰好需要用到某个技能时，才会加载该Skill的完整内容。这一步就是所谓的按需加载（懒加载）。

这种按需加载的思想在软件工程中有着深厚的渊源。Lazy Loading是经典的工程模式，广泛应用于数据库ORM、前端资源加载、操作系统内存管理等场景。例如，现代网页的图片懒加载——只有当用户滚动到图片可视区域时才真正发起HTTP请求下载图片数据，而非页面打开时一次性加载所有图片。在操作系统层面，虚拟内存的分页机制也是类似思路：物理内存只加载当前正在使用的页面，其余数据驻留在磁盘上。Agent Skills将这一思想迁移到了AI上下文管理中，实现了"声明式注册、运行时加载"的模式，有效缓解了大模型上下文窗口这一稀缺资源的压力。

打个通俗的比方：你脑子里知道自己有某项技能，但具体怎么操作暂时不用记，只有真正用到时才去翻说明书。而MCP模式则像是——每次做事前，先把所有说明书通读一遍。

Agent Skills vs MCP：工程思维对比协议思维

这两者的对比可以清晰地列出来：

维度	Agent Skills	MCP
加载方式	只加载名字和描述，用到才加载细节	全量加载，不管用不用
上下文占用	极大节省	工具越多越爆炸
决策模式	模型自主判断要不要用、用哪个	工具全摆面前，按规则选
扩展性	可无限增加技能而不拖慢对话	工具越多成本延迟越高
定位	更像智能体	更像工具箱

一句话总结：Skills是渐进式披露的工程思维，MCP是一次性暴露的协议思维。

"渐进式披露"（Progressive Disclosure）并非AI领域的原创概念，它最早来自人机交互（HCI）设计理论，由IBM研究员在1980年代提出。核心思想是：在任何时刻只向用户展示他们当前阶段所需的信息和操作选项，高级功能隐藏在更深的层级中。这个原则在软件设计中极为常见——比如Word的"更多选项"折叠菜单、iOS的设置分层结构。Agent Skills将这一设计哲学引入AI工程领域，让模型平时只感知技能的"标题和摘要"，相当于只看到菜单上的菜名，而非每道菜的完整食谱。在规模化的实际工程中，Skills明显更具优势。

实战搭建：基于OpenCode的完整流程

由于原生Claude Code存在一些使用限制，本次实战采用其开源替代方案OpenCode（官网opencode.ai）来演示。OpenCode是一款开源的终端AI编程助手，与Claude Code需要绑定Anthropic订阅不同，OpenCode支持接入多种模型提供商的API，包括OpenAI、Anthropic、智谱AI、DeepSeek等，给用户提供了更大的灵活性和成本控制空间。它运行在命令行环境中，能够直接访问本地文件系统、执行shell命令，这使得它天然具备了Agent化操作的基础。其Skills机制的实现借鉴了Claude Code的.claude/commands和CLAUDE.md等设计，但在开放性和可扩展性上做了进一步增强。

环境准备

首先需要安装Node.js。Node.js是基于Chrome V8引擎构建的JavaScript运行时环境，它让JavaScript得以在服务端和命令行环境中运行，是现代前端工具链和大量CLI工具的基础运行环境。安装过程比较简单，一路下一步即可，装完后用node -v命令验证版本号是否正常输出。

Node.js安装验证版本号

接着到OpenCode官网，根据系统选择安装方式：带base命令的适用于Mac，Windows用户则使用对应命令（前提是已装好Node.js）。复制命令后回车即可完成安装，然后输入opencode启动开发工具。

配置模型

启动后有几个常用命令值得注意。输入/models可查看已有模型。如果没有配置过API，通常只有一个不太稳定的免费模型。

要接入更稳定的模型（如智谱GLM-4.7），可输入/connect，搜索「智谱AI」，回车后填入从官方平台获取的API Key（没有就创建一个新Key）。智谱AI是国内领先的AI大模型公司，其GLM系列模型在中文理解和代码生成方面表现出色，且API定价相对友好，适合作为开发调试阶段的主力模型使用。配置成功后，对应模型会高亮显示。

OpenCode配置模型API Key

验证本地文件操作能力

配置完成后，先测试OpenCode的本地文件操作能力。比如让它「写一首关于AI的现代诗并保存到.txt文件」，它会直接在当前路径下完成写入操作。这展示了OpenCode相比普通对话工具的关键差异——它能直接操作本地目录。这种能力源于OpenCode在终端环境中的运行方式：它拥有当前用户的文件系统权限，可以通过执行shell命令来创建、读取、修改和删除文件，这是纯Web端对话工具所不具备的能力，也是Agent化操作的基础前提。

加载官方技能库：让模型学会读PDF

复现模型的局限

先复现前面提到的痛点：在当前目录下放一个PDF，让OpenCode读取「第6页的内容」。结果不出所料——它回复「无法读取PDF文件，请将其转成文本格式」。这正是裸模型无法读取外部文件的典型表现。

引入Anthropic官方Skills技能库

解决方案是使用Anthropic官方提供的技能库。Anthropic是Claude系列模型的开发公司，由前OpenAI研究副总裁Dario Amodei创立，在AI安全和大模型领域处于全球领先地位。其官方技能库是专门为Agent化工作流设计的预制技能集合。进入其GitHub仓库，找到skills源码，直接下载压缩包。这些官方技能覆盖了PDF操作、PPT处理、主题工厂、Web App等多种场景。

配置步骤如下：

复制官方技能文件；
进入用户配置目录config/opencode；
若没有skills文件夹，手动创建一个；
将技能文件粘贴进去；
重启OpenCode使配置生效。

Skills技能文件配置完成

效果验证

重启后询问「当前有哪些skills」，模型便能正确读取到刚加载的全部技能。注意，此时模型只是"知道"这些技能的名称和描述，并未加载它们的具体执行逻辑——这正是渐进式披露原则的体现。

这时再次让它「利用skills读取文档第6页内容」，可以看到它开始主动调用相应技能——从skill中不仅读取描述，还执行了内置的Python脚本。这里的Python脚本通常依赖PyPDF2或pdfplumber等PDF解析库，这些库能够解码PDF的二进制结构，提取出纯文本内容，再以模型可理解的文本格式返回给上下文。

脚本成功运行后，模型准确报告「文档共121页」，并提取出第6页关于「模型算法发展历程」的内容。经人工核对，读取内容准确无误。这就是Agent Skills带来的深层次能力加载效果——模型的能力边界从"只能处理文本"扩展到了"能调度外部工具处理任意格式的数据"。

两种配置模式与工程价值

Skills支持两种配置方式：

全局配置：所有项目通用，技能文件存放在用户级别的配置目录中，适合放置通用性强的基础技能，如文件格式转换、通用数据处理等；
项目级配置：仅在当前特定目录下生效，技能文件存放在项目根目录的配置文件夹中，适合放置与特定项目强相关的专属技能，如特定框架的代码生成规范、项目专属的部署流程等。

这种分层配置的设计思路与Git的.gitconfig（全局）和.gitattributes（项目级）类似，让开发者可以在不同粒度上灵活管理技能集合。

借助Agent Skills，OpenCode具备了更强大的本地执行能力——批量处理文档、整理文件夹、执行自动化任务都成为可能。通过加载官方技能库，AI在文档处理、内容创作、数据分析等场景实现了能力跃迁。

更重要的是，这种模式让AI从简单对话进化为真正的工程化执行方式。相比MCP的全量协议，拥抱Agent Skills意味着更低的成本、更高的效率、更强的扩展性，这正是构建规模化智能AI工作流的关键所在。随着开源社区持续贡献更多高质量的技能模板，Agent Skills有望成为AI工程化落地中不可或缺的基础设施层。