skill-publisher

スキルパブリッシャー

skill-manager リポジトリ内のスキルを準備、パッケージ化し、設定された GitHub リポジトリに公開します。対応するレイアウトは次のとおりです。

• スタンドアロン： skills/<skill-id>/ → <github.owner>/<skill-id>。
• シリーズ： skills/<series>/<skill-id>/ → そのシリーズに設定されたリポジトリとターゲットパス。

このスキルは、ユーザーが所有する、または保守を許可されているスキルを公開します。無関係なサードパーティ製スキルを検索、インストール、再公開することはありません。

動作モード

ユーザーの依頼からモードを判断し、簡潔に伝えます。

• 監査／確認： メタデータと完全性を調べます。ファイルやリモートの状態は変更しません。
• 準備／パッケージ化： 検証してローカルアーティファクトを作成します。リモートリポジトリは変更しません。
• 公開／リリース： アーティファクトを準備し、具体的なリリース計画を提示して、リモートへの変更について明示的な確認を得てから公開し、結果を検証します。

確認やパッケージ化の依頼を公開の依頼に変えてはいけません。

絶対に守る安全ルール

1. 確認なしでリモートを変更しないでください。 リポジトリの作成、コミットのプッシュ、公開範囲の変更、PR の作成またはマージ、タグ／リリースの作成、リリースメタデータの変更を行う前に、対象、公開範囲、ブランチ、バージョン、ファイル、操作を正確に伝えてください。明示的な確認を得てください。実質的に異なる操作には、それぞれ新たな確認が必要です。
2. 破壊的な Git のショートカットを使用しないでください。 強制プッシュ、タグの強制更新、リリースの削除と再作成、git reset --hard の実行、公開を容易にする目的での git clean -fdx の使用は禁止です。ターゲットリポジトリ内の無関係なファイルを上書きしないでください。
3. ローカルの作業を保護してください。 編集やコミットの前に git status を確認してください。ユーザーの変更を保持してください。リリースコミットに無関係なステージ済みファイルや未追跡ファイルを含めないでください。作業ツリーの状態から安全に分離できるか明確でない場合は、作業を中止し、障害となっている点を説明してください。
4. 設定を推測しないでください。 series.json と対象スキルの SKILL.md を読み、実際の設定からターゲットを解決してください。シリーズのターゲットが未設定、またはスキルの参照先が曖昧な場合は、準備できていることと不足している設定を報告し、リポジトリを作り上げないでください。
5. 認証情報を絶対に漏らさないでください。 認証状態の確認には gh auth status を使用してください。トークンを表示したり、認証情報ファイルをコピーしたり、URL にシークレットを埋め込んだり、チャットへの認証情報の貼り付けをユーザーに求めたりしないでください。
6. バージョンの不変性を守ってください。 既存のバージョンタグや GitHub Release を黙って上書きしてはいけません。バージョンがすでに存在する場合は、公開済みの状態を比較してください。同等性を確認できた場合に限り「公開済み」と報告してください。それ以外の場合は中止し、新しいバージョンを推奨してください。
7. 公開前確認と公開後確認を分けてください。 同じ初回リリースを作成する前提条件として、対応する GitHub Release の存在を求めてはいけません。公開前に競合を確認し、リリースが存在するかを検証するのは公開後に限ります。
8. 検証結果を正直に伝えてください。 実際に実行した確認と、推奨しただけの確認を区別してください。コマンド結果を調べてリモートの状態を検証することなく、パッケージ化、プッシュ、リリースが成功したと主張してはいけません。

ワークフロー

1. スキルとターゲットを特定する

1. skill-manager リポジトリのルートと、依頼されたスキルのフォルダーを見つけます。
2. スキル参照を正規化します。スタンドアロンスキルには <skill-id> を、シリーズスキルには <series>/<skill-id> を使用します。同じ ID が複数のシリーズにある場合は、シリーズ名を含む明示的な参照を求めてください。
3. 該当する場合は、スキルの SKILL.md、README.md、LICENSE、agents/ 内のメタデータ、series.json を読みます。
4. 設定から公開先のリポジトリとリポジトリ内のパスを解決します。スタンドアロンのターゲットは、github.owner が明示的に設定されている場合に限り、その値とスキル ID から導き出せます。ターゲットリポジトリのデフォルトブランチ名が main だと決めつけてはいけません。

2. 意図とリリースバージョンを確認する

1. ユーザーが監査、パッケージ化、公開のどれを依頼したかを判断します。確認や準備の依頼だけから、リモートへの変更を許可されたと推測してはいけません。
2. スキルのフロントマターから metadata.version を読み取り、アクセス可能であれば関連する Git タグ／GitHub Releases を確認します。
3. セマンティックバージョニングを使用します。
   • PATCH： 意味のある機能を追加しない、後方互換性のある修正、文言の訂正、内部的な明確化。
   • MINOR： 既存の目的やインターフェースとの互換性を保つ、ワークフロー、機能、ガイダンスの追加。
   • MAJOR： スキルで想定されるワークフロー、インターフェース、メタデータの契約、サポート対象のレイアウトに対する破壊的変更。
