技能

技能（Skill）是由 Anthropic 所提出的标准发布的格式，用于扩展 AI 代理能力、补充专业知识与工作流程。一个技能即一个包含 SKILL.md 文件的文件夹，写清某类任务该怎么做，模型会按需加载。

发现技能与优先级

Bub 按以下优先级顺序自动发现并加载技能。同名时以最先找到的为准：

1. 工作区目录：<workspace>/.agents/skills/（旧目录 .agent/skills/ 仍兼容）
2. 用户全局目录：~/.agents/skills/
3. 已安装包：环境中所有已安装的 skills 命名空间包（含 Bub 自带的内置技能）

内置技能

安装 Bub 应用时自带三个技能：

技能	用途	外部依赖
telegram	发送、回复和编辑 Telegram 消息	Telegram Bot token
gh	通过 GitHub CLI 管理仓库、Issue、PR 和 Actions	安装并认证 gh
skill-creator	指导创建或更新技能	无

编写技能

可以试着在当前工作区或全局用户目录下试着创建一个技能，例如 .agents/skills/repo-map/SKILL.md：

---
name: repo-map
description: 修改代码前，先阅读本地仓库结构。
---

1. 运行 `rg --files`，查看仓库结构。
2. 阅读能够说明本次修改的文件。
3. 编辑代码前，说明会涉及哪些模块。

字段与变量规范

SKILL.md 的 YAML frontmatter 规范如下：

字段	要求
name	必填；必须与所在的技能目录名完全一致；仅限小写字母、数字和连字符；最多 64 个字符
description	必填；清晰说明适用任务和触发场景，供模型判断何时选用该技能；最多 1,024 个字符
metadata	可选；键值对映射，键和值都必须是字符串

配套的辅助脚本或参考文件可存放在技能目录下的 scripts/、references/ 或 assets/ 中。技能正文支持以下动态变量插值：

变量	展开结果
$SKILL_DIR	当前技能目录的绝对路径
$PYTHON	运行 Bub 的 Python 解释器路径
${config.path.to.value}	Bub 配置文件中对应字段的值

技能中的脚本不会自动执行。正文中应指引模型调用对应工具执行脚本，并确保环境已安装所需外部依赖（如本例需安装 rg）。

当然，如果你不想自己手动创建技能，可以委托给你的 Agent 工具或是 Bub 应用来创建技能，例如：

bub run '使用 $skill-creator 技能，创建一个名为 `repo-map` 的技能，主要流程是：
1. 运行 `rg --files`，查看仓库结构。
2. 阅读能够说明本次修改的文件。
3. 编辑代码前，说明会涉及哪些模块。'

验证与使用

在 Bub 应用中可以通过以下方式调用技能：

命令	说明
bub run ",skill"	列出当前工作区实际发现的技能
bub run ",skill name=repo-map"	打印变量展开后的正文，不调用模型；返回 (no such skill) 时检查目录名与 name 是否一致
bub run '使用 $repo-map 技能，然后列出你找到的顶层模块。'	把正文展开进本轮对话的系统提示词，模型据此调用工具完成后续步骤

注意

未显式写出 $skill-name 时，模型仍会依据技能的 description 自主判断是否采用。

随 Python 包分发

技能可通过插件包进行分发。关于如何组织插件包目录结构、配置打包以及独立环境发布验证，详见打包与分发。