skillpack-harvest

skillpack-harvest — ホストのスキルを gbrain に取り込む編集ワークフロー

規約： ファイル配置のルールについては、_brain-filing-rules.md を参照してください。このスキルは、brain リポジトリのメモではなく、gbrain 自身のツリーに書き込みます。

このスキルは gbrain skillpack scaffold の逆です。scaffold はスキルを下流へ配布します（gbrain → ホスト）。harvest は実績のあるパターンを上流へ取り込み（ホスト → gbrain）、他のすべてのクライアントが scaffold で利用できるリファレンスにします。

条件

harvest が「適切に完了した」とみなされるのは、次の条件を満たしたときです。

1. ホストのスキルが成熟していること（本番環境で使用され、最近のルーティング評価ケースに合格していること）。
2. Phase 3 の編集による汎用化で、フォーク固有の参照（名前、実在のエンティティ、内部チャンネル）がすべて取り除かれていること。
3. gbrain skillpack harvest --dry-run でファイルセットをプレビューしていること。
4. 実際の gbrain skillpack harvest <slug> --from <host> が status: harvested で成功していること（プライバシー lint の検出がないこと）。
5. 新しい skills/<slug>/SKILL.md に対して bun test test/skills-conformance.test.ts が成功すること。
6. ユーザーが gbrain の差分を確認し、コミットを明示的に承認していること。

いずれかが完了していない場合、そのスキルはまだ harvest されていません。ファイルが gbrain の作業ツリーに置かれていても、取り込みは完了していません。

出力形式

このスキルは、gbrain の作業ツリーに次の 3 つの成果物を生成します。

1. skills/<harvested-slug>/SKILL.md（および routing-eval.jsonl などの同階層のファイル）
2. ミラー先のパスに配置された対応するソースファイル（例：src/commands/<slug>.ts）。ホストの SKILL.md が frontmatter の sources: でそれらを宣言している場合に生成されます。
3. 新しい slug を skills: に追加した openclaw.plugin.json の更新版（ソート済み）

ユーザーへのセッション出力は、1 行の成功概要と、書き込んだファイルの一覧です。JSON モード（--json）では、機械処理用に HarvestResult の完全な形式を返します。

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または notice ブロックについては、エージェントオペレータープロトコルに従ってください。このスキル固有の対応は次のとおりです。

• lint_failed：プライバシーリンターが実名または非公開の詳細を検出しました。Phase 3 に戻り、プレースホルダー（alice-example、acme-example、fund-a）に置き換えてください。
• harvest 後に gbrain skillpack check --strict が差分を報告した場合：バンドルを再生成して、もう一度実行してください。差分のある skillpack を出荷してはいけません。

アンチパターン

• ドライランを省略する。 必ず最初にプレビューしてください。ファイルは gbrain の作業ツリーに配置されます。git checkout ですぐにクリーンアップできますが、その必要がないようにしてください。
• リンターだけを信頼する。 デフォルトの正規表現セットは一般的なケースを検出しますが、すべての固有名詞を検出するわけではありません。主な防御策は Phase 3（編集工程）です。
• 正当な理由なく --no-lint で harvest する。 lint には理由があります。回避する場合は、その理由をコミットに記録してください。
• まだ変更中のスキルを harvest する。 ホスト版が安定するまで待ってください。そうしないと、harvest、再度 harvest、さらに再度 harvest することになり、メリットがないまま gbrain のバンドルに変更が重なります。
• コピーではなくファイルを移動する。 harvest はコピーです。ホストにはスキルを残してください。harvest 後にソースを rm -rf で削除しないでください。
• 複数のスキルを一括 harvest する。 サポートされていません。また、理由があります。スキルごとの編集レビューには相応の作業が必要です。

呼び出すタイミング

• ユーザーがホストのフォーク（使用している OpenClaw またはその他の非公開の下流フォーク）でスキルを開発し、他の gbrain クライアントでも使えるようにしたい場合
• スキルが本番環境で実績を上げ、汎用化の準備ができた場合
• ユーザーがスキルを上流へ「harvest」または「公開」するよう明示的に依頼した場合

次の場合は呼び出さないでください。

• スキルがまだローカルで変更中の場合。まず安定させてください。
• スキルに汎用化できない非公開コンテンツが含まれている場合
• ユーザーが単発のドラフトを共有したいだけの場合（代わりに gist を使用してください）

前提条件

このスキルを実行する前に、次の点を確認してください。

1. スキルが十分に成熟していること。 最近の routing-eval.jsonl のケースに合格しており、少なくとも数回は本番環境で使用されています。

2. スキルが汎用化できること。 頭の中で置き換えテストをしてください。フォーク固有の名前をすべて置き換えても、スキルとして意味が通じますか？

3. ユーザーが gbrain のチェックアウトを所有していること。 収集した内容は gbrain の作業ツリーに書き込まれます。ユーザーがレビューしてコミットします。ユーザーがコミットする予定のないチェックアウトには収集しないでください。

ワークフロー

フェーズ 1 — 計画

ユーザーに次の点を尋ねてください。

• 収集するスキルのスラッグは何にしますか？（スラッグはケバブケースで、gbrain バンドル内でグローバルに一意である必要があります。）
• ソースのホストリポジトリはどれですか？（スキルディレクトリではなく、リポジトリのルートパスを指定します。例：~/git/agent-fork。~/git/agent-fork/skills/foo ではありません。）
• 関連するソースファイルも含めますか？（ホストの SKILL.md のフロントマターにある sources: 配列を確認してください。）

フェーズ 2 — ドライランとプライバシーリントのプレビュー

CLI を --dry-run 付きで実行します。

gbrain skillpack harvest <slug> --from <host-repo-root> --dry-run

出力には、次の内容が表示されます。

• gbrain のツリーに取り込まれるファイル
• 関連するソースが含まれるかどうか
• （暗黙的に）スキルのフロントマターのトリガー。内容を読み、汎用化できているか確認してください。

ドライランを省略しないでください。 プライバシーリンターは実際の収集時にしか実行されませんが、ドライランのプレビューを使えば、ファイルが取り込まれる前に内容を確認できます。SKILL.md と関連ソースを抜き取り確認し、リンターが見落とす可能性のある内容（固有名詞、内部プロジェクト名など）がないか確認してください。

フェーズ 3 — 汎用化チェックリスト（編集作業）

実際に収集する前に、ホストの skills/<slug>/ ファイルを確認し、次のチェックリストを適用してください。該当する内容があれば、まずホストファイルを編集してから収集を実行してください。

1. フォーク固有の名前 → 汎用的な表現

   • <personal-fork-name> → your OpenClaw（または OpenClaw deployment）； ユーザーの非公開エージェントにつけられた愛称も同様に置き換えます
   • 個人のファーストネーム（garry、jane など）→ the user / you / 汎用プレースホルダー

2. 実在のエンティティ → プレースホルダー

   • 実在する人物、企業、取引、ファンド → プレースホルダーのスラッグ （alice-example、acme-example、fund-a など）
   • メールアドレス → 完全に削除するか、[email protected] を使用
   • 内部 Slack チャンネル → #some-channel に置き換えるか、削除
   • 特定のトラッカー ID／Linear チケット番号 → 削除

3. フォーク固有の規約 → 参照

   • <host-repo>/docs/... ファイルへの言及 → ドキュメントを gbrain に移すか、汎用的なプレースホルダーの説明に置き換える
   • <host-repo>/skills/<other-fork-only-skill> への言及 → そのスキルも 収集するか決めるか、汎用的なパターンへの参照に置き換える

4. triggers 配列を汎用化する

   • フロントマターの triggers: にあるすべての項目を確認してください。ユーザー名、フォーク名、内部ツールを参照する項目があってはいけません。
   • 「garry に承認してもらう」→「ユーザーに承認してもらう」

5. routing-eval.jsonl の例を匿名化する

   • skills/<slug>/routing-eval.jsonl を開きます。すべての intent フィールドに、triggers: と同じ匿名化を行います。

