スキル
スキルは、AI に「この仕事はこうやる」を教える小さな包みです。手順・型・見本・参照の資料を 1 つのフォルダーにまとめ、AI は要る時だけ読みます。
良いスキルを知っている人は多くありません。BeesBuild は、プロジェクトのリポジトリと設計図を読み、要るスキルを手元・Xroid・公開の場から探します。5 段の安全性の確認と効き目の試験を通した物だけを勧め、1 回押すだけで各ハーネスに入れ、版の固定（lock）と見張りで守ります。合うスキルが無ければ、作って試します。
スキルの管制の 8 つの機能
| 機能 | すること |
|---|---|
| 台帳 | 手元・Xroid・公開・社内の棚の 4 つの元を、1 つの台帳にまとめる |
| 安全性の確認 | 入れる前と更新の時に、5 段で確かめる |
| 探す | 目的を日本語で書いて探す |
| 勧める | リポジトリ・設計図・役から、要るスキルを出す |
| 入れる | 1 つの元から、各ハーネスの置き場へ書き出す |
| lock と更新 | 版を固定し、更新は確かめ直してから入れる |
| 効き目の評価 | スキルがある時と無い時を比べる |
| 止める・引退 | 悪いスキルを、全部のプロジェクトでまとめて止める |
流れは「探す → 確かめる → 勧める → 入れる → 守る」です。守る段で更新や PR の指摘が出たら、確かめる段に戻ります。
台帳
台帳は、4 つの元からスキルを集めます。
| 元 | 中身 |
|---|---|
| 手元 | プロジェクトの .claude/skills/・.agents/skills/・.github/skills/、個人の置き場、プラグイン、管理の設定 |
| Xroid | Xroid のスキル。Geniam の MCP から一覧を取り、入れる |
| 公開 | Anthropic の公開のスキル集と公式のマーケットプレイス、各ハーネスの公開のスキル、MCP Registry |
| 社内の棚 | BeesBuild が確認と試験を通した物だけ。週に 1 回集め直す |
1 つのスキルごとに、目的・持ち主・出どころ（リポジトリ・ref・tree SHA か、スキルの id と版）・版・信頼の段・安全の札・効き目・使っているハイブを持ちます。
Claude Code のスキルには版の欄がありません。そこで、版と来歴は BeesBuild の台帳で持ちます。社内のスキルは 1 つのプラグインにまとめて版を付けます。スレッドが直したら、差と来歴を残し、使っているスレッドに知らせます。
信頼の段
| 段 | 中身 |
|---|---|
| T0 | 自作・社内 |
| T1 | 公式 |
| T2 | Xroid |
| T3 | 確認を通した公開の物 |
| T4 | 出どころの分からない物 |
ハーネスごとの置き場
| ハーネス | プロジェクトの置き場 | 個人の置き場 |
|---|---|---|
| Claude Code | .claude/skills/ | ~/.claude/skills/ |
| Codex | .agents/skills/（親のフォルダーも読む） | ~/.agents/skills/ |
| GitHub Copilot | .github/skills/・.claude/skills/・.agents/skills/ | ~/.copilot/skills/・~/.agents/skills/ |
| Antigravity | .agents/skills/ | Gemini の設定の中 |
置き場は、調べた時点の物です。ハーネスの版で変わることがあるので、できること表と同じく週に 1 回確かめ直します（ハーネスの設計）。
安全性の確認（5 段）
| 段 | すること | 見る物 |
|---|---|---|
| ① 出どころ | 元のリポジトリ・作者・commit と tree SHA・署名・ライセンス・前の版との差を見る | 名前を似せた偽物、持ち主の急な変更、大きな差、ライセンスが無い |
| ② 静的な点検 | 手元で 14 の項目を流す。中身を外に送らない | 下の表 |
| ③ AI の読み取り | 書いた AI と別のモデルが、全部のファイルを信用しないデータとして読む | 説明と中身のずれ、データの流れ、人に隠す指示、ほかの設定を変える指示 |
| ④ サンドボックスでの試行 | 鍵の無い仮想マシン・Docker・WSL の中で、偽の MCP と一緒に動かす。外への通信は止めるか記録する | 触ったファイル・出ようとした通信・使った道具を、宣言と比べる |
| ⑤ 人の承認 | 確認のカードに、要点・危ない所・許す事を 1 枚で出す | 書いた人と承認する人を分ける。AI の承認は数えない |
静的な点検で見る物です。
| 見る物 | 止める例 |
|---|---|
| 仕様と説明文 | 決まった形になっていない・説明が中身と合わない |
| 動く front matter | hooks・広すぎる allowed-tools |
| 読み込む時に動く命令 | スキルを読んだだけで命令が動く書き方 |
| 秘密と設定のファイル | 鍵らしき文字・設定を書き換えるファイル |
| スクリプト | 外への通信・読めなくした（難読化した）コード |
| 外の URL | 許可リストに無い送り先 |
| 別の物を入れさせる文 | 「先にこれを入れて」 |
| 安全を無視させる指示 | 「確認を飛ばして」 |
| MCP の組み合わせ | 「読む」と「外へ送る」がそろっている |
| 隠し文字と大きさ | 見えない文字・大きすぎるファイル |
結果の札は、通った・注意つき・止めた・確認中・期限切れ の 5 つです。更新の時・月に 1 回・点検の決まりが上がった時に、確かめ直します。外の検査の道具は、手元で動く部分だけを既定で使います。中身を外へ送る検査は、持ち主が許した時だけです。
Claude Code のプラグインの形のスキルは、公式の作りの検査（claude plugin validate）と、分けた環境での試し（claude plugin eval）も通します。
ハーネスの側の守り
ハーネスの側でも、危ない機能を既定で止めます。
| ハーネス | 既定で止める物 |
|---|---|
| Claude Code | スキルの中の命令の実行（disableSkillShellExecution）。許可の決まりは管理の設定だけにする（allowManagedPermissionRulesOnly）。プラグイン以外からの書き換えを止める（strictPluginOnlyCustomization） |
| Codex | 頼まれていないのにスキルを呼ぶ動き（allow_implicit_invocation）。スキルごとの設定（skills.config）で切る |
リポジトリの中にあるスキルは、そのフォルダーでハーネスを開く前に点検に通します。
入れてよい範囲
| スキル | 入れ方 |
|---|---|
| T0〜T2 | 5 段が通れば、自動で入れる |
| 公開の物（T3・T4） | 5 段・試行・人の承認を通す |
| スクリプトか hooks を持つ物 | 既定では入れない。入れる時は確認のカード |
探す
目的を日本語で書くと、4 つの元をまとめて探します。
- ハーネス・元・安全の札・ライセンス・更新日で絞れます。
- 合う度合い・安全・効き目・新しさで並べ、なぜ合うかを 1 行で出します。
- 同じ中身（digest か tree SHA が同じ物）は 1 つにまとめます。
- 名前を似せた物には印を付けます。
勧める
BeesBuild は、次の物を読んでスキルを勧めます。
- リポジトリ（言葉・依存・CI・試験の道具）
- 設計図
- ブロックとスレッドの役
- ハーネスの設計
合わせ方は、Claude Code のプラグインの勧めと同じ 5 つの信号です。作業のフォルダー・読んだファイル・依存の宣言・動かした命令・通信の相手を見ます。
出す一覧は「必ず用意」「あると良い」「参照」の 3 つで、理由と重なりを付けます。スキルは多すぎると、AI が選び間違えます。役ごとに束にして、要る物だけを渡します。合うスキルが無い仕事には「新しく作る」を出し、スキルを作るスキル（skill-creator）で作って試します。
用意するスキル
BeesBuild で作るどの開発にも、次のスキルを用意します。
| スキル | 中身 |
|---|---|
| 開発ルールのスキル | そのプロジェクトの書き方と決まり。BeesBuild が自動で作る（下の節） |
| 書く前に探す | 新しく書く前に、再利用の地図と既存のリポジトリを探す |
| 引き継ぎの札 | 引き継ぎの文の決まった形 |
| スキルの安全性の確認 | 5 段の確認の手順 |
| スキルを探す | 台帳から目的で探す |
| 仕上げ・決める部屋 | 仕上げの手順と、決めることを 1 ページにまとめる手順（人の番と決める部屋） |
| スキルを作る | skill-creator |
| レビュー | コードのレビューと守りのレビュー。レビューの決まりは REVIEW.md |
条件つきで足すスキルもあります。画面の試験・MCP を作る・Claude API・文書の形式（Word・PDF・PowerPoint・Excel）・画面のデザイン・読みやすい日本語・図・Xroid のコースのスキルなどです。
参照スキルは、知識を持つスキルです。本文は目次と「いつ読むか」だけにし、中身は references/ に置きます。
入れる
既定の書き出し先は、.claude/skills/ と .agents/skills/ の 2 か所です。1 つの元から両方に書き出し、手では直しません。
GitHub Copilot が、両方にある同じ名前のスキルをどう扱うかは、試しの週に確かめます。確認中
lock と更新
プロジェクトに .beesbuild/skills-lock.json を置き、コミットします。1 行に次の物を持ちます。
| 欄 | 中身 |
|---|---|
| 名前・id・版 | どのスキルの、どの版か |
| digest | 中身から作った値。同じ中身なら同じ値になる |
| 置き場とハーネス | どこに書き出したか |
| 出どころ | 元のリポジトリと tree SHA |
| 信頼の段 | T0〜T4 |
| 確認と効き目 | 通った確認と、効き目の試験の id |
| 固定 | 版を固定しているか |
Xroid のスキルは、Xroid の lock のファイルにも同じ物を書きます。
- 知らせる：元が変わったら知らせ、差を見せます。
- 確かめ直す：安全性の確認と効き目の試験を流し直します。
- 承認する：人が承認します。
- PR にする：lock を変える PR を出します。
- 戻せるようにする：前の版は残し、1 回で戻せます。
効き目の評価
| 測る物 | やり方 |
|---|---|
| 差 | スキルがある時と無い時に、同じ頼みを 3 回ずつ流して比べる（claude plugin eval。採点は道具を使ったか・決まった文字が出たか・AI の判定） |
| 呼ばれ方 | 呼ぶべき頼みと、呼ぶべきでない頼みで、正しく呼ばれるかを測る。外れたら説明文を直す（skill-creator） |
| 共存 | ほかのスキルとぶつからないか |
| 違い | モデルとハーネスごとの差 |
| 使われ方 | どれだけ使われ、どれだけ費用がかかったか |
使われ方の報告は、安全性の確認ではありません。試験は利用枠を使うので、見込みと週の上限を台帳に出します。
止める・引退
状態は、候補 → 試行 → 使える → 非推奨 → 取り消し と進みます。緊急の時は「止めた」にします。
悪いと分かったスキルは、全部のプロジェクトと全部のハーネスで、まとめて止めます（確認のカードと止める 3 段）。取り消した版は、二度と入れません。
開発ルールの輪
開発ルールは、そのプロジェクトの書き方と決まりを、AI が守れるスキルにした物です。6 つの段の輪で固めて、育てます。
- 集める：README・AGENTS.md・CLAUDE.md・決定の記録、lint と型と CI の設定、名前とフォルダーの形、コメントの言葉と印、commit と PR の題、PR の行の指摘を読みます。設定のファイルは正として扱い、値は写さずに場所を書きます。
- 分ける：決まりを 1 行ずつにし、id・文・種類・強さ（必ず・推奨・参考）・範囲（パス）・確かめ方（機械・AI・人）・出どころ（ファイルと行・PR・件数と守られている割合）・状態・ぶつかりを付けます。
- 決める：設定から読める物と、95% 以上が守っている物は自動で入れます。ぶつかる物・新しい決まり・守りの決まりだけ、人が決める部屋で決めます。古い書き方は一度に直さず、触ったファイルだけ合わせます。
- 書く：プロジェクトごとに 1 つの開発ルールのスキルにします。各ハーネスの形へ書き出し、手では直しません。
- 守らせる：機械・AI・人の 3 段で守らせます。
- 育てる：同じ種類の指摘が 3 回（2 つ以上の PR で）出たら、決まりの候補にします。守られている割合が 95% より低い決まりは、見直しの候補にします。
AGENTS.md も CLAUDE.md も無いリポジトリでは、決まりが PR の行の指摘に埋もれていることがよくあります。BeesBuild は指摘を訳して数え、多い指摘（名前・使わないコード・書式・「何のため」・再利用など）から、決まりの候補を出します。
開発ルールのスキルの中身
| ファイル | 中身 |
|---|---|
SKILL.md | いつ使うか・手順・守ること |
references/ | 決まりの詳しい説明と、良い例・悪い例 |
rules.json | 機械が読む決まりの一覧 |
scripts/check.mjs | 決まった答えを出す点検（CI で動く） |
CHANGELOG.md | 版ごとの変更 |
書き出し先と 3 段の守り方は、指示書を一つの元から作るにあります。レビューで付けた学びの印も、決まりの候補になります（レビュー）。
直し方
決まりの直しは、小さな束で出します。
- どの版への直しかを書きます。
- AI の操作は 8 つまでにします。
- 全部入れるか、何も入れないかのどちらかにします。
- 理由を残し、却下した案も覚えておきます。
版を上げる時は、確認のカード・lock の更新・使っているスレッドへの知らせ・効き目の試験のやり直しをそろえます。
データの形
| 型 | 中身 |
|---|---|
HbSkill | スキル（版・来歴・安全・状態） |
HbSkillSource | 台帳の元（手元・Xroid・公開・社内の棚） |
HbSkillCheck | 安全性の確認の結果（5 段・札・使った道具の版） |
HbSkillEval | 効き目（差・呼ばれ方・共存・モデルの違い） |
HbSkillLock | lock の 1 行 |
HbSkillBundle | 役ごとの束 |
HbDevRule | 開発ルールの 1 行 |
HbRuleSet | 開発ルールのスキルの版 |
HbRuleProposal | 決まりの候補 |