Skills

A slash command is a macro you fire. A skill is something the model reaches for on its own, when it judges a task needs it.

That difference decides how they are loaded. Only the name and description of each skill are in the system prompt; the body stays on disk until the model calls load_skill. You pay for the catalogue on every turn and for the instructions only when they are used — which is what makes it reasonable to have twenty skills installed and carry none of their contents around.

Writing one

A skill is a directory with a SKILL.md in it:

~/.config/tapioca/skills/
  release/
    SKILL.md
    checklist.md

---
description: Cut a release — version bump, tag, changelog, publish.
---

Bump the version in `internal/version` and `flake.nix` together; CI refuses a
tag whose versions disagree. Then …

The description is the only part the model sees until it loads the skill, so write it as the thing that decides whether this is relevant — not as a title. It is capped at 200 characters, which is roughly a sentence, because every description is paid for on every turn of every conversation whether or not the skill is ever used.

Files next to SKILL.md are listed to the model when the skill loads, so a checklist or a script can be part of the pack rather than pasted into it.

Where they live

Two places, the same two custom commands come from:

Location	Scope
~/.config/tapioca/skills/	yours, everywhere
.tapioca/skills/	the project's, committed with it

The project's win by name, so a repository can ship its own release skill over your personal one.

Using them

/skills lists what is loaded. /skills <name> loads one immediately, for when you know it applies and would rather not wait for the model to decide.

Limits, and why they are there

• 100 skills, 200-character descriptions, 64 KB per SKILL.md, 40 bundled files listed. A directory with a thousand packs in it would otherwise be a system prompt nobody asked for.
• Symlinks are followed only while they stay inside the skills directory.
• A broken pack is named and skipped, not fatal. Skills are hand-written and they arrive with cloned repositories, so one that does not parse is ordinary and should not take startup down with it.

A skill is instructions, and instructions are input

A skill in .tapioca/skills/ came with the repository. Its text reaches the model the same way AGENTS.md does, and the model cannot reliably tell instructions it was given from instructions it merely read. Nothing in a skill executes on its own — it has no command field, and loading one is a tool call that returns text — but what it says can ask the model to run something, and that request will look like any other.

The permission prompt is still where that is caught. See Untrusted Repositories.