codex-theme-installer

CodexThemes から Codex テーマをインストールする

codexthemes.ai から公開テーマのポータブルパッケージをダウンロードし、ソースファイルを展開して ~/.codexthemes/themes/<theme-id>/ に配置します。このスキルは単独で動作します。ダウンロード、検証、ローカルへのインストールは TypeScript スクリプトが担当します。ギャラリーの検索（codex-theme-finder）、テーマの作成（codex-theme-creator）、テーマの送信（codex-theme-submitter）は行いません。適用は codex-theme-switcher が担当しますが、インストールが成功したら直接そちらに進みます（ステップ 4）。ファイルをインストールして終わりでは、作業は完了していません。必要なローカルツールは Node.js 20+ と npx のみです。

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

ステップ 1：テーマを特定する

インストール対象をテーマ ID に解決します。これは codex-theme-finder の検索結果、または https://codexthemes.ai/themes/<theme-id> の URL に含まれる小文字のスラッグです。スクリプトはどちらの形式も受け付けます。ユーザーがスタイルを説明しているだけでテーマ名を指定していない場合は、ID を推測せず、まず codex-theme-finder で候補を探してください。

ステップ 2：インストールする

npx tsx scripts/install-theme.ts <theme-id | codexthemes.ai theme URL> [--force]

無料の匿名利用枠では API キーなしでダウンロードできるため、最初からキーを要求しないでください。キーがすでに設定されている場合（CODEXTHEMES_API_KEY 環境変数、または ~/.codexthemes/credentials.json）、スクリプトはより高い上限を利用できるよう、自動的にキーを送信します。

スクリプトは、ダウンロードしたパッケージの書き込み前に、形式、スキーマのバージョン、テーマ ID の一致、安全な相対ファイル名、サイズが 30 MB 以下であることを検証します。その後、theme.json、スタイルシート、アートワーク、readme を ~/.codexthemes/themes/<theme-id>/ に展開します。既存の空でないテーマディレクトリへの上書きは拒否されます。ローカルのコピーを置き換えることについてユーザーの確認を得た後に限り、--force を渡してください。ディレクトリにはユーザー自身が編集した内容が含まれている可能性があります。

インストール済みのテーマを更新する場合：公開済みテーマは codexthemes.ai 上で更新されます。そのため、すでにインストールしたテーマの更新、アップグレード、再ダウンロードをユーザーから依頼された場合は、--force を付けて再インストールしてください。ローカルのコピーにユーザー自身が編集した内容が含まれていない限り、更新の依頼自体を確認とみなします（編集内容がある場合は、先に警告してください）。ファイルの配置後はステップ 4 に進み、実行中のアプリを実際に新しいバージョンへ切り替えてください。同じテーマ ID のホットスワップでは、更新された CSS が再注入されます。

ステップ 3：クォータとレート制限に対処する

HTTP 429 または 402 が返された場合、無料クォータを使い切っています。スクリプトのエラーメッセージには Retry-After の値が含まれている場合があります。ループで再試行しないでください。無料のダウンロードクォータを使い切ったことをユーザーに伝え、個人用 API キーの設定を案内してください。

1. https://codexthemes.ai/settings/apikeys でキーを作成します。
2. キーを保存します：printf '%s' "<api-key>" | npx tsx scripts/apikey.ts set（stdin を使うとキーがシェルの履歴に残りません。apikey.ts set <key> も使用できます。）
3. インストールを再実行します。

現在のキーの状態は npx tsx scripts/apikey.ts status で確認できます。保存済みのキーを削除するには npx tsx scripts/apikey.ts clear を実行します。キー全体を出力しないでください（スクリプトはマスクした形式のみを表示します）。プロジェクトファイルに書き込んだり、コミットしたりしないでください。

401／403 が返された場合、設定済みのキーは無効または取り消されています。同じ手順で新しいキーを作成するようユーザーに案内してください。404 が返された場合、そのテーマ ID は存在しません。codex-theme-finder で ID を再確認してください。

ステップ 4：有効化する、またはユーザーに次の正確な返信を伝える

インストールの依頼は、ユーザーがテーマのファイルを保存するだけでなく、Codex でテーマを確認したいという意味です。インストール先（~/.codexthemes/themes/<theme-id>/）、テーマのバージョン、書き込んだファイルを報告し、そのまま codex-theme-switcher を使って有効化に進みます。codex-theme-switcher がインストールされていない場合は、このスキルのブートストラップと同じ方法でセットアップします（npx skills add codexthemes/skills --skill codex-theme-switcher -g -a codex）。

• Codex がすでにデバッグエンドポイントを公開している場合は、switcher の switch-theme.ts apply <theme-id> で今すぐホットスワップし、switch-theme.ts status で確認します。ホットスワップは元に戻せるため、インストールの依頼以外に確認は必要ありません。
• 有効化に Codex の再起動が必要な場合は、黙って再起動せず、「インストール済み」の時点で止めないでください。会話の最後に、続行に必要な正確な返信をユーザーに伝えます。たとえば、「apply と返信してください。Codex を再起動して <theme-id> を有効化します。」とします。ユーザーが返信したら、switcher の --launch フローに従います。

「ファイルはインストール済みですが、適用されていません」とだけ伝え、次にできる操作を示さずに会話を終えてはいけません。また、switcher の status が active を報告するまでは、テーマが有効だと主張してはいけません。