road-map
skill作者：小傅哥
apm::install
apm install @fuzhengwei/road-mapapm::skill.md
---
title: agent-skills
lock: need
---
# Agent Skill，你记一下，我做如下部署调整！
作者：小傅哥
<br/>博客：[https://bugstack.cn](https://bugstack.cn)
> 沉淀、分享、成长，让自己和他人都能有所收获！😄
<iframe id="B-Video" src="//player.bilibili.com/player.html?isOutside=true&aid=115890381129183&bvid=BV1PprJBeEmY&cid=35370763226&p=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" width="100%" height="480"> </iframe>
大家好，我是技术UP主小傅哥。
skill 是什么？它像是一本技能书📚，把一阳指（`mcp/py/shell/js`）和狮吼功（`prompt`）合成了一整招。缩短了从用户把提示词发给AI客户端，进行分析，决策，再到 mcp 执行的过程，**让诉求直达结果**，token 减少了，幻觉减少了！
<div align="center">
<img src="https://bugstack.cn/images/roadmap/tutorial/road-map-agent-skill-00.png" width="250px">
</div>
随着 LLM 大模型能力的不断提升，并与 RAG、MCP、Skill 的结合，使得 Agent 智能体与完整的计算机环境（Computer/Phone）交互成为可能。这个过程中，一方面不断产生新的技术方案，一方面又不断的优化设计。就像 Skill 的出现，它不是替代 MCP，而是更准确的使用 MCP 能力。
接下来，小傅哥就带着大家使用一波 skill，让小伙伴们可以在 opencode、trae.ai，以及基于 Spring AI 也可以使用上 skill 能力。
## 一、skill 和 prompt + mcp
如图，演示了一段 skill 的编写案例；
<div align="center">
<img src="https://bugstack.cn/images/roadmap/tutorial/road-map-agent-skill-02.png" width="850px">
</div>
- 场景：案例中体现的是，对电脑性能检测后，用一段下达命令的方式，告知用户如何优化电脑性能。
- 重点：如果不使用 skill，则需要描述一大段话术，让 ai 自己完成对用户场景诉求的分析，并按照步骤来调用对应的各个 mcp 服务（没有 skill 则需要把各类内容，都包装为 mcp 服务）。这个过程是比较消耗 token 的，也可能有不小的幻觉。现在有了 skill，我们可以适当的完整的写一段诉求文档，文档里嵌入可执行的脚本/mcp服务，让执行更可靠。
- 用途：那都有哪些场景可以写 skill 技能书呢？🤔 如；互联网公司里的系统巡检，在接收到报警日志后，拿到一个报警的系统和接口信息，之后用 skill 技能书，分别采集出对应的系统配置、上线日志、数据库/缓存情况、运营操作记录、全链路监控上的接口耗时情况等。之后在根据我们日常排查问题的时候经验，编写过程步骤，这样会更加准确。
> 所以，不是 skill、mcp 谁替代谁，而是 skill 对 mcp 进行增强，让 ai 执行时更加可靠。
## 二、配置使用
首先，像是市面上的 claude code、opencode 这些软件，都是支持了 skill 技能书配置使用的，如果遇到一些软件暂时还不支持 skill，或者自己使用 spring ai、langchain4j、google adk 构建的智能体时候需要使用 skil 技能，则可以通过 skillport-mcp 来使用 skill 配置。
这里小傅哥分别演示下 opencode、trae.ai + mcp、spring ai + google adk + mcp 的方式使用 skill；
### 1. 测试工程(skill)
<div align="center">
<img src="https://bugstack.cn/images/roadmap/tutorial/road-map-agent-skill-03.png" width="300px">
</div>
- 地址：[https://github.com/fuzhengwei/xfg-dev-tech-agent-skills](https://github.com/fuzhengwei/xfg-dev-tech-agent-skills)
- 说明：
- 工程里 `docs/skills` 下面就是一个个技能书，battle-plan、pdf，每一个技能书下都必须有一个 SKILL.md 文件，作为入口。这个文件，可以描述 prompt 提示词，以及在提示词中明确给出可执行的脚本(py\shell\js)和可参考的文档。
- 此外，在 xfg-dev-tech-app 下，test 里编码的是 SpringAiToolTest 测试技能书案例。
### 2. opencode 使用
- 文档：[https://opencode.ai/docs/skills/](https://opencode.ai/docs/skills/)
- 安装：[https://bugstack.cn/md/road-map/ai-ssh-opencode.html](https://bugstack.cn/md/road-map/ai-ssh-opencode.html) - `做好了安装脚本，方便小白伙伴使用`
#### 2.1 配置skill
```java
fuzhengwei@fuzhengweideMacBook-Pro-2 skill % ls
battle-plan
fuzhengwei@fuzhengweideMacBook-Pro-2 skill % pwd
/Users/fuzhengwei/.opencode/skill
fuzhengwei@fuzhengweideMacBook-Pro-2 skill % cd battle-plan
fuzhengwei@fuzhengweideMacBook-Pro-2 battle-plan % ls
reference.md scripts SKILL.md
fuzhengwei@fuzhengweideMacBook-Pro-2 battle-plan %
```
进入到 opencode 配置文件下，如果是 linux 一般会放到 `/root/.config/opencode/` 下。首先你要进入到这个 opencode 配置文件夹，之后在这个文件夹添加一个 skill，再之后就在 skill 下创建你的具体的技能书了。现在你可以把 xfg-dev-tech-agent-skills 案例工程的技能书，battle-plan 放到 skill 里。
#### 2.2 开启skill
```java
fuzhengwei@fuzhengweideMacBook-Pro-2 ~ % cd /Users/fuzhengwei/.opencode
fuzhengwei@fuzhengweideMacBook-Pro-2 .opencode % ls
bin node_modules package.json
bun.lock opencode.json skill
fuzhengwei@fuzhengweideMacBook-Pro-2 .opencode % cat opencode.json
{
"permission": {
"skill": {
"pr-review": "allow",
"internal-*": "deny",
"experimental-*": "ask",
"*": "allow"
}
},
"$schema": "https://opencode.ai/config.json"
}% fuzhengwei@fuzhengweideMacBook-Pro-2 .opencode %
```
- 注意 `opencode.json` 需要配置下 `"*": "allow"`
#### 2.3 使用skill
<div align="center">
<img src="https://bugstack.cn/images/roadmap/tutorial/road-map-agent-skill-04.png" width="600px">
</div>
- 提问：`基于 skill 解答，电脑性能优化`
- 说明：这里的`电脑性能优化`就是 skill 工具名称的描述。
### 3. trae.ai + mcp + skill
#### 3.1 工具说明
工具：[https://github.com/gotalab/skillport](https://github.com/gotalab/skillport)
目前还有不少 AI Agent 智能体，在底层设计上，还不支持直接使用 skill，也包括一些 ai 组件框架，也都没有 skill 的直接支持。那么这里要引入一个 skillport-mcp 服务来解决。借助 mcp 能力，使用 skill。
#### 3.2 工具安装
```java
# 需要安装 python3
pip3 config set global.index-url http://mirrors.aliyun.com/pypi/simple/
pip3 install uvx
```
- 安装 skillport 前，要确保本地安装了 pyhton/python3 环境。之后有 uvx 的安装。
```java
pip3 install skillport
# or: uv tool install skillport
```
- 如果安装过程中遇到一些失败的问题，可以用 trae.ai 里面执行安装，之后把报错拖进去提问。
#### 3.3 mcp 配置
<div align="center">
<img src="https://bugstack.cn/images/roadmap/tutorial/road-map-agent-skill-05.png" width="600px">
</div>
```java
{
"mcpServers": {
"skillport": {
"command": "uvx",
"args": ["skillport-mcp"],
"env": { "SKILLPORT_SKILLS_DIR": "~/.skillport/skills" }
}
}
}
```
- 这里你要配置下自己 skill mcp 服务，到你的 trae.ai 中。确保一定安装好了 python 环境，可以执行 `pip3 install skillport` 安装。
#### 3.4 工具使用
<div align="center">
<img src="https://bugstack.cn/images/roadmap/tutorial/road-map-agent-skill-01.png" width="400px">
</div>
当你选择 Builder with MCP（涵盖了skillport-mcp），之后提问 `基于 skill 解答，电脑性能优化` 那么就可以得到上面的命令了。
### 4. spring ai + skill
```java
public class SpringAiToolTest {
private static final Logger log = LoggerFactory.getLogger(SpringAiToolTest.class);
public static void main(String[] args) {
OpenAiApi openAiApi = OpenAiApi.builder()
.baseUrl("https://apis.itedus.cn")
.apiKey("sk-efen7WX8Q8vGvBps3f7c9a34578d41BbBc508dC5Df33A9Fb")
.completionsPath("v1/chat/completions")
.embeddingsPath("v1/embeddings")
.build();
ChatModel chatModel = OpenAiChatModel.builder()
.openAiApi(openAiApi)
.defaultOptions(OpenAiChatOptions.builder()
.model("gpt-4.1")
.toolCallbacks(new ArrayList<>() {{
addAll(List.of(sseMcpClient()));
}})
.build())
.build();
// String call = chatModel.call("你哪有哪些 skill 工具能力");
String call = chatModel.call("基于 skill 解答，电脑性能优化");
log.info("测试结果:{}", call);
}
/**
* https://github.com/gotalab/skillport
* pip3 config set global.index-url http://mirrors.aliyun.com/pypi/simple/
* pip3 config set install.trusted-host mirrors.aliyun.com
* pip3 config list
* pip3 install uvx
*/
public static ToolCallback[] sseMcpClient() {
ServerParameters stdioParams = ServerParameters.builder("uvx")
.args("skillport-mcp")
.env(new HashMap<>() {{
put("SKILLPORT_SKILLS_DIR", "/Users/fuzhengwei/coding/gitcode/KnowledgePlanet/road-map/xfg-dev-tech-agent-skills/docs/skills");
}})
.build();
McpSyncClient mcpSyncClient = McpClient.sync(new StdioClientTransport(stdioParams, new JacksonMcpJsonMapper(new ObjectMapper())))
.requestTimeout(Duration.ofSeconds(35000)).build();
McpSchema.InitializeResult initialize = mcpSyncClient.initialize();
return SyncMcpToolCallbackProvider.builder().mcpClients(mcpSyncClient).build()
.getToolCallbacks();
}
}
```
- 在 Spring AI 程序中，添加 `skillport-mcp` 服务，之后在 ChatModel 模型里，使用 mcp 服务。
- 如果你正在开发一些 AI Agent，那么也可以把 `skillport-mcp` 配置进去使用。如小傅哥带着做 [AI Agent 智能体项目](https://bugstack.cn/md/project/ai-knowledge/ai-knowledge.html) 你现在可以加进去更多的扩展操作了。