Package skills for the app

A skill gives the Bub app a procedure it can load for a task. Keep project-specific skills in the workspace, or include them in a Python package so other users can install them.

For your first local skill, follow Add a project skill. This page covers discovery and packaging. Skill discovery is part of the application; a plain core.Agent uses the instructions you explicitly give it.

Write a skill Bub can load

Each skill directory contains a SKILL.md with YAML frontmatter:

---
name: my-skill
description: Describe the task this skill helps the agent complete.
---

Write the procedure here.

Bub checks these fields when discovering skills:

Field	Requirement
name	Matches the directory name; lowercase words separated by hyphens; at most 64 characters
description	Nonempty string, at most 1,024 characters
metadata	Optional map with string keys and string values

Add scripts/, references/, or assets/ alongside SKILL.md when the procedure needs supporting files. In the body, $SKILL_DIR expands to the skill’s directory and $PYTHON to the interpreter running Bub. Application configuration can be inserted with ${config.path.to.value}.

Know which skill is selected

By default, the application searches these roots in order. The first matching name wins:

1. <workspace>/.agents/skills/
2. ~/.agents/skills/
3. Installed skills namespace packages, including Bub’s bundled skills

A project skill can therefore replace a packaged skill with the same name. BubAgent(skill_dirs=...) replaces the default roots with the directories you supply.

The system prompt lists available skills. A $skill-name hint expands that skill for the current turn; ,skill name=skill-name prints its body through the command path.

Include skills in a wheel

Place a skills namespace package alongside your Python code:

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

With Hatch, include both directories in the wheel:

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

Keep skills/ as a namespace package without an __init__.py so multiple installed packages can contribute to it. Other build backends must produce the same installed layout.

Skills can ship with a plugin or an application distribution. Bub discovers them through the installed skills namespace package.

Check the installed package

Install the built wheel into the environment running Bub, then ask it to load the skill:

bub run ",skill name=my-skill"

If it returns (no such skill), check the directory name, frontmatter, and wheel contents. If it prints an unexpected version, look for a project or user skill with the same name.

To distribute a CLI and plugins alongside these skills, see Package a Bub application.