テンプレート

テンプレートセンター、CLI、あるいはエージェント自身のシェルから、完成したアプリ — テーブル、インターフェース、そしてエージェントがデータに触れる前に読むマニュアル — をまるごとインストールする。

テンプレートとは、space にそのままインストールできる完成したアプリです。テーブル、インターフェース、サンプル行、そして「ただのテーブルの集まり」と決定的に違う部分 — 作者がエージェントのために書いたマニュアル — が含まれます。1 つインストールすれば、スキーマを説明しなくてもエージェントはすぐ動けます。

仕組みとしては、テンプレートはパッケージであり、同時に Agent Skill でもあります。同じディレクトリのルートに SKILL.md があり、その隣に busabase.json と content/ が並びます。

busa-email/
├── SKILL.md          ← エージェントが読むマニュアル
├── references/       ← 一緒に運ばれる
├── busabase.json     ← マニフェスト（`template` オブジェクト付き）
└── content/          ← 普通の busabase-package@1 ツリー

content/ 配下は普通のパッケージとバイト単位で同一です。ここから 3 つの帰結が出ます。

テンプレートのディレクトリはすでに正当なパッケージです。busabase-cli install は以前からインストールできました — マニュアルを配置せず、所有スタンプを押さず、サンプル行をマージしないだけです。
どんなパッケージも、ルートに SKILL.md と template オブジェクトを足せばテンプレートになります。移行も、フォーマット v2 も不要です。
テンプレート要件を満たさないパッケージが拒否されることはありません。テンプレートが存在しなかった頃と全く同じく、普通のパッケージとしてインストールされます。

読む順序：このページはテンプレートをインストールして使う話です。テンプレートフォーマットは中身と設計理由、テンプレートを公開するは自分で作ったフォルダをテンプレートにする手順です。

入口は 2 つ、リソースは 1 組

space への入口は 2 つあり、どちらを使うかはその人が今どこにいるかで決まります。

	出発点	インストールするもの
テンプレートセンター	Busabase のダッシュボード	サーバーがリポジトリを取得してパッケージを適用する
エージェントのシェル	Claude Code、Codex など skill 対応エージェント	その skill 自身の `scripts/setup.mjs` が `busabase-sdk` 経由で API を叩く

どちらも同じリソースを作り、作成した全ノードに同じ所有スタンプ — ノードの metadata に入る appId、安定した resourceKey、schemaVersion — を書き込みます。このスタンプだけが、2 つの入口が互いの成果を認識する根拠です。ギャラリーからインストールしたあとターミナルで同じ skill を実行すると、2 つ目のコピーを作ろうとせず、自分の Folder と自分のテーブルを見つけます（スタンプが食い違えば、skill は自分のものと証明できないデータには触れず SETUP_CONFLICT で止まります — テンプレートフォーマットを参照）。

テンプレートセンターを見る

ダッシュボードのサイドバー、アクティビティや GitHub からインストール… の並びに テンプレート があり、いま開いている space のテンプレートギャラリーを開きます。

ギャラリーはカードのグリッドです。各カードにはスクリーンショット（作者が用意していなければプレースホルダー）、名前、カテゴリバッジ、説明、そして手で書いたのではなくパッケージ自体から読み取った 1 行の計算 — 「3 tables · 1 app · 7 sample rows」 — が並びます。検索ボックスは名前・説明・カテゴリ・タグを対象に絞り込みます。右上のリンクはカタログの元になったリポジトリで、誰のテンプレートを見ているのかが常に分かります。

カードを開くと詳細ビューになり、人が実際に判断する順に並んでいます。

スクリーンショット — 見た目。
「インストール後、エージェントに何を頼めるか」 — 作者が用意したプロンプト。*「そもそも何を聞けばいいのか」*への最短で正直な答えであり、テンプレートがマニュアルをテーブルと一緒にインストールするからこそ成立します。
「インストールすると何が作られるか」 — テーブル、アプリ、ドキュメント、サンプル行、ファイル、そしてエージェント用マニュアルの有無。
ソースを読む、ライセンス、作者。

閲覧は誰でもできますが、インストールは space の owner/admin の操作です。 テンプレートは AirApp と Skill — この space のエージェントが実行するコード — を含み得るため、サーバーはプレビューとインストールの両方でロールを検証します。メンバーにはカードと「誰がインストールできるか」の説明が表示され、押しても無反応なボタンは出ません。

カタログはブラウザではなくサーバーが取得し、1 時間キャッシュされます。取得できないときは理由が赤で表示されます — 「Could not reach the template catalog at …」。空のギャラリーと壊れたギャラリーは利用者から見分けがつかず、行動できるのは一方だけだからです。

ギャラリーはデモワークスペースでも動きます。カタログが並べるのは公開リポジトリで、あなたのデータとは無関係です。インストールはできません。

インストールする

詳細ページの Install は、サイドバーが開くのと同じ GitHub からインストール… ダイアログを、テンプレートのリポジトリ URL と対象フォルダ名で埋めた状態で開きます。これは意図的な再利用です。閲覧とインストールが「これは何のパッケージか、誰がインストールできるか、何が作られるか」で食い違ってはならず、確認するプレビューが文字どおり同一なら食い違いようがありません。

したがって手順はインストールとエクスポートと同じ 3 ステップ（URL → プレビュー → 確認）です。変わるのは、サーバーがテンプレートだと認識したあとの動作です。

