为应用打包 skills

skill 为 Bub 应用提供完成任务的流程。项目专用的 skills 可以留在工作区，也可以随 Python 包分发，让其他用户安装使用。

第一次编写本地 skill，请从添加项目 skill开始。本页说明发现机制和打包方式。自动发现 skills 是应用提供的行为；普通 core.Agent 使用你显式传入的指令。

编写 Bub 能加载的 skill

每个 skill 目录包含带 YAML frontmatter 的 SKILL.md：

---
name: my-skill
description: 说明这个 skill 帮助 agent 完成什么任务。
---

在这里编写流程。

Bub 发现 skills 时会检查这些字段：

字段	要求
name	与目录名一致；使用连字符分隔的小写单词；最多 64 个字符
description	非空字符串，最多 1,024 个字符
metadata	可选映射，键和值都必须是字符串

流程需要配套文件时，可以在 SKILL.md 旁添加 scripts/、references/ 或 assets/。正文中的 $SKILL_DIR 会展开为 skill 所在目录，$PYTHON 会展开为运行 Bub 的解释器路径。应用配置可以用 ${config.path.to.value} 引用。

确认应用会选择哪个 skill

应用默认依次搜索以下位置，同名时使用最先找到的 skill：

1. <workspace>/.agents/skills/
2. ~/.agents/skills/
3. 已安装的 skills 命名空间包，包括 Bub 自带的 skills

因此，项目中的 skill 可以覆盖包内同名的 skill。BubAgent(skill_dirs=...) 会用指定目录替代默认搜索位置。

系统提示词会列出可用 skills。$skill-name 在当前轮展开该 skill；,skill name=skill-name 则通过命令路径打印正文。

把 skills 放进 wheel

在 Python 代码旁放置 skills 命名空间包：

src/
├── bub_myplugin/
│   ├── __init__.py
│   └── plugin.py
└── skills/
    └── my-skill/
        ├── SKILL.md
        └── references/
            └── examples.md

使用 Hatch 时，把两个目录都加入 wheel：

[tool.hatch.build.targets.wheel]
packages = ["src/bub_myplugin", "src/skills"]

skills/ 保持为不含 __init__.py 的命名空间包，让多个已安装的包都能提供 skills。其他构建工具也应生成相同的安装目录结构。

Skills 可以随插件或应用发行包分发。Bub 通过安装后的 skills 命名空间包发现它们。

检查安装结果

把构建好的 wheel 安装到运行 Bub 的环境，再让应用加载 skill：

bub run ",skill name=my-skill"

如果返回 (no such skill)，检查目录名、frontmatter 和 wheel 内容。如果打印了意外的版本，检查项目或用户目录下是否有同名 skill。

要一起分发 CLI 和插件，参见打包 Bub 应用。