技能（Skill）

Busabase 官方技能——busabase、busabase-app-creator、busabase-template-creator——如何安装和使用，以及托管在工作区里的技能如何让每个 agent 行为一致。

技能是给 agent 看的操作手册：一份 SKILL.md（外加可选的 references/、agents/、scripts/），告诉任何一个 agent 某样东西是什么意思、工作流怎么走、什么事绝对不能做。这个文件布局就是开放的 Agent Skills 格式——由 Anthropic 以开放标准发布，Claude Code、Codex、Cursor、Gemini CLI 等数十个客户端都支持——所以本页的一切都适用于你手上已有的任何 agent。格式本身的细节见它的官方规范；本页讲的是 Busabase 怎么用它。你会在两个地方遇到技能：

官方技能，安装在你的 agent 旁边，教它驾驭 Busabase 本身。
工作区里的技能，以 Skill 节点存放，教任何连上来的 agent 怎么处理你的数据。

这一页两者都讲，按这个顺序。

官方技能有哪些

github.com/busabase/skills 发布了三个技能：

技能	干什么	什么时候用
`busabase`	日常驾驶手册：通过 Change Request 连接、读写任何工作区，用 `busabase-cli`、REST API 或 MCP	只要你的 agent 需要和 Busabase 工作区打交道
`busabase-app-creator`	构建完整的工作区应用、编写可安装的模板、或维护已有的 AirApp——同一套 review-first 工作流	你在创建或演进应用、模板、AirApp
`busabase-template-creator`	在 app-creator 之上叠加目录发布门槛：封面图、截图覆盖、品牌卫生、示例记录、干净的 `busabase-cli check`	模板已经正确，你要让它可发布

busabase-skill-creator、busabase-package-creator、busabase-app-package-creator 是 busabase-app-creator 的别名——四个名字，一个技能。一个目录可以同时是包、Agent Skill 和 AirApp，一个技能全都能构建；按名字拆开只会让 agent 去猜哪个名字对应它还没构建出来的那样东西。

怎么安装

用 skills 安装器

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

要发布到模板目录时，再加上 busabase-template-creator。

或者用 CLI，无需网络

busabase-cli skill install

它把 busabase 技能放进你 agent 的技能目录（默认 ./.agents/skills，否则 ./.claude/skills）——适合 CI 环境或从没跑过 npx skills add 的机器。它写的是一份拷贝；如果一个技能应该在某个工作区里保持唯一正本、被多个仓库读取，请改用 skill link（见从另一个仓库指过来）。Codex、Claude Code 和 DeepSeek Harness 插件已经捆绑了这些技能，装了插件就不用再做任何事。

验证

让你的 agent"读 busabase 技能并检查连接"，或者跑 busabase-cli doctor。技能从 ~/.busabase/.env 读取 base URL、API key 和目标 Space。

工作区里的技能

官方技能教 agent 驾驭 Busabase；工作区技能教它驾驭你的数据。工作区技能就是一个 Skill 节点，和它所解释的 Base 放在同一个 Folder 里——字段是什么意思、工作流怎么走、什么绝对不能碰——于是能力跟着数据走，而不是跟着今天恰好连上来的那个 agent 走。

busabase-cli skills list 枚举工作区里的 Skill 节点。
busabase-cli skills read-file --node-id <id> --file-path SKILL.md --output json 读取一份正文。
Dashboard → Agent 技能（英文界面为 Agent Skills）生成一段已经指向当前 Space 的提示词。
技能正文的修改走 Change Request：审一次，所有消费方同一时刻生效。

因为每个 agent 读的都是同一份正文，结果不再取决于用的是哪家 agent、开车的人水平如何。

技能正文怎么进入工作区

有三种方式，用哪一种取决于还有谁会用这个技能。

        package-first                workspace-first
   在磁盘上把 SKILL.md          直接在 Folder 里
   写成包的一部分               创建 Skill 节点
            │                            │
            │  install                   │  export --template
            ▼                            ▼
   ┌──────────────────────────────────────────────┐
   │      Folder 里的 Skill 节点（正文本体）        │
   └──────────┬─────────────────────────┬─────────┘
              │                         │
     这个 Space 里的 agent        各仓库里的指针 stub
     行动前先读它                 用时现取

