Skills

Skills are reusable instruction packs that Bestie loads into the chat system prompt. Use them for repeatable behavior, workflows, guardrails, or project-specific habits that should be available across conversations.

Think of a skill as a small, named prompt module. If a behavior needs to be reused more than once, do not keep pasting it into chat like a tired goblin. Put it in a skill.

Bestie supports two skill sources:

• local skills you create under ~/.bestie/skills/<skill-name>/SKILL.md
• remote library skills from the official GitHub registry used by the Web UI skill library

File layout

Each skill lives in its own folder under the Bestie runtime app directory:

.bestie/skills/<skill-name>/SKILL.md

Example:

.bestie/
  skills/
    code-reviewer/
      SKILL.md
    release-helper/
      SKILL.md

The folder name is the stable skill identifier. Keep it lowercase and descriptive, for example code-reviewer, docs-polisher, or incident-debugger.

SKILL.md format

A skill is a Markdown file with YAML frontmatter followed by instructions.

---
name: code-reviewer
description: Review code changes for bugs, regressions, missing tests, and risky behavior.
---

# Code Reviewer

Use this skill when the user asks for a code review, PR review, or risk assessment.

## Behavior

- Prioritize bugs, security issues, behavioral regressions, and missing tests.
- Put findings first, ordered by severity.
- Include file and line references when available.
- Keep summaries short unless the user asks for detail.

Frontmatter fields

Field	Required	Purpose
name	Yes	Human-readable skill name. Usually matches the folder name.
description	Yes	Short trigger description that tells Bestie when the skill is relevant.

Keep description specific. Helps with stuff is not a description; it is a cry for help wearing a trench coat.

Loading behavior

Bestie loads skills from the runtime app directory at startup or chat initialization, depending on the command path.

Important behavior:

• Only .bestie/skills/<skill-name>/SKILL.md files are loaded.
• Empty SKILL.md files are ignored.
• Skill content is trimmed before injection.
• Skills load in directory-name order for deterministic prompts.
• The loader stops when the combined skills prompt reaches its byte budget.

Because skills share a prompt budget, keep them focused. A skill should teach one durable behavior, not become a landfill for every thought you have ever had.

When to create a skill

Create a skill when you want Bestie to consistently follow a workflow, such as:

• code review style
• release checklist
• documentation writing rules
• incident debugging steps
• project-specific conventions
• repeatable research or planning process

Do not create a skill for one-off context. If the instruction only matters for the current task, say it in chat instead.

Related commands

List installed skills:

bestie skills
bestie skills list

Both commands show the skills Bestie can discover from the runtime skills directory.

Remote skill library

The local Web UI skill library uses the official remote registry by default:

https://raw.githubusercontent.com/sirquy/bestie-skills/master/registry.json

Bestie verifies the registry with the sidecar checksum at:

https://raw.githubusercontent.com/sirquy/bestie-skills/master/registry.sha256

Registry metadata is cached under:

~/.bestie/data/skill-remote-registry-cache.json

Remote installs are intentionally gated:

• registry URLs must use https://
• the registry must validate and verify by checksum or detached signature
• installPolicy must be ask
• the owner must explicitly confirm installs, updates, rollback, enable/disable, and uninstall actions in the UI/API flow

When Bestie installs a library skill, it writes the skill content plus non-secret source metadata:

~/.bestie/skills/<skill-name>/SKILL.md
~/.bestie/skills/<skill-name>/bestie-skill.json

The manifest records source, version, checksum, declared permissions, and whether the skill is enabled. Disabled skills remain visible in the Web UI but are not injected into future prompts.

Library workflows

Use the Web UI skill library to:

• preview a remote skill before installing it
• compare diffs before updating an installed skill
• install or update a skill after explicit confirmation
• roll back to a previous installed copy when available
• enable or disable a skill without deleting it
• uninstall a skill, which archives removed files under .bestie/skills/.uninstalled/

The editor is for installed skills. Remote library previews are read-only until you install the skill.

Best practices

• Give each skill a narrow purpose.
• Write a clear trigger in description.
• Keep instructions actionable and short.
• Prefer checklists over long essays.
• Never store secrets, API keys, tokens, or private config in skills.
• Treat remote skill text as untrusted instructions until you review it.
• Avoid conflicting skills that give opposite instructions.
• Put project-specific rules in a project skill, not in every chat prompt.

Troubleshooting

If a skill does not appear:

• Check that the file is named exactly SKILL.md.
• Check that it lives under .bestie/skills/<skill-name>/.
• Check that the file is not empty.
• Run bestie skills list to verify discovery.
• Shorten large skills if later skills are missing because the byte budget was reached.
• In the Web UI, check whether the skill is disabled in bestie-skill.json.
• For remote library issues, refresh or clear the registry cache and verify the registry checksum status.