skill-publish

スキルの公開

適切なバージョン管理、変更履歴の管理、Git ワークフローを用いて、Claude Code プラグインと単独のエージェントスキルを公開します。

公開タイプの判定

開始する前に、プロジェクトの構成に基づいて公開タイプを特定します。

判定基準	タイプ
.claude-plugin/plugin.json および／または .codex-plugin/plugin.json が存在する	ホスト型プラグイン
プラグインマニフェストのない単独の SKILL.md	単独のエージェントスキル

ホスト型プラグインは GitHub へのプッシュによって公開します。複数のホストに対応するリポジトリでは、実際のすべてのマニフェストと、共有するマーケットプレイスのメタデータを同期させる必要があります。Codex はプラグインの内容をバージョンごとにキャッシュするため、ソースコミットが更新されても、古いバージョンのままでは古いスキルが残ることがあります。

単独のエージェントスキルは agentskills.io の仕様に準拠し、SKILL.md を含むディレクトリとして配布します。

ホスト型プラグインのワークフロー

1. 現在の状態を確認する

# Read and validate every host manifest
python3 scripts/check-plugin-manifests.py

# Check git is clean and up to date
git fetch origin && git status

# Review commits since last version bump
git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~10)..HEAD

2. ドキュメントを整合させる

CHANGELOG.md は必須です。前回のリリース以降に発生した、ユーザーに見える変更または運用上の変更をすべて Unreleased の下に要約します。公開されている項目、インストール手順、実行時の動作、または告知している機能に変更がある場合は、README.md を更新します。利用可能な場合は、リポジトリのドキュメントチェックを実行します。

python3 scripts/check-docs.py

前回のマニフェストのバージョン更新コミットと現在の HEAD を比較し、古いバージョンのままコミットされた変更が漏れないようにします。

3. 実際のすべてのマニフェストのバージョンを更新する

リポジトリに同期用のバージョン更新コマンドがある場合は、それを使用します。bopen-tools の場合：

python3 scripts/check-plugin-manifests.py --bump-patch

それ以外の場合は、すべてのホストのマニフェストをまとめて編集します。ユーザーが明示的に、より大きな変更を依頼し、その妥当性を説明している場合を除き、パッチバージョンを更新します。

0.1.6 → 0.1.7
1.0.23 → 1.0.24

4. CHANGELOG.md を確定する

確認済みの Unreleased の記載を、日付付きのリリース項目に移動します。

## [X.X.X] - YYYY-MM-DD

### Added
- New features

### Changed
- Changes to existing functionality

### Fixed
- Bug fixes

次の変更に備えて、空の Unreleased 見出しを残します。リリースの見出しがすべてのマニフェストと完全に一致していることを確認します。

5. プラグインの構成を検証する

公開する前に、プラグインの形式が正しいことを確認します。

• .claude-plugin/plugin.json に必須の name フィールドがある
• コンポーネントディレクトリ（commands/、agents/、skills/、hooks/）に有効なファイルが含まれている
• スキルに有効な YAML フロントマター（name と description）を含む SKILL.md がある
• エージェントとコマンドに YAML フロントマター付きの .md ファイルがある
• 参照されているファイルとスクリプトが存在する
• すべてのホストのマニフェストとマーケットプレイスのバージョンが同期されている
• CHANGELOG.md にリリースバージョンが記載されている
• README の一覧が、作成されたスキル、エージェント、コマンド、フックと一致している
• 生成されたホストアダプターが最新である

bopen-tools の場合は、次を実行します。

python3 scripts/check-plugin-manifests.py
python3 scripts/check-docs.py
python3 scripts/codex-agents/generate.py --check
bash hooks/tests/run-tests.sh
git diff --check

6. コミットしてプッシュする

重要：デフォルトブランチへのプッシュは公開を意味します。 Claude Code のプラグインマーケットプレイスは、最新のコミットを自動的に取得します。

# Stage only reviewed, owned paths; never sweep unrelated worktree changes.
git add .claude-plugin/plugin.json .codex-plugin/plugin.json CHANGELOG.md README.md
git add path/to/each/reviewed/component
git commit -m "Release vX.X.X"
git push origin <default-branch>
git log origin/<default-branch>..<default-branch>

いずれかの実際のマニフェストのバージョンを更新した場合は、同じセッション内でプッシュします。コミット済みでもプッシュされていないバージョン更新は、公開されずに取り残されます。

7. すべてのホストで公開を確認する

プッシュ後、プラグインの更新が利用可能になっていることを確認します。

CLAUDECODE= claude plugin update <plugin-name>@<publisher>
codex plugin marketplace upgrade
codex plugin add <plugin-name>@<publisher>

CLAUDECODE= プレフィックスを付けると、Claude セッションのネストによるエラーを回避できます。Codex では、marketplace add は既存のスナップショットを更新しません。再インストールする前に marketplace upgrade を使用します。インストール先のルートに新しいバージョンが含まれていることを確認してから、新しいセッションで両方のホストのスモークテストを行います。

**注：**マーケットプレイスに新しいバージョンが反映されるまで、数分かかる場合があります。

8. 下流の参照を更新する

プラグインのバージョンが別の場所（マーケットプレイスのページ、ドキュメント、lib/plugins.ts など）で管理されている場合は、新しいバージョンに合わせてそれらの参照を更新します。

単独のエージェントスキルのワークフロー

Claude Code プラグインにバンドルされていないスキルについては、agentskills.io の仕様に従います。

1. SKILL.md を検証する

フロントマターが仕様を満たしていることを確認します。詳細については、references/agentskills-spec.md を参照してください。

必須フィールド：

• name：1～64 文字の小文字英数字とハイフンで構成し、ディレクトリ名と一致すること
• description：1～1024 文字で、スキルの内容と使用する状況を説明すること

任意のフィールド：

• license、compatibility、metadata、allowed-tools

2. 構成を検証する

skill-name/
├── SKILL.md          # Required
├── scripts/          # Optional executables
├── references/       # Optional docs loaded on demand
└── assets/           # Optional static resources

3. メタデータによるバージョン管理

フロントマターの metadata フィールドでバージョンを管理します。

metadata:
  author: org-name
  version: "1.1.0"

4. 配布

スタンドアロンのスキルはディレクトリとして配布します。一般的な方法は次のとおりです。

• Git リポジトリ（GitHub にプッシュ）
• アーカイブ（スキルディレクトリを zip 形式にする）
• パッケージレジストリ（該当する場合）

よくある問題

プラグインが更新されない

claude plugin update で変更が反映されない場合：

• デフォルトブランチ（通常は main または master）にプッシュされていることを確認します
• .claude-plugin/plugin.json が有効な JSON であることを確認します
• マーケットプレイスに反映されるまで数分待ちます

バージョンがすでに存在する

バージョン文字列が以前のコミットですでに使用されている場合は、プッシュする前に次のパッチバージョンへ引き上げてください。

ネストされたセッションのエラー

アクティブな Claude Code セッション内から実行する場合は、「ネストされたセッション」エラーを回避するため、CLI コマンドの先頭に必ず CLAUDECODE= を付けてください。

追加リソース

リファレンスファイル

• references/agentskills-spec.md — スタンドアロンのスキル向け、agentskills.io の仕様の完全な概要