装一个模板

模板把手册作为根部的 SKILL.md 携带；安装时它原样变成目标 Folder 里的一个 Skill 节点，内容逐字节搬运。

在工作区里直接写

直接创建 Skill 节点、把正文写在里面。节点是原件；日后 busabase-cli export --template 把它反向提出来，成为包根部的 SKILL.md。无论哪种方式，文件和节点都是同一份字节——不同的只是拷贝的方向。

从另一个仓库指过来

跨仓库的场景：一个技能，五个仓库都想要。每个仓库 vendor 一份就是五份会漂移的拷贝。改成提交一个指针 stub——极简的本地 SKILL.md，正文在使用时从 Skill 节点现取。

一条命令就能生成：

busabase-cli skill link --node-id nodXXXXXXXX

link 和 install 正好相反。 skill install 写的是技能的一份拷贝；skill link 写的是一个指针——正文根本不会落到本地磁盘，只留下远端技能自己的 name 和 description，加上取回正文的命令。它写出来的文件长这样：

---
name: crm-visits
description: 在 Acme CRM 空间里记录和回顾客户拜访。完整流程托管在 Busabase——先取回它（命令见下）。
---

这个技能的正文放在 Busabase 里，和它要写的 Base 在同一个 Folder。
做任何事之前先取回正文：

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

| 什么 | 在哪 |
| --- | --- |
| Space | Acme Team `spcXXXXXXXX` |
| Skill 节点 | `crm-visits` — `nodXXXXXXXX` |

有两样东西留在本地，skill link 会替你填好。description 是从远端技能自己的 frontmatter 抄下来的：agent 靠技能列表里的 description 决定要不要调用（该格式的发现阶段在启动时只加载这一项），触发条件只在远端就永远没人看见，而手写的转述则会和真正的那份渐行渐远。取回命令里的两个 flag 也不是装饰：--output json，因为默认的 text 输出会把正文压成一行预览（一份 40 KB 的技能回来只剩 426 字节，结尾是 …）；@latest，因为 npx 否则会跑缓存里的旧版 CLI，那个版本可能根本没有这个子命令。

目录名取自远端技能，而不是你输入的任何东西——agent 就是靠这个名字解析「读这个 folder 里的 crm-visits 技能」。同名技能不加 --force 永远不会被替换：把一份真正的正文覆盖成指向另一个技能的指针，是掉包，不是刷新。

三条规则让 stub 保持诚实：

永远先取回。 取回失败就停下来说明——绝不能凭一行 description 即兴发挥出流程。
stub 写死了具体 id，所以绝不能发布成模板。
读者需要对那个 Space 有访问权。 stub 服务于共享工作区的团队；对外分发是模板的职责。

为什么写死 id 的东西不能分发

上面那条「stub 绝不能发布成模板」，是一条对任何要发给别人的东西都成立的规则的具体情形：

绑定	工件里是否写死 id	属于
`pinned`	是——写入 Space 和节点 id	已部署的实例：工作区里编写的应用、维护中的安装、指针 stub
`runtime`	否——安装时按安装者解析	分发中的模板：id 在有人安装之前根本不存在

作者 ──发布──▶ 模板（无 id）──安装──▶ 实例（id 诞生）──pin──▶ 指针 stub
                  ▲                                              │
                  └────────── 绝不把 id 发回去 ◀─────────────────┘

模板在安装者的 Space 里物化全新的资源；pin 住的 id 指向的是作者自己的。把 pin 过的 id 发布出去，每一次安装都会成功——然后读到空，或者读到别人的数据。busabase-cli check 正是因此拒绝任何 pin 了资源 id 的模板包。

我该用哪一种？

别人要装进他们自己的 Space → 发布成模板，保持 runtime 绑定。
只服务你自己运营的一个工作区 → 在那个工作区里直接写，随便 pin。
已经部署好了，团队其他仓库也要用 → 每个仓库一个指针 stub。