zh usage skills readme

技能 (Skills)

Skill 是一个按需激活的指令包：用户描述匹配时，Agent 调用 activate 工具把这个技能的指令拉进上下文，然后按指令完成任务。未激活的技能不占用上下文。

适合给 Agent 加一段专业流程、模板或脚本——比如"分析 Python 项目"、"PDF 表单填充"、"代码评审"——而不必每个对话都把指令塞进 System Prompt。

与插件、MCP 的区别

你想做的事	用这个
按需触发的一段工作流（可带脚本、模板）	Skill
接入已有的 MCP 工具服务	MCP Server
长期能力，需要配置页、事件、知识库	插件

详见运行时与扩展关系。

安装技能

Note

技能依赖沙箱：box.enabled 为 true 且 Docker / Nsjail / E2B 至少一个可用时，才能安装、激活和编辑技能。详见沙箱配置。

从 LangBot Space（首选）

LangBot Space 是 LangBot 的官方市场，已上架多种技能。在 WebUI 的 Skills 页面浏览并一键安装，无需自己编写 SKILL.md 或准备资源文件。

适合大多数场景。需要自定义流程再走下面的方式。

自己创建技能

WebUI — Skills 页面新建、上传 zip 包、从 GitHub 导入。

沙箱 + register_skill：

1. 在沙箱 /workspace 下准备好目录和 SKILL.md
2. 让 Agent 调用 register_skill(path="/workspace/my-skill")

两种方式都会写入 Box Runtime 管理的 skill store。

在流水线启用

技能装好之后，还要在流水线扩展配置里决定 Agent 能看到哪些：

• 开启"启用所有技能"，或
• 只绑定指定技能

绑定只影响 <available_skills> 列表（即 Agent 能从哪些技能里挑），完整指令永远等 activate 被调用后才注入。

编写 SKILL.md

技能就是一个目录加一个 SKILL.md。frontmatter 写元数据，正文是 Agent 激活后会收到的指令：

---
name: code-reviewer
display_name: 代码评审助手
description: 审查代码并给出改进建议；用户提到 review、评审、代码改进时触发
---

## 执行步骤

1. 用 `read` 浏览相关文件
2. 检查可读性、潜在 bug、安全问题
3. 给出按优先级排序的改进建议

LangBot 当前读取以下三个字段：

字段	必需	说明
name	创建/注册时	唯一标识，1–64 字符
description	强烈建议	Agent 用它判断何时激活——越具体越能选中
display_name	否	UI 显示名

description 是 Agent 挑技能的唯一依据，要写清楚功能、适用场景、可能的触发关键词。

完整规范见 agentskills.io。其它字段（license、metadata 等）可保留供未来兼容，当前不会被读取。

带资源的技能在 SKILL.md 同级放 scripts/、templates/ 等目录，激活后 Agent 通过 /workspace/.skills/{skill-name}/ 访问。

Agent 可用的工具

工具	用途
activate	Agent 判断匹配时自动调用，把 SKILL.md 拉进上下文
register_skill	把沙箱里准备好的目录注册为新技能

常见问题

现象	检查项
技能列表为空	box.enabled、Box Runtime 状态、box.local.skills_root
Agent 不激活技能	description 是否具体、流水线是否绑定、模型是否支持函数调用
激活后找不到文件	文件需在 Skill 包内，路径是 /workspace/.skills/{skill-name}/
register_skill 报错	路径必须在 /workspace 下，目录或两层内子目录需含 SKILL.md

Note

Skills 当前面向内置 Agent，依赖函数调用和沙箱后端。外部 Runner（Dify、n8n、Langflow、Coze 等）请使用各自平台的等价机制。