codex-theme-submitter

CodexThemes に Codex テーマを投稿する

既存のエクスポート済み .codex-theme パッケージ、または URL から抽出したリンク付きテーマのショーケース（スキン）を codexthemes.ai に投稿します。このスキルは単独で動作します。API キーの保存と投稿には、スキル独自の TypeScript スクリプトを使用します。テーマのソースの作成、編集、検証、エクスポートは行いません。これらは codex-theme-creator の役割です。必要なローカルツールは Node.js 20+ と npx のみです。

予期しない API レスポンスの原因を調べる場合や、エンドポイントの動作を変更する場合は、事前に references/submit-api.md を読んでください。すべてのコマンドは、インストール済みのスキルディレクトリから実行してください。

ユーザーが共有した内容に応じて手順を選択してください。ディスク上にあるものを基準にしてはいけません。

• エクスポート済み .codex-theme パッケージ、またはローカルのテーマ ID → パッケージ投稿。手順 1～5 を実行してください。
• テーマのショーケース（リポジトリ、ギャラリー、投稿など）の URL → リンク投稿。「URL からリンク付きテーマを投稿する」を参照してください。リンク投稿にはパッケージもエクスポートもローカルのテーマソースも必要ありません。一致するものを探すために ~/.codexthemes/exports/ を検索してはいけません。また、最初にパッケージをエクスポートするようユーザーに求めたり、「見つからない」パッケージを理由に処理を止めたりしてはいけません。ユーザーがインストール可能なパッケージの公開を明示的に希望した場合に限り、URL の共有にパッケージ投稿の手順を使ってください。
• 具体的な情報がない（「自分のテーマを投稿して」など）→ ローカルで確認してから質問してください。
  1. ~/.codexthemes/exports/*.codex-theme を一覧表示します。パッケージが 1 つだけの場合は、ID、バージョン、更新日時を示して、投稿対象か確認します。複数ある場合は、一覧を示してどれを投稿するか尋ねます。
  2. エクスポートがなく、~/.codexthemes/themes/ にテーマソースがある場合は、存在するソースを伝えて、次の 2 つの選択肢を提示します。codex-theme-creator でいずれかをエクスポートしてパッケージを投稿するか、テーマのページの URL を共有してリンク投稿するかです。
  3. ローカルに何もない場合は、掲載するテーマの URL（リンク投稿）を尋ねるか、まずテーマを作成するために codex-theme-creator を案内します。 確認できた具体的な情報を添えて、一度だけ質問してください。どのテーマを指しているか推測したり、複数の中から黙って選んだりしてはいけません。

手順 1：パッケージを見つける

ポータブルな .codex-theme パッケージのみ投稿できます。管理されたエクスポート先は ~/.codexthemes/exports/<theme-id>.codex-theme です。

• ユーザーがパッケージのパスを指定した場合は、そのパスを使用します。
• ユーザーがテーマ ID またはソースディレクトリを指定した場合は、~/.codexthemes/exports/ 内で対応するファイルを探します。
• パッケージが存在しない場合は、処理を中止し、まず codex-theme-creator（export-theme.ts）でエクスポートするようユーザーに伝えます。パッケージの JSON を手作業で組み立てたり、テーマソースの生ファイルを投稿したりしてはいけません。
• パッケージには preview を埋め込む必要があります。これはサイドバーが表示されたワークスペースのキャプチャで、codexthemes.ai のギャラリー画像および詳細画像になります。submit-theme.ts は、これがないパッケージの投稿を拒否します（ギャラリーに背景画像がそのまま表示されてしまいます）。修正するには、テーマの previews/ ディレクトリにキャプチャを追加してから codex-theme-creator で再エクスポートするか、投稿時にアプリ全体のスクリーンショットを --preview /absolute/screenshot.png で指定します。テーマの背景画像を --preview に指定してはいけません。--allow-art-preview は、ユーザーが背景画像をギャラリー画像として使うことを明示的に了承した場合に限り使用できます。
• 公開される正確なプレビューを目視で確認してください。実際の Codex のキャプチャには、サイドバーやワークスペース内にアカウントの表示名、リポジトリ名、プロジェクト名、タスクのタイトル、ファイルパス、ソースの添付ファイル、会話のテキストなどが表示されることがあります。非公開情報が含まれる可能性がある場合は、アップロード前に処理を止め、サニタイズしたワークスペース全体のキャプチャ、または汎用的な内容を使って生成済みのデザインプレビューを提案します。選んだ画像をユーザーに見せて、確認を得てください。ドライランが成功しても、画像内の意味的なプライバシー漏えいは検出できません。

作品の所有権を調査したり、描かれている題材を理由に投稿を妨げたりしてはいけません。投稿ページと API では、アップロードするユーザーに共有許可の確認を求めます。この確認はユーザーとサーバーに委ねてください。

ステップ 2：API キーがあることを確認する

ローカルで設定された CodexThemes API キーを確認します。

npx tsx scripts/apikey.ts status

キーは、まず CODEXTHEMES_API_KEY 環境変数から取得され、次に ~/.codexthemes/credentials.json から取得されます。

キーが設定されていない場合、推測したり、でっち上げたりしないでください。次のページで API キーを作成するようユーザーに案内します。

https://codexthemes.ai/settings/apikeys

ユーザーから提供されたキーを保存します。

printf '%s' "<api-key>" | npx tsx scripts/apikey.ts set

キーがシェルの履歴に残らないよう、標準入力を使う形式を推奨します。apikey.ts set <key> も使用できます。キー全体をユーザーに表示してはいけません（スクリプトにはマスクされた形式のみが表示されます）。また、プロジェクトファイルに書き込んだり、コミットしたりしないでください。保存済みのキーは npx tsx scripts/apikey.ts clear で削除します。

ステップ 3：ドライランで事前チェックする

ネットワークに接続せずに、パッケージと設定を検証します。

npx tsx scripts/submit-theme.ts /absolute/path/<theme-id>.codex-theme --dry-run

ドライランでは、パッケージが有効な codex-theme ドキュメントとして解析できること（形式、スキーマバージョン、マニフェストのスラッグとバージョン、空ではない CSS、≤30 MB）、解決されたエンドポイントとキーの設定状況、ギャラリーの preview 状態が報告されます。preview は present（パッケージ内に存在する、または --preview で指定されている）か、提出が未加工のアートワークにフォールバックして拒否されるという警告のいずれかです。報告された問題はすべて、提出前に修正してください。パッケージ自体が無効な場合は、手作業で編集せず、codex-theme-creator に戻って再エクスポートするようユーザーに案内してください。

ステップ 4：提出する

API はエージェントによる唯一の提出方法です。ブラウザーで codexthemes.ai/submit を開いたり、ブラウザー拡張機能を操作したり、ウェブアップロードフォームに入力したりしてはいけません。このフォームのファイル選択機能は人間向けであり、自動化では動作しません（Chrome は拡張機能によるファイルへのアクセスをブロックします）。submit-theme.ts が失敗した場合、または API キーが設定されていない場合は、そのことを明確に伝えて修正方法を案内してください。ウェブサイトのフォームに切り替えてはいけません。

提出すると、テーマは codexthemes.ai ですぐに公開されます。審査待ちキューはありません。すでに公開済みのテーマ ID を再提出するのが通常の更新方法です（manifest.version を更新し、再エクスポートしてから、もう一度提出します）。アップロード前に、最終 ID、バージョン、作者、正確なプレビュー画像、および公開が即時であることを提示してください。公開とプレビューの選択についてユーザーに確認してから、次を実行します。

npx tsx scripts/submit-theme.ts /absolute/path/<theme-id>.codex-theme \
  [--preview /absolute/workspace-screenshot.png]

スクリプトはパッケージを UTF-8 JSON として Authorization: Bearer <key> を付けて POST https://codexthemes.ai/api/themes/submit に送信します。--preview を指定すると、アップロード前にパッケージ内のギャラリー用プレビューが、指定されたアプリ全体のスクリーンショットに置き換わります。ベース URL を CODEXTHEMES_API_BASE で上書きするのは、ユーザーが別の環境（たとえばステージング）を明示的に指定した場合に限ります。

ステップ 5：結果を報告する

成功すると、テーマはすぐに公開され、レスポンスには詳細ページの URL（url、例：https://codexthemes.ai/themes/<theme-id>）が含まれます。必ずそのリンクと、公開された ID およびバージョンをレスポンスからユーザーに伝えてください。指定されたスラッグがすでに別の提出者または組み込み項目に使われている場合、サーバーは上書きせず、スラッグにランダムなサフィックスを加えて公開するため、最終的な ID／URL は送信時のものと異なることがあります。同じ API キーで自分のテーマ ID を再提出すると、公開済みテーマがその場で更新されます。変更が反映されるよう、先にマニフェストのバージョンを更新してください。

失敗した場合は、HTTP ステータスとサーバーのメッセージを明確に伝え、その内容に応じて対応してください。

• 401／403：キーが無効または失効しています。新しいキーを https://codexthemes.ai/settings/apikeys から取得して、ステップ 2 をやり直すようユーザーに案内してください。
• その他のエラー：references/submit-api.md を参照してください。

失敗した提出をループで再試行してはいけません。また、スクリプトが "status": "submitted" を報告していない限り、テーマを提出したと主張してはいけません。

URL からリンク付きテーマを投稿する

ユーザーがテーマの紹介ページ（リポジトリ、ギャラリーページ、投稿など）の URL を共有した場合、リンク付きディレクトリエントリ（スキン）として公開します。この手順は単独で完結します。.codex-theme パッケージも、エクスポートも、ローカルのテーマソースも必要ありません。また、それらが提供されるのを待って処理を止めてはいけません。抽出した名前、作者、プレビュー画像、URL だけで投稿できます。

1. 抽出：ページを取得し、テーマ名、作者、最適なプレビュー画像を取り出します。サイドバーとコンテンツが表示されたウィンドウなど、テーマを適用したワークスペースの画像を選び、og:image または README／スクリーンショット内の画像を優先します。壁紙だけの画像やロゴはプレビューに使用しないでください。作者は表示名のみです（ページの作者、リポジトリの所有者、署名欄の名前）。@ハンドルと括弧付き ID は削除してください。数字探索者 (@slimeXDX) → 数字探索者 のようにします。ハンドルにはソース URL からアクセスできるためです。また、スクリプトは (@handle) を含む作者名を拒否します。
2. スラッグとタグの決定：テーマ名から短い小文字の ASCII スラッグを作成します。これは公開 URL https://codexthemes.ai/skins/<slug> になります。ラテン文字以外の名前はローマ字表記にするか翻訳してください（功夫女足 → kungfu-womens-football）。タイムスタンプ ID にフォールバックさせたり、無関係な単語を使ったりしないでください。また、ページとプレビューからスタイル、雰囲気、題材を表す短い英語の小文字タグを 2～5 個作成します（例：editorial, dark, minimal）。タグは必ず指定してください。タグはギャラリーの絞り込みに使用されます。
3. プレビューをダウンロードし、一時ファイルとして保存します（PNG、JPEG、または WebP、10 MB 未満）。プロジェクトのワークスペースには保存しないでください。
4. ユーザーに確認してからアップロードします。抽出した名前、スラッグ、作者、タグ、ソース URL、プレビューに使用する画像を提示してください。各項目を修正できるようにしてください。
5. 投稿（API キーが必要です。ステップ 2 と同じです。同様にウェブフォームは使用しないでください）：

npx tsx scripts/submit-skin.ts \
  --name "<theme name>" \
  --slug <ascii-slug> \
  --source-url "<the user's URL>" \
  --preview /absolute/preview.png \
  --tags "<tag1, tag2, tag3>" \
  [--author "<display name>"] [--description "<one-line description>"] [--mode light|dark|mixed] [--dry-run]

6. 結果を報告：成功すると、レスポンスに公開リスティング URL（https://codexthemes.ai/skins/<slug>）が含まれます。レスポンスから取得したリンクを必ずユーザーに伝えてください。スラッグがすでに別の投稿者に使われている場合、上書きせず、サーバーがランダムな接尾辞付きのスラッグで公開します。同じ API キーで自分のスラッグを再投稿すると、公開済みのエントリがその場で更新されます。

ページに使用可能なワークスペースのプレビュー画像がない場合は、アートワークで代用したりモックアップを生成したりせず、処理を中止してユーザーに画像の提供を依頼してください。