Creating Custom Skills

Bonsai installs abilities from its built-in catalog. You can also create custom skills — your own skills that live alongside catalog-provided ones and are tracked by Bonsai.

How It Works

Create a file in agent/Skills/ (e.g., agent/Skills/my-custom-skill.md)
Add YAML frontmatter with at least a description field
Run bonsai update — it detects untracked files and offers to track them
Once tracked, custom items appear in CLAUDE.md nav tables and .bonsai.yaml

Frontmatter Format

Every custom skill needs YAML frontmatter at the top, delimited by ---:

---
description: What this skill does — shown in CLAUDE.md nav tables
display_name: My Custom Skill
---

# Content starts here
...

Field	Required	Notes
`description`	Yes	Shown in CLAUDE.md nav tables
`display_name`	No	Human-readable name. If omitted, derived from filename (`my-skill` becomes “My Skill”)

File Naming

Use kebab-case for filenames: my-custom-skill.md, not MyCustomSkill.md
The filename (minus extension) becomes the item’s machine name
Use .md extension

What `bonsai update` Does

When you run bonsai update:

Scans each agent’s workspace for files not yet tracked by Bonsai
Validates frontmatter — shows warnings for files missing required fields
Prompts you to select which files to track (multi-select, all pre-selected)
Tracks selected files in .bonsai.yaml (config) and .bonsai-lock.yaml (lock)
Re-renders catalog items from the latest embedded templates
Refreshes CLAUDE.md nav tables (includes both catalog and custom items)

Catalog vs Custom

Aspect	Catalog Items	Custom Items
Source	Built into the Bonsai binary	Created by you in your workspace
Metadata	Separate `meta.yaml` file	YAML frontmatter in the file itself
Re-renderable	Yes — templates re-rendered on update	No — your file is yours, never overwritten
Tracked in config	Item name in skills list	Item name in list + metadata in `custom_items`
Lock source	`catalog:skills/name`	`custom:skills/name`