テンプレートのインストールで変わること

	普通のパッケージ	テンプレート
作者の `SKILL.md`	リポジトリに残る	フォルダ内の Skill ノードとして、`references/`・`agents/`・`scripts/` ごとインストールされる
ノードの metadata	なし	ルート Folder と作成した全リソースに所有スタンプ
Base の slug	作者が書いたまま	対象フォルダのプレフィックス付き — `settings` が `busa-email-settings` になる
サンプル行	レビュー待ちとして提案	インストール時にマージされ、開いたときに空でない
AirApp のコード、Skill、ドライブ	レビュー待ち	レビュー待ち — 変わらず

slug のプレフィックスは、汎用的な名前が衝突するために存在します。settings や contacts を持つテンプレートを 2 つ入れると、そのままでは名前を奪い合ってしまいます。プレフィックスの付いた Base を指す relation フィールドは追随して書き換えられ、すでにプレフィックスの付いた slug が二重に付くことはありません。

サンプル行のマージは、*「入れればすぐ使える」*を願望ではなく事実にするためのものです。そして同時に、フォーマットが 1 テーブルあたり 50 行という上限を設けている理由でもあります。マージされた行は webhook や自動化を発火させ、コミット履歴に入り、エージェントには実データとして読まれます。テンプレートはデモの種を蒔くもので、データセットを配るものではありません。

レコードに relation の値を持つパッケージは通常 --auto-merge を必要とします。relation は指し先の行の id を保持し、その id は行がマージされて初めて存在するからです。テンプレートは自分のサンプル行を自分でマージするため、この要件は発火しません。

構造は即座に、動くものはレビューのあとで

インストールとエクスポートのルールはそのまま生きており、ここが最も驚かれる部分です。

即座に作成： フォルダ、Base、そのフィールドとビュー。未マージの Base には id がなく、id がなければビューもフィールドも行も置けません。
即座にマージ（テンプレートのみ）： サンプル行。
レビュー待ち： AirApp のソース、マニュアルを載せた Skill ノード、ドライブ、ドキュメント。

そのため新規インストールはたいてい 「3 change requests are waiting for you」 と受信箱へのリンクで終わります。マージするまでテーブルはあってもアプリは起動できず、エージェントはマニュアルを読めません — Skill ノードがまだ存在しないからです。

コマンドラインからインストールする

npx busabase-cli install https://github.com/busabase/templates/tree/main/busa-email

インストールのページの内容がそのまま当てはまります。テンプレートで効くフラグは 2 つです。

フラグ	効果
`--skill <name>`	URL が 1 つのパッケージではなく複数のパッケージを持つリポジトリを指している場合。CLI は見つけたものを一覧し（テンプレートを先頭に、ラベル付きで。テンプレートを名乗って失敗したものは理由付きで）、そこから選びます
`--no-sample-records`	サンプル行をマージせずレビューに回す

--skill は CLI 専用です。ダッシュボードのダイアログは URL 自体がパッケージであることを前提とするため、/tree/<ref>/<subdir> まで含む完全な URL を貼ってください（テンプレートセンターのカードが渡すのはまさにこれです）。

まず --dry-run から。URL の git ref がバージョンの固定です。タグを指定すればブランチが先に進んだあとも、そのタグの内容が永久にインストールされます。

インストールしたあと

1. 待っているものをレビューする。 受信箱で change request を読みます。特に AirApp のソースとマニュアルは、実際に動くものとエージェントが従うものなので重要です。マージして初めてアプリは現実になります。

2. エージェントを向ける。 Skill ノードがマージされれば、MCP で接続したエージェントは自力で見つけられます。

呼び出し	返るもの
`busabase_guide`（topic は `apps`）	このワークスペースにどのアプリが入っているか、各 slug
`busabase_guide`（topic は `skill:<slug>`）	そのアプリの `SKILL.md` 全文と `references/`

セッション指示は、アプリのデータを操作する前に必ず apps を確認するようエージェントに求めます。アプリが既に文書化しているスキーマを推測することこそ、行が違うテーブルに入る原因だからです。一覧を指示文ではなくツール呼び出しにしているのは、40 個のアプリが入ったワークスペースが毎セッション無関係な 39 個分のマニュアルを負担しないためです。

3. 作者のプロンプトを使う。 詳細ページのものが出発点です — このアプリが何のためにあるかを知っている人が書いています。

マニュアルは内容であって権限ではありません。skill:<slug> を読んだエージェントはテーブルの意味とアプリの用途を知りますが、行動はあくまで API トークンの権限の範囲内で、変更は Change Request として提案されます。

テンプレートがまだできないこと

計画を立てる前に知っておく価値があります。

アップグレード経路がありません。 install --upgrade はまだありません。ルート Folder のスタンプはどのリポジトリ・ref・バージョン由来かを記録しており、それが将来のアップグレード提案を可能にする土台ですが、今のところ新版を入れるには別のフォルダにインストールすることになります。
シークレットは宣言であって作成ではありません。 テンプレートの secrets と vaultNamespace は、アプリが期待する Vault のキーを教えるだけです。パッケージフォーマットにシークレットの値を入れる場所はなく、増やすべきでもありません — 自分で入れる必要があり、インストールは今のところ促しもしません。
インストールしてもアプリは開きません。 主となる AirApp は検証時に解決されますが、インストールは change request のサマリーで終わり、起動したアプリでは終わりません。