Skill 是一个按需激活的指令包：用户描述匹配时，Agent 调用 activate 工具把这个技能的指令拉进上下文，然后按指令完成任务。未激活的技能不占用上下文。
适合给 Agent 加一段专业流程、模板或脚本——比如”分析 Python 项目”、“PDF 表单填充”、“代码评审”——而不必每个对话都把指令塞进 System Prompt。
与插件、MCP 的区别
| 你想做的事 | 用这个 |
|---|
| 按需触发的一段工作流（可带脚本、模板） | Skill |
| 接入已有的 MCP 工具服务 | MCP Server |
| 长期能力，需要配置页、事件、知识库 | 插件 |
安装技能
技能依赖沙箱：box.enabled 为 true 且 Docker / Nsjail / E2B 至少一个可用时，才能安装、激活和编辑技能。详见沙箱配置。 从 LangBot Space（首选）
LangBot Space 是 LangBot 的官方市场，已上架多种技能。在 WebUI 的 Skills 页面浏览并一键安装，无需自己编写 SKILL.md 或准备资源文件。
适合大多数场景。需要自定义流程再走下面的方式。
自己创建技能
WebUI — Skills 页面新建、上传 zip 包、从 GitHub 导入。
沙箱 + register_skill：
- 在沙箱
/workspace 下准备好目录和 SKILL.md
- 让 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. 给出按优先级排序的改进建议
| 字段 | 必需 | 说明 |
|---|
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 |
Skills 当前面向内置 Agent，依赖函数调用和沙箱后端。外部 Runner（Dify、n8n、Langflow、Coze 等）请使用各自平台的等价机制。
