Add a project skill

A skill gives Bub instructions for a particular task. In this example, you will ask it to inspect a repository before changing code.

Use the workspace from Run Bub for the first time. A skill contains a SKILL.md file and can include scripts or reference material alongside it.

Write the instructions

Create a directory for the skill:

mkdir -p .agents/skills/repo-map

Create .agents/skills/repo-map/SKILL.md:

---
name: repo-map
description: Read the local repository layout before changing code.
---

1. Run `rg --files` to see the repository layout.
2. Read the files that explain the requested change.
3. Describe the affected modules before editing code.

The name must match the directory name. Use lowercase words separated by hyphens. The description helps the model decide when to use the skill.

Check that Bub can load it

bub run ",skill name=repo-map"

The command prints the skill’s instructions without calling a model. If it returns (no such skill), check the path and the YAML frontmatter.

Use it in a conversation

With your model configured, run:

bub run 'Use the $repo-map skill, then list the top-level modules you found.'

$repo-map includes the skill’s instructions in this turn’s system prompt. The model then follows them using the tools available in the application. Install rg in the execution environment for this example.

You can keep this skill in the project or package it for other users. The packaging guide also explains discovery order and support files.