publish-and-sync-skills

スキルの公開と同期

1 回のリリーストレインを実行します。

リポジトリのソース → 検証 → GitHub でのマージ → グローバルインストール → 証跡。

JoelFrancisco/skills を信頼できる唯一の情報源として扱います。グローバルなエージェントディレクトリは、生成されたインストール先として扱います。

リリースの進め方を選ぶ

エントリーポイントを 1 つ選びます。

• **追加またはインポート：**すべての手順を実行します。
• **更新：**リポジトリの準備から始め、既存のスキルを編集してから、登録から検証までを実行します。
• **同期のみ：**対象のスキルがすでに main にマージされていることを確認してから、グローバルインストールを開始します。

公開と同期を含む完全なリリースの依頼には、マージの承認が含まれます。PR の依頼では、ドラフトの公開後に停止します。

1. リポジトリを準備する

origin が JoelFrancisco/skills を指すチェックアウトを特定します。構造やリリースの動作を変更する前に、リポジトリの指示、docs/creating-skills.md、承認済みの ADR を読みます。

クリーンな main を origin/main と同期してから、agent/<skill-name> を作成します。無関係な作業は、ステージングする前に分離するか、対象範囲を確認します。

現在の origin/main をベースにした専用ブランチでチェックアウトされており、既存の変更すべての担当者が明確になったら、この手順は完了です。

2. スキルを追加または更新する

リポジトリの規約に従って、実際に使用するカテゴリを選びます。フォルダー名、フロントマターの name、kebab-case のスキル名を同一にします。

新しいスキルには、現在のハーネスのスキル作成用スキャフォールドを使用します。ハーネスが手動作成のみを提供する場合は、次を作成します。

skills/<category>/<skill-name>/
├── SKILL.md
└── agents/openai.yaml

公開されているスキルをインポートする場合は、適応する前にライセンス、由来、スクリプト、ネットワーク動作、認証情報の使用、破壊的な操作を確認します。インポートした素材に必要な帰属表示を保持します。

スキルの内容を説明し、実際に存在する各分岐のトリガーを 1 つずつ示す、モデル向けの説明を記述します。本文は命令形で、自己完結させ、プレースホルダーを含めないでください。詳細情報や条件付きの情報は、明示的なコンテキストへの参照を付けて、同じ階層のファイルに配置します。

スキルの目的が明確に 1 つで、プレースホルダーがすべて解消され、UI メタデータが有効であり、手順ごとに確認可能な完了基準がある状態になったら、この手順は完了です。

3. リリースを登録してバージョンを更新する

キュレーション済みのマニフェストを再生成します。

node scripts/sync-skills.mjs

.claude-plugin/plugin.json と .claude-plugin/marketplace.json の両方でリリースバージョンを更新します。値は一致させてください。通常、新しい公開スキルにはマイナーリリース、互換性を保つ修正にはパッチリリースが適切です。

新しいスキルのパスが plugin.json に正確に 1 回含まれ、マニフェストに実際に使用するカテゴリのスキルだけが含まれ、両方のマニフェストに意図した同じバージョンが記載されたら、この手順は完了です。

4. 公開前に検証する

該当するチェックをすべて実行します。

node scripts/sync-skills.mjs --check
jq empty .claude-plugin/plugin.json .claude-plugin/marketplace.json
git diff --check
npx --yes skills@latest add . --list --full-depth

利用可能であれば、現在のハーネスのスキルバリデーターを実行します。バンドルされたスクリプトはすべて、代表的な入力で実行します。複雑なスキルは、そのスキルと現実的なタスクだけを受け取る新しいエージェントでフォワードテストします。

マニフェストの検出結果にスキルが表示され、構造チェックに合格し、実行可能なリソースが正常に動作し、フォワードテストの失敗が修正済み、または明示的に報告済みであれば、この手順は完了です。

5. 公開してマージする

差分全体を確認し、リリース対象のファイルだけをステージングします。専用ブランチで簡潔なコミットを作成し、追跡設定付きでプッシュして、変更内容、理由、影響、検証について説明する本文を含むドラフト PR を作成します。

依頼に完全なリリースが含まれる場合：

1. PR のマージ先、想定されるヘッド SHA、マージ可能性、レビュー、チェックを確認します。
2. PR をレビュー可能な状態にして、リポジトリで承認されている方法でマージします。
3. ローカルのチェックアウトを main に切り替え、--ff-only でプルします。

まず利用可能な GitHub 統合を使い、対応していない変更操作には認証済みの gh CLI を代替手段として使います。

PR のみのリリースでは、意図した差分と検証の証跡がドラフト PR に含まれたら、この手順は完了です。完全なリリースでは、GitHub が PR のマージを報告し、ローカルの main にそのマージが反映され、ワークツリーがクリーンになったら完了です。

6. マージしたスキルをグローバルにインストールする

npx --yes skills@latest --help を使って、Vercel Skills CLI の現在の構文を確認します。このシェルヘルパーを定義してから、正確にマージしたスキル名を指定して sync_public_skill を呼び出します。

sync_public_skill() {
  local released_skill="$1"
  npx --yes skills@latest add JoelFrancisco/skills \
    --global \
    --agent codex claude-code hermes-agent opencode pi \
    --skill "$released_skill" \
    --yes \
    --full-depth
}

このコマンドでは、CLI のデフォルトのシンボリックリンクによるインストール方式を使用します。正規のハーネス識別子は codex、claude-code、hermes-agent、opencode、pi です。

CLI で、要求したスキルが5つすべてのハーネスにインストールされたと報告されたら、この手順は完了です。

7. ローカル同期を検証する

グローバルインストールを JSON 形式で一覧表示し、リリースしたスキルを選択します。

npx --yes skills@latest list --global --json

次の項目を検証します。

• スコープがグローバルであること。
• ソースが JoelFrancisco/skills であること。
• Codex、Claude Code、Hermes Agent、OpenCode、Pi が含まれていること。
• CLI がシンボリックリンクを使用する場合、エージェント固有のリンクが正規のインストール先を参照していること。
• インストールされた SKILL.md の内容が、マージ済みリポジトリのバージョンと一致すること。

GitHub でのマージ、ローカルの main、マニフェストのバージョン、グローバルソース、5つのハーネス、インストール済みのコンテンツがすべて一致したら、リリーストレインは完了です。

リリースを報告する

結果を先頭に記載します。スキル名とパス、リリースバージョン、コミット、PR とマージ、検証内容、インストール元、対象ハーネス、および未検証の項目があればその内容を含めます。

報告が自己完結しており、合格・不合格・未検証の証拠が区別されていれば、完了です。