> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langbot.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 技能 (Skills)

> 在 LangBot 中使用技能（Skills），按需加载专业知识，扩展 AI Agent 而不撑爆上下文。

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

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

## 与插件、MCP 的区别

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

详见[运行时与扩展关系](../sandbox/runtime-relationships)。

## 安装技能

<Note>
  技能依赖沙箱：`box.enabled` 为 `true` 且 Docker / Nsjail / E2B 至少一个可用时，才能安装、激活和编辑技能。详见[沙箱配置](../sandbox/config)。
</Note>

### 从 LangBot Space（首选）

[LangBot Space](https://space.langbot.app) 是 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 激活后会收到的指令：

```markdown theme={null}
---
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](https://agentskills.io/home)。其它字段（`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 等）请使用各自平台的等价机制。
</Note>