技能

Bub 将技能视为可发现的 SKILL.md 文档，带有经过验证的 frontmatter。

最小契约

每个技能目录必须包含一个 SKILL.md 文件：

my-skill/
`-- SKILL.md

src/bub/skills.py 中的验证规则：

• SKILL.md 必须以 YAML frontmatter 开头（--- ... ---）
• frontmatter 必须包含非空的 name 和 description
• 目录名必须与 frontmatter 中的 name 完全匹配
• name 必须匹配正则 ^[a-z0-9]+(?:-[a-z0-9]+)*$
• name 长度必须 <= 64
• description 长度必须 <= 1024
• 如果提供了 metadata，必须是 string -> string 的映射

Frontmatter 字段

当前强制校验的字段：

• 必需：name、description
• 可选（带类型检查）：metadata

允许其他额外字段，但核心不对其进行验证。

发现与覆盖

技能从以下三个根目录按优先级顺序发现：

1. 项目级：.agents/skills
2. 用户级：~/.agents/skills
3. 内置：src/skills

如果名称冲突，列表中靠前的根目录胜出。

遗留路径说明：.agent/skills 仍会被扫描以保持兼容，但 Bub 会发出弃用警告并优先使用 .agents/skills。

运行时访问

内置命令模式可以检查已发现的技能：

uv run bub run ",skill name=my-skill"

如果技能未找到，,skill name=<name> 会返回 (no such skill)。

编写指南

• 保持 SKILL.md 简洁且面向操作
• 保持 metadata 精简且确定性
• 使用小写 kebab-case 命名以保证兼容性

可选脚本约定

对于 scripts/*.py，推荐使用 PEP 723 配合 uv 的独立脚本约定：

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = []
# ///