4. パッケージを再構築するだけの理由で、バージョンを上げてはいけません。バージョンを上げる必要があるものの、想定されるリリース範囲が曖昧な場合は、バージョンを提案し、変更前に確認を求めます。入手できないタグについての仮定に基づいて、バージョンを決めてはいけません。
5. SKILL.md のバージョンを正とします。パッケージのマニフェスト、対象リポジトリの内容、Git タグ、Release 名がすべてこのバージョンと一致することを確認します。

3. スキルを検証する

リポジトリで実際に使用されている検証コマンドを実行し、報告されたエラーはすべてブロッカーとして扱います。

skillctl check --skill <skill-ref>

エントリーポイントが利用できず、管理リポジトリで文書化された代替手段がサポートされている場合は、次を使用します。

PYTHONPATH=src python -m skill_manager check --skill <skill-ref>

どちらも利用できない場合、代替コマンドを考案してはいけません。ブロッカーを報告し、不足している検証ツールに依存しない非破壊的なレビューのみを続行します。

最低限、以下を確認します。

• フロントマターが解析可能な YAML であり、有効なスキル name、有用な description、セマンティックバージョンの metadata.version、metadata.license、空でない metadata.topics が含まれていること。
• 管理リポジトリで求められる場合、スキルのディレクトリ名とフロントマターの名前が一致していること。
• README.md で目的、要件、使用方法、制限、リリース手順を説明していること。
• ライセンスファイルが存在し、想定される再利用条件と一致していること。
• スキルから参照されるリンク先ファイルとパスが存在すること。
• 例やコマンドが、実際の管理リポジトリおよびリポジトリのレイアウトと一致していること。

完全性のゲートを緩めたり削除したりして、検証エラーを「修正」してはいけません。

4. アーティファクトをパッケージ化して確認する

検証に合格した後にのみ、パッケージ化コマンドを実行します。

skillctl package --skill <skill-ref>

パッケージ化では、検証ゲートを再度実行する必要があります。終了コードだけを信用せず、生成されたアーカイブを確認します。

• アーティファクトが存在し、開けること、および想定されるスキルファイルが含まれていることを確認します。
• MANIFEST.json を調べ、スキル ID、バージョン、ライセンス、トピック、エントリーポイントを確認します。
• 無関係なプロジェクトファイル、.git/、仮想環境、キャッシュ、認証情報、.env ファイル、秘密鍵、誤って含まれたローカルアーティファクトがないことを確認します。
• 参照されている補助ファイルが含まれ、パスに移植性があることを確認します。
• 決定論的なパッケージ化を維持します。検証後にアーカイブの内容を変更した場合は、再ビルドして再確認します。

コマンドの出力先が明確でない場合は、ヘルプまたは出力を確認します。アーティファクトのファイル名を推測してはいけません。

5. GitHub の公開先を事前確認する

公開リクエストの場合：

1. gh auth status で認証状態を確認します。認証情報は開示しないでください。
2. 対象リポジトリが存在する場合は、GitHub CLI または利用可能な別の読み取り専用手段を使って調査します。正式なオーナー名／リポジトリ名、公開範囲、URL、デフォルトブランチ、説明、トピック、README、ライセンス、ブランチ保護の制約を、確認できる範囲で記録します。
3. 実際のデフォルトブランチを照会します。main をハードコードしてはいけません。
4. v<version>（またはリポジトリで定められたタグ規則）が Git タグまたはリリースとしてすでに存在するか確認します。プッシュの準備を進める前に、競合を解消します。
5. リリース前に存在していなければならないメタデータ（リポジトリの説明、トピック、README、ライセンス、正しいスキルファイル）と、リリース後に確認するメタデータ（タグ、リリースページ、リリースノート、添付パッケージアセット）を区別します。
6. 対象リポジトリが存在しない場合は、リポジトリ名、説明、トピック、対象パス、公開範囲を提案します。ユーザーが明示的に公開をリクエストしない限り、デフォルトでは非公開にします。作成前に明示的な確認を得てください。
7. シリーズの公開先が設定されていない場合は、リモートへの公開を中止します。パッケージの準備が完了していることは報告してかまいません。

6. リリース計画を提示し、確認を得る

最初にリモートを変更する前に、以下を要約します。

• 元のスキルと現在のバージョン／提案するバージョン
• 検証結果とパッケージの結果
• 対象リポジトリの正確な URL と公開範囲
• 対象パスと実際のデフォルトブランチ
• 追加、更新、削除するファイル（通常、削除は明示的に記載された場合を除いて行いません）
• 予定しているコミット／ブランチ／PR の方針
• タグとリリース名、リリースノートの出典、添付するパッケージアセット
• リポジトリのメタデータに対する変更

