Skills

Bub’s skills system follows Agent Skills: a skill is a discoverable directory centered on SKILL.md, with optional scripts/, references/, assets/, and other supporting files. The notes below focus on how Bub loads those skills and the authoring patterns we recommend.

Minimal Contract

Each skill directory must contain a SKILL.md file:

my-skill/
`-- SKILL.md

Common optional directories from the Agent Skills format:

• scripts/ for executable helpers
• references/ for load-on-demand documentation
• assets/ for templates and static resources

Bub’s current loader expects:

• SKILL.md must start with YAML frontmatter (--- ... ---)
• frontmatter must include non-empty name and description
• directory name must exactly match frontmatter name
• name must match regex ^[a-z0-9]+(?:-[a-z0-9]+)*$
• name length must be <= 64
• description length must be <= 1024
• if provided, metadata must be a map of string -> string

Frontmatter Fields

Fields Bub currently reads:

• required: name, description
• optional with type check: metadata

Other extra keys are allowed.

Discovery And Override

Skills are discovered from three roots in this precedence order:

1. project: .agents/skills
2. user: ~/.agents/skills
3. builtin: src/skills

If names collide, earlier roots in this list win.

This discovery model is Bub’s runtime behavior on top of the standard Agent Skills format.

Legacy path note: .agent/skills is still scanned for compatibility, but Bub emits a deprecation warning and prefers .agents/skills.

Runtime Access

Builtin command mode can inspect discovered skills:

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

If a skill is not found, ,skill name=<name> returns (no such skill).

Authoring Guidance

• keep SKILL.md concise and action-oriented
• keep metadata small and deterministic
• use lowercase kebab-case names for compatibility
• move detailed material into references/ or scripts instead of overloading SKILL.md

Optional Script Convention

For scripts/*.py, a practical standalone convention is PEP 723 with uv:

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