Skills

A skill is an operating manual for agents: a SKILL.md (plus optional references/, agents/, scripts/) that tells any agent what something means, how the workflow runs, and what it must never do. The layout is the open Agent Skills format — released by Anthropic as an open standard and supported by Claude Code, Codex, Cursor, Gemini CLI, and dozens of other clients — so everything on this page works with whatever agent you already use. The format itself is documented in its own specification; this page is about how Busabase puts it to work. You will meet skills in two places:

• The official skills, installed next to your agent, which teach it to drive Busabase itself.
• Skills in your workspace, stored as Skill nodes, which teach any connected agent how to work with your data.

This page covers both, in that order.

The official skills

Three skills are published at github.com/busabase/skills:

busabase-skill-creator, busabase-package-creator, and busabase-app-package-creator are aliases of busabase-app-creator — four names, one skill. A directory can be a package, an Agent Skill, and an AirApp at the same time, and one skill builds all of them; splitting it by name would only make an agent guess which name matches the thing it has not built yet.

Install them

npx skills add busabase/skills --skill busabase busabase-app-creator

busabase-cli skill install

Skills in your workspace

The official skills teach an agent to drive Busabase; workspace skills teach it to drive your data. A workspace skill is a Skill node stored in the same folder as the Bases it explains — what the fields mean, how the workflow runs, what must never be touched — so the competence travels with the data, not with whichever agent happens to connect today.

• busabase-cli skills list enumerates the Skill nodes in your workspace.
• busabase-cli skills read-file --node-id <id> --file-path SKILL.md --output json reads one body.
• Dashboard → Agent Skills produces a prompt already targeted at the selected space.
• Edits to a skill body go through Change Requests: reviewed once, live for every consumer at the same moment.

Because every agent reads the same body, the outcome no longer depends on which agent — or how experienced a person — is driving.

How a skill body gets into a workspace

There are three ways, and which one you want depends on who else will use the skill.

        package-first                workspace-first
   write SKILL.md on disk       create the Skill node
   as part of a package         directly in the folder
            │                            │
            │  install                   │  export --template
            ▼                            ▼
   ┌──────────────────────────────────────────────┐
   │   the Skill node in the folder  (the body)   │
   └──────────┬─────────────────────────┬─────────┘
              │                         │
     agents in this space        pointer stubs in repos
     read it before acting       fetch it on demand

Install a template

A template carries the manual as its root SKILL.md; on install it becomes exactly a Skill node in the target folder, content carried verbatim.

Write it in the workspace

Create the Skill node directly and write the body there. The node is the original; busabase-cli export --template later lifts it back out as a package's root SKILL.md. Either way, file and node are the same bytes — only the direction of the copy differs.

Point at it from another repo

The cross-repo case: one skill, wanted in five repositories. Vendoring a copy per repo means five copies that drift. Instead, commit a pointer stub — a minimal local SKILL.md whose body is fetched from the Skill node at use time.

One command writes it for you:

busabase-cli skill link --node-id nodXXXXXXXX

link is the opposite of install. skill install writes a copy of a skill onto this machine. skill link writes a pointer: the body never lands on disk here at all — only the hosted skill's own name and description, plus the command to fetch the rest. The file it writes looks like this:

---
name: crm-visits
description: Log and review customer visits in the Acme CRM space. The full procedure is hosted in Busabase — fetch it first (command below).
---

The body of this skill lives in Busabase, in the same folder as the Bases it
writes to. Fetch it before doing anything:

    npx busabase-cli@latest skills read-file --node-id nodXXXXXXXX \
      --file-path SKILL.md --output json

| What | Where |
| --- | --- |
| Space | Acme Team `spcXXXXXXXX` |
| Skill node | `crm-visits` — `nodXXXXXXXX` |

Two things stay local, and skill link fills in both for you. The description is copied down from the hosted skill's own frontmatter: agents decide whether to invoke a skill from its listed description — the format's discovery stage loads nothing else at startup — so a remote-only trigger would never be seen, and a hand-written paraphrase would drift from the real one. The fetch command carries two flags that are not decoration: --output json, because the default text output collapses the body to a one-line preview (a 40 KB skill comes back as 426 bytes ending in …), and @latest, because npx will otherwise serve a cached older CLI that may not have the subcommand at all.

The directory is named after the hosted skill, not after anything you type — that name is how an agent resolves "read the crm-visits skill in this folder". An existing skill of the same name is never replaced without --force, since overwriting a real body with a pointer to a different one is a swap, not a refresh.

Three rules keep stubs honest:

• Fetch first, always. If the fetch fails, stop and say so — never improvise the procedure from the one-line description.
• A stub names concrete ids, so never publish it as a template.
• Readers need access to that space. Stubs are for a team sharing a workspace; external distribution is what templates are for.

Why ids written into a file must not be distributed

The rule above — never publish a stub as a template — is the specific case of something that applies to anything you hand out:

author ──publish──▶ template (no ids) ──install──▶ instance (ids exist) ──pin──▶ pointer stubs
                        ▲                                                          │
                        └───────────── never ship the ids back ◀──────────────────┘

A template materializes fresh resources in the installer's space; pinned ids name the author's. Publishing pinned ids means every install succeeds — then reads nothing, or someone else's data. busabase-cli check refuses a template package whose app pins resource ids for exactly this reason.

See also

• Agent Skills — the open SKILL.md standard all of this builds on
• Get started with agents — connecting the agent that will read all of this
• Template format — the root SKILL.md, references/, and the ownership stamp
• Node types — the Skill node's storage and review behavior
• Install & export — the package format both directions share