skillport-distribution-system

SkillPort 配布システム

目的

再利用可能なエージェントスキルを一度だけパッケージ化し、共有ローカルスキルストレージを使って、Codex、Claude Code、OpenCode などのハーネスを含む複数のマシン、ユーザー、リポジトリ間でインストールおよび共有できるようにします。

このワークフローを使用する

新しいスキルパックのリポジトリを作成する場合：

1. ファイルをパッケージ化する前に、リポジトリの製品名、スラッグ、提供価値を決めます。
2. 新しいスキルパックを始める際は、SkillPort リポジトリから scripts/create-agent-skill-repo.sh を実行します。
3. 生成されたプレースホルダー、プラグインマニフェスト、README、サンプル、スキーマ、セットアップスクリプトを確認します。
4. 実際のスキルを追加または更新します。
5. GitHub リポジトリの略称を SkillPort のマニフェスト（通常は config/skill-repos.local.yaml）に追加します。
6. 次のコマンドでローカル検証します：

npx skills add /path/to/generated/repo --list

7. GitHub にプッシュします。
8. GitHub 上で次のコマンドを実行して検証します：

npx skills add https://github.com/OWNER/REPO --list

通常のマシン間同期には、次を使用します：

./scripts/skillport-sync.sh

これにより、選択したマニフェストに記載された各リポジトリに対して npx skills add <repo> --skill '*' -a codex -g -y を再実行し、その後 npx skills update -g -y を実行します。

個人用のリポジトリ一覧は、config/skill-repos.local.yaml などの無視対象ローカルファイルに保管するか、--repos-file で別のマニフェストを指定します。公開する SkillPort リポジトリには、中立的なサンプルマニフェストのみを含めてください。

通常のマシンセットアップには同期スクリプトを使用します。プッシュ前のライブ編集を反映させたい場合に限り、ローカルシンボリックリンクスクリプトを使用して、ローカルで開発してください。

GitHub テンプレートのルール

GitHub テンプレートリポジトリはリポジトリ全体をコピーします。サブディレクトリを直接テンプレート化することはできません。

通常の SkillPort ワークフローにはジェネレーターを使用してください。GitHub UI または gh repo create --template のフローが必要な場合に限り、独立した最小構成の GitHub テンプレートリポジトリを作成します。

ハーネスに依存しないインストールとグローバルルール

設定済みのベースラインには、npx skills add <repo> --skill '*' -a codex claude-code opencode -g -yを使用します。CLI の出力とnpx skills ls -g -a codex claude-code opencodeを確認してください。Codex と OpenCode は~/.agents/skillsを直接使用し、Claude のパスは OS ごとのこのツリーへのエイリアスです。ハーネスごとに編集可能なコンテンツのコピーを追加しないでください。

Windows のパスと/mnt/cを通じて、Windows と WSL で共有する正規のリポジトリチェックアウトを1つ維持します。生成されるインストール先は OS ごとに分けてもかまいません。各インストーラーが、無関係なスキルに影響を与えずに独自のパスを管理できます。ほかの物理デバイスでは、Git で同期する別個のチェックアウトを使用します。

グローバルガイダンスの生成は AgentDesk が担います。AgentDesk のglobal-guidance/を編集し、AgentDesk のscripts/regenerate-agents-md.pyを実行してください。SkillPort は更新時に AgentDesk のジェネレーターを呼び出すだけです。編集可能な別のジェネレーターやガイダンスのコピーを持たせないでください。また、編集可能なルールを複製せずに、Claude のインポートと OpenCode のグローバル JSON のinstructionsを設定します。最初の移行では、比較と明示的な置き換えが必要です。移行前に有効だったコンテンツはバックアップされます。保持と検証の手順については、docs/cross-device-maintenance.mdを参照してください。任意のハーネスが同じグローバルパスやインポート構文をサポートすると想定しないでください。

無人更新では、SKILLPORT_ROOTを設定し、macOS の LaunchAgent インストーラーまたはネイティブの Windows タスク スケジューラ インストーラーを、非公開のマシン設定とともに使用します。リポジトリレジストリとグローバルガイダンスのレイヤーには、どちらも AgentDesk のチェックアウトを使用してください。リポジトリの一覧、ガイダンスソース、マシンパス、シェル起動時の前提を重複させないでください。macOS ではログイン／読み込み時と、スリープ解除後にまとめて実行される15分ごとのタイミングで実行されます。Windows ではログオン時およびStartWhenAvailableを指定して15分ごとに実行されます。これにより、監査ポリシーに依存する不安定なロック解除イベントのサブスクリプションを避けられます。どちらも、レジストリで選択された正規のチェックアウトのみを更新し、プラットフォームに適したガイダンスを組み立て、明示的に指定されたリモートスキルのサブセットを再インストールします。これらの基本操作に GitHub CLI は任意であり、稼働中のプッシュ可視性の検証にのみ使用されます。メタデータがない場合や取得に失敗した場合、更新を妨げることなくプッシュをスキップします。任意のプッシュは引き続きレジストリの範囲に限定され、フェイルクローズで動作します。プライベートリポジトリには、プライベート可視性の検証と認証情報のスキャンが必要です。パブリックリポジトリにも、レビュー済み HEAD の完全一致承認と個人情報のスキャンが必要です。この自動化でファイルをステージングしたりコミットしたりすることはありません。

ワークフローの指示と、それを支える事実が一体となっている場合は、スキルディレクトリ内に参考資料も含め、インストール可能な1つのスキルとしてパッケージ化してください。危害と利益を検討して公開または非公開を選び、公開する資料はサニタイズし、リポジトリをまたぐ実行時依存関係や、第二の信頼できる情報源となるサイドカーを避けてください。