この具体的な計画について、ユーザーに確認を求めてください。公開先、公開範囲、バージョン、または対象ファイルがその後変更されている場合、以前の曖昧な指示を根拠にしてはいけません。

7. 変更を安全にステージングする

1. 確認後、書き込みを行う前に、対象の最新のリモート状態を再確認します。
2. 分離されたクローン、ワークツリー、または専用の公開用チェックアウトを優先します。使用前に、その origin と現在のブランチを確認します。
3. 対象の実際のデフォルトブランチをフェッチします。既存ファイルとリポジトリ固有のワークフローを保持します。検証済みのスキルファイルのみを設定済みの対象パスにコピーします。マネージャーリポジトリ全体をコピーしてはいけません。
4. 差分とステータスを確認します。提案するコミットに無関係な変更が含まれていないことを確認します。元のスキルフォルダーに存在しないという理由だけで、リポジトリのファイルを削除してはいけません。
5. 意図したスキルファイルだけをコミットします。リポジトリでブランチまたはプルリクエストが必須の場合は、そのポリシーに従い、保護を回避してはいけません。デフォルトブランチへの直接プッシュが許可されるのは、ユーザーがその方法を明示的に承認し、リポジトリのポリシーでも許可されている場合に限ります。
6. 強制プッシュや、リモートで同時に行われた変更の破棄は決して行わないでください。リモートが進んでいる場合は、安全にフェッチして調整します。推測なしに競合を解決できない場合は中止します。

8. GitHub リリースを作成する

対象のコンテンツがプッシュされた後、または必要な PR がマージされた後にのみ、次の手順を実行します。

1. 対象のコミットに、検証済みのスキルファイルが含まれていることを確認します。
2. 対象バージョンのタグとリリースが、異なるコンテンツを指していないことを確認します。
3. 実際の差分または提供された変更履歴から、簡潔で事実に基づいたリリースノートを作成します。検証していないテストや機能について主張してはいけません。
4. 対象リポジトリに別の規則が記載されていない限り、v<version> を使用してリリースを作成します。
5. 成果物が利用可能で、リリース計画に含まれている場合は、パッケージ手順で生成された検証済みの再現可能な ZIP を添付します。無関係なファイルの名前を変更して、パッケージとして渡してはいけません。
6. 既存のリリースやタグを上書きしてはいけません。事前確認と作成の間に競合が発生した場合は中止し、報告します。

9. 検証して報告する

公開後、ツールが利用できる場合は、リモートの結果を独自に検証します。

• 対象リポジトリと公開先のパスが正しいこと。
• 意図したコミットが想定ブランチに存在すること。
• タグとリリース名がスキルのバージョンと一致すること。
• リリース URL とリリースノートを利用できること。
• 予定していた場合、想定されたパッケージアセットが添付され、ダウンロードできること。
• リポジトリの説明、トピック、README、ライセンスが正確であること。
• 無関係なファイルやシークレットが公開されていないこと。

ソーススキル、バージョン、対象 URL、コミット／ブランチ、リリース URL、アーティファクトのパス、合格したチェック、実施していないチェック、残っている問題を列挙した簡潔なレポートを返します。パッケージのみのモードでは、ローカルのアーティファクトのパスを示し、何も公開していないことを明記します。

失敗時の対応と復旧

• 検証失敗： パッケージングと公開を中止し、失敗したチェックと、安全に実施できる最小限の修正を列挙します。
• パッケージング失敗： ソースファイルを保持し、エラーを調査して、原因を修正してから再ビルドします。
• 認証または権限の失敗： 処理を中止し、シークレットを開示せずに不足している権限の種類を報告します。
• シリーズの公開先がない： ローカルの検証／パッケージングは完了している可能性がありますが、設定がないため公開できないことを報告します。
• 作業ツリーが汚れている、または無関係なファイルがステージングされている： 状態を保持し、別のワークツリーでリリースを分離するか、ユーザーに解決を依頼します。
• リリース中にリモートが変更された： 再度フェッチして差分を確認し、並行して行われた作業を上書きしません。
• バージョンがすでにリリースされている： タグ、コミット、ソースのバージョン、アセットを比較します。同一性を確認できた場合は既存のリリースを報告します。確認できない場合は、履歴を書き換えるのではなく、新しいバージョンを要求します。
• 一部のみ公開された： どの手順が成功したかを正確に報告します。リモートの状態を再確認してから、最初に未完了となった手順を再開します。リポジトリの作成、プッシュ、タグ付け、リリース作成を無条件に繰り返してはいけません。

最終的な制約

• 結果の証拠がない限り、またリモートへの公開では読み戻しチェックを行わない限り、操作が成功したと主張してはいけません。
• 推測に基づく推奨事項を事実として扱ってはいけません。利用できないチェックには 未検証 と明記します。
• ユーザー向けの出力は、判断事項、実際の変更、検証、阻害要因に絞ります。認証情報、過剰なコマンドログ、無関係なリポジトリの内容をそのまま出力してはいけません。