6. コードコメントとログ文字列

   • 関連ソースも収集する場合は、非公開情報が同様に漏れていないか確認してください。コメントは最もよく見落とされる箇所です。

フェーズ 4 — 実際のハーベスト

フェーズ 3 が完了したら、実際のハーベストを実行します。

gbrain skillpack harvest <slug> --from <host-repo-root>

デフォルトの動作：

• ファイルのコピー時にパスの範囲制限を確認し、シンボリックリンクを拒否します
• プライバシーリンターは ~/.gbrain/harvest-private-patterns.txt を対象に実行されます （組み込みのデフォルトも対象です — 正規のプライベートフォーク名、メールアドレス、 Slack チャンネルについては src/core/skillpack/harvest-lint.ts を参照してください）
• 一致があった場合 → ロールバック（ハーベストしたファイルを削除）し、ゼロ以外の終了コードで終了します
• openclaw.plugin.json を更新してスラッグを追加し、並べ替えます

結果：

• harvested — 成功。マニフェストが更新され、ファイルが gbrain のツリーに配置されました
• lint_failed — プライバシーリンターが問題を検出しました。フェーズ 3 に戻り、 ホストファイルから該当箇所を削除して再試行してください。
• slug_collision — gbrain にすでにそのスラッグのスキルがあります。別のスラッグを 使うか、本当に置き換える場合は --overwrite-local を渡してください。

フェーズ 5 — gbrain で確認

ハーベストが成功したら：

1. bun test test/skills-conformance.test.ts — 新しい SKILL.md がフロントマターの契約を満たしていることを確認します。
2. gbrain skillpack check --strict — バンドルと gbrain 自身のチェックアウト間に 差異がないことを確認します。
3. gbrain skillpack list — バンドルにスラッグが表示されることを確認します。
4. 差分を確認します：cd <gbrainRoot> && git diff -- skills/<slug>/
5. 追加内容を gbrain でコミットします（ホストリポジトリに残ったファイルは 絶対にコミットしないでください — ハーベストは移動ではなくコピーです）。

フェーズ 6 — 下流への告知（任意）

ほかの gbrain クライアントにも新しいスキルを取り込んでもらう場合：

• 次のリリースの「Skills added」に CHANGELOG.md へ記載します
• スキルがコアチーム以外の人から提供された場合は、PR でユーザー／コントリビューターにタグ付けします

バイパス：--no-lint

プライバシーリンターは安全網です。編集レビューが第一の防御策です。フェーズ 3 を 十分に実施しても誤検知でリンターが動作する場合は、--no-lint を使用します。

gbrain skillpack harvest <slug> --from <host-repo-root> --no-lint

コミットメッセージにバイパスしたことを記録してください。 将来のメンテナーが、 なぜリンターをバイパスしたのか確認できるようにします（例：「フォーク名は実際の 参照ではなく引用に記載されている — 手動で確認済み」）。

安易にリンターをバイパスしないでください。デフォルトでリンターを有効にしている のは、実名が編集レビューをすり抜けてしまうことが時折あるためです。

ハーベストで行わないこと

• ファイルを移動しません（コピーします）。ホスト側の skills/<slug>/ は そのまま残ります。
• 名前を自動で削除しません。編集レビューは人が行います。
• npm やリモートバンドルには公開しません。gbrain の作業ツリーに書き込み、 ユーザーが通常の gbrain リリースプロセスを通じてコミットし、リリースします。
• --all はサポートしません（複数スキルの一括ハーベストには対応していません）。 一度に 1 つのスキルを扱うことで、編集レビューを無理なく行えます。

このスキルが変更するファイル

• gbrain の skills/<slug>/ — ホスト側スキルディレクトリ内のすべてのファイル （コピー）
• 宣言されたペアソースに対応する gbrain のミラーパス （例：ホスト側の SKILL.md でフロントマターに宣言されている場合の src/commands/<slug>.ts）
• gbrain の openclaw.plugin.json — skills: 配列にスラッグを追加し、 アルファベット順に並べ替えます。id、configSchema、contracts などの OpenClaw ネイティブプラグインフィールドは削除しません