Customize

Add your own skills

Teach Bwat repeatable workflows as SKILL.md packages. Install one from a folder, have Bwat author it from your description, or write it by hand.

On this page

What a skill is

A skill is a small folder with a SKILL.md file containing instructions for one repeatable kind of task. When your request matches a skill's description, Bwat loads it and follows it before answering. Examples include your deploy checklist, PR-review ritual, or convention for writing release notes. Skills can carry companion files (scripts, templates, references) next to the SKILL.md.

Bwat ships with a library of official skills. Your own live alongside them in two places:

Scope	Location	Applies to
User	`~/.bwat/custom-skills/<slug>/SKILL.md`	Every project on this machine
Project	`.bwat/skills/<slug>/SKILL.md`	This workspace only

Three ways to add one

1. Install from a folder

Found a skill on disk, perhaps cloned from a repo, shared by a teammate, or downloaded from a skill collection? Point Bwat at it:

in chat

You: Load the skill at ~/dev/pr-review-skill into my user skills.

Bwat: ManageSkillsTool install
      Source: ~/dev/pr-review-skill
      Skill: pr-review · Scope: user
      [Approve]  [Deny]

For a git repo, Bwat clones it with its normal shell tool first, then installs from the folder. The install step itself never touches the network.

2. Have Bwat write one

Describe the workflow and Bwat authors the SKILL.md (and any scripts) itself, shows you the card, and writes it after you approve:

in chat

You: Create a skill for our staging deploy: run scripts/deploy-staging.sh,
     then smoke-test https://staging.example.com, then post in #deploys.

Bwat: ManageSkillsTool create
      Skill: staging-deploy · Scope: project
      Description: Deploys the staging environment and smoke-tests it
      [Approve]  [Deny]

3. Write the file by hand

Skills are just folders: drop one in place and Bwat picks it up on the next message. The format is the Anthropic agent-skills convention: a flat frontmatter block, then the instructions in markdown.

~/.bwat/custom-skills/staging-deploy/SKILL.md

---
name: staging-deploy
description: Deploys the staging environment and smoke-tests it. Use when the user asks to deploy or update staging.
argument-hint: "[service]"
---

1. Run ${SKILL_DIR}/scripts/deploy.sh $ARGUMENTS
2. Smoke-test https://staging.example.com/health until it returns 200.
3. Post a summary in #deploys.

Frontmatter field	Required	Meaning
`name`	no	Display name; falls back to the folder name (which is the slug)
`description`	yes (in practice)	How Bwat decides when to use the skill: be specific and trigger-rich
`argument-hint`	no	Shown in `/skills` and the slash-command popup, e.g. `[service]`

Using a skill

Skills are invoked in two ways. Automatically, Bwat chooses one when your request matches its description. Explicitly, you run /skill-name with optional arguments (/staging-deploy api). Run /skills to list everything available; your own skills are marked [custom] in the CLI. Inside the body, ${SKILL_DIR} resolves to the skill's folder (so scripts/ paths work) and $ARGUMENTS receives whatever was passed after the slash command.

New and edited skills are live from the next message. Discovery rescans the folders every run, and the body is re-read every time the skill is invoked.

Removing and precedence

Ask (“remove the staging-deploy skill”) or just delete the folder. Project skills win over user skills with the same slug, and the official library wins over both, so a custom skill can never shadow a Bwat-shipped one.

A skill changes the instructions Bwat follows when it is used, so only install skills you trust. Every install and create shows you an approval card with the name, source, and content before anything is written.

Pair skills with your own MCP servers: a skill that drives your Playwright or Supabase server is where this gets powerful.