スキル（Skill）

Busabase 公式スキル — busabase、busabase-app-creator、busabase-template-creator — のインストールと使い方、そしてワークスペースにホストされたスキルがどのエージェントにも同じ振る舞いをさせる仕組み。

スキルはエージェントのための操作マニュアルです。SKILL.md（および任意の references/、agents/、scripts/）が、どのエージェントに対しても、対象の意味・ワークフローの進め方・絶対にしてはならないことを伝えます。このファイル構成はオープンな Agent Skills フォーマットです — Anthropic がオープン標準として公開し、Claude Code、Codex、Cursor、Gemini CLI をはじめ数十のクライアントが対応しています — つまりこのページの内容は、いま使っているどのエージェントでもそのまま使えます。フォーマット自体の詳細は公式の仕様へ。このページは Busabase がそれをどう使うかを説明します。スキルに出会う場所は 2 つあります。

公式スキル — エージェントの隣にインストールし、Busabase 自体の操り方を教えるもの。
ワークスペース内のスキル — Skill ノードとして保存され、接続してくるどのエージェントにもあなたのデータの扱い方を教えるもの。

このページでは、この順に両方を説明します。

公式スキルの一覧

github.com/busabase/skills では 3 つのスキルが公開されています。

スキル	何をするか	使いどころ
`busabase`	日常の運転マニュアル：Change Request を通じて任意のワークスペースへ接続・読み書きする。`busabase-cli`、REST API、MCP を使用	エージェントが Busabase ワークスペースを扱うすべての場面
`busabase-app-creator`	完全なワークスペースアプリの構築、インストール可能なテンプレートの執筆、既存 AirApp の保守 — 1 つのレビューファーストなワークフロー	アプリ・テンプレート・AirApp を作成または進化させるとき
`busabase-template-creator`	app-creator の上に載るカタログ公開基準：カバー画像、スクリーンショットの網羅、ブランド衛生、サンプルレコード、クリーンな `busabase-cli check`	テンプレートが正しい状態から公開できる状態へ引き上げるとき

busabase-skill-creator、busabase-package-creator、busabase-app-package-creator は busabase-app-creator のエイリアスです — 名前は 4 つ、スキルは 1 つ。1 つのディレクトリはパッケージであり、Agent Skill であり、AirApp でもあり得ます。1 つのスキルがそのすべてを構築するので、名前で分割するとエージェントはまだ作っていないものに合う名前を推測させられるだけです。

インストール

skills インストーラで

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

テンプレートカタログへ公開するときは busabase-template-creator を追加します。

あるいは CLI で、ネットワーク不要

busabase-cli skill install

busabase スキルをエージェントのスキルディレクトリ（デフォルト ./.agents/skills、無ければ ./.claude/skills）に配置します。CI 環境や npx skills add を一度も実行していないマシンで便利です。これが書くのはコピーです。1 つのワークスペースに正本を置いたまま複数のリポジトリから読ませたいスキルには、代わりに skill link を使ってください（別のリポジトリから参照する）。Codex、Claude Code、DeepSeek Harness のプラグインはこれらのスキルを同梱しているので、プラグインを入れていれば追加作業はありません。

確認

エージェントに「busabase スキルを読んで接続を確認して」と頼むか、busabase-cli doctor を実行します。スキルは base URL・API キー・対象スペースを ~/.busabase/.env から読み取ります。

ワークスペース内のスキル

公式スキルはエージェントに Busabase の操り方を教えます。ワークスペーススキルはあなたのデータの扱い方を教えます。ワークスペーススキルとは、説明対象の Base と同じフォルダに置かれた Skill ノードです — フィールドの意味、ワークフローの進め方、絶対に触れてはならないもの。能力はデータと一緒に移動し、たまたま今日接続してきたエージェントには付いて回りません。

busabase-cli skills list はワークスペース内の Skill ノードを列挙します。
busabase-cli skills read-file --node-id <id> --file-path SKILL.md --output json は本文を 1 つ読み取ります。
Dashboard → Agent Skills は選択中のスペースをすでに指し示したプロンプトを生成します。
本文の変更は Change Request を通ります。一度レビューされれば、すべての利用側に同じ瞬間に反映されます。

どのエージェントも同じ本文を読むため、結果はどのエージェント（や操作者の熟練度）にも依存しなくなります。

スキルの本文がワークスペースに入る方法

3 つの方法があり、どれを選ぶかはほかに誰がそのスキルを使うかで決まります。

        package-first                workspace-first
   パッケージの一部として       フォルダ内に直接
   SKILL.md をディスクに書く    Skill ノードを作る
            │                            │
            │  install                   │  export --template
            ▼                            ▼
   ┌──────────────────────────────────────────────┐
   │     フォルダ内の Skill ノード（本文の実体）     │
   └──────────┬─────────────────────────┬─────────┘
              │                         │
     このスペースのエージェントは   各リポジトリのポインタスタブは
     行動前にこれを読む             使うときに取得する

テンプレートをインストールする

テンプレートはマニュアルをルートの SKILL.md として携え、インストール時にそのままターゲットフォルダ内の Skill ノードになります。内容は逐語的に運ばれます。

ワークスペースで直接書く

Skill ノードを直接作り、本文をそこに書きます。ノードが原本です。後で busabase-cli export --template がそれをパッケージのルート SKILL.md として持ち出します。どちらの方法でも、ファイルとノードは同一のバイト列 — 違うのはコピーの方向だけです。

別のリポジトリから参照する

リポジトリ横断のケース：1 つのスキルを 5 つのリポジトリが欲しがっている。リポジトリごとにコピーを持てば 5 つのコピーが漂流します。代わりにポインタスタブをコミットします — 最小限のローカル SKILL.md で、本文は使用時に Skill ノードから取得します。

コマンド 1 つで生成できます。

busabase-cli skill link --node-id nodXXXXXXXX

link は install の逆です。 skill install はスキルのコピーをこのマシンに書き込みます。skill link が書くのはポインタです — 本文はここのディスクには一切降りてこず、ホストされたスキル自身の name と description、そして本文を取得するコマンドだけが残ります。書き出されるファイルはこうなります。

---
name: crm-visits
description: Acme CRM スペースで顧客訪問を記録・レビューする。完全な手順は Busabase にホストされている — まず取得すること（コマンドは下記）。
---

このスキルの本文は Busabase 内、書き込み先の Base と同じフォルダにあります。
何かをする前にまず本文を取得してください：

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

| 何 | どこ |
| --- | --- |
| スペース | Acme Team `spcXXXXXXXX` |
| Skill ノード | `crm-visits` — `nodXXXXXXXX` |

ローカルに残るものは 2 つで、どちらも skill link が埋めてくれます。description はホストされたスキル自身の frontmatter から写し取られます — エージェントは一覧の description を見て呼び出すかどうかを決める（このフォーマットの発見ステージは起動時にそれ以外を読み込まない）ため、リモートにしかないトリガーは誰にも見えず、手書きの言い換えは本物から離れていきます。取得コマンドの 2 つのフラグも飾りではありません。--output json は、デフォルトのテキスト出力が本文を 1 行のプレビューに切り詰めるため（40 KB のスキルが … で終わる 426 バイトになります）。@latest は、npx がキャッシュされた古い CLI を使い、そのバージョンにはサブコマンド自体が無いことがあるためです。

ディレクトリ名はホストされたスキルから取られ、入力した何かからではありません — エージェントが「このフォルダの crm-visits スキルを読む」を解決するのがその名前だからです。同名のスキルは --force なしに置き換えられません。本物の本文を別スキルへのポインタで上書きするのは、更新ではなくすり替えです。

スタブを健全に保つルールは 3 つです。

必ず先に取得する。 取得に失敗したら停止して報告する — 1 行の description から手順を即興で作らない。
スタブは具体的な id を書き込んでいるので、テンプレートとして公開しない。
読み手にはそのスペースへのアクセス権が必要。 スタブはワークスペースを共有するチームのためのもの。外部への配布はテンプレートの役目です。

id を書き込んだものを配布してはいけない理由

上記の「スタブをテンプレートとして公開しない」は、人に配るもの全般に当てはまるルールの一例です。

バインディング	アーティファクトに id を書き込むか	属するもの
`pinned`	はい — スペースとノードの id を記載	デプロイ済みインスタンス：ワークスペースで書いたアプリ、保守中のインストール、ポインタスタブ
`runtime`	いいえ — インストール時にインストーラごとに解決	配布中のテンプレート：id は誰かがインストールするまで存在しない

作者 ──公開──▶ テンプレート（id なし）──インストール──▶ インスタンス（id 誕生）──pin──▶ ポインタスタブ
                    ▲                                                                │
                    └───────────── id を送り返すことは決してない ◀──────────────────┘

テンプレートはインストーラのスペースに新しいリソースを実体化します。pin された id が指すのは作者自身のリソースです。pin 済みの id を公開すると、どのインストールも成功してしまい — その後、何も読めないか、他人のデータを読みます。busabase-cli check がリソース id を pin したテンプレートパッケージを拒否するのは、まさにこのためです。

どれを選べばいい？

他の人が自分のスペースにインストールする → テンプレートとして公開し、runtime バインディングを維持。
自分が運用する 1 つのワークスペースのためだけ → そのワークスペースで直接書き、自由に pin してよい。
すでにデプロイ済みで、チームの他のリポジトリでも使う → リポジトリごとにポインタスタブを 1 つ。