codex-theme-finder

CodexThemes で Codex テーマを検索する

codexthemes.ai の公開テーマギャラリーを検索します。このスキルは単独で動作します。検索リクエストと API キーの保存は、独自の TypeScript スクリプトが処理します。テーマの作成、インストール、投稿は行いません。これらは codex-theme-creator、codex-theme-installer、codex-theme-submitter が担当します。必要なローカルツールは Node.js 20+ と npx のみです。

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

ステップ 1：検索する

ユーザーのリクエストを短い検索語（スタイル、題材、雰囲気。例：dark anime、pastel floral light）に変換し、次を実行します。

npx tsx scripts/find-themes.ts <terms...> [--limit <1-50>] [--page <n>] [--sort <popular|newest|name>]

無料の匿名利用枠内であれば API キーなしで検索できるため、最初からキーを要求しないでください。キーがすでに設定されている場合（環境変数 CODEXTHEMES_API_KEY または ~/.codexthemes/credentials.json）、スクリプトが自動的に送信し、より高い上限で利用できます。出力の auth フィールドに、使用されたモードが表示されます。

最初の検索結果が少ない場合は、異なる検索語で複数回検索してください。ただし、同じクエリを繰り返し実行してはいけません。

ステップ 2：検索結果を提示する

最も適した候補を提示します。ギャラリーに候補が複数ある場合は、最初の 1 件だけでなく、複数（最大 5 件）を提示してください。結果が 1 件だけだと判断する前に、より幅広い検索を 1〜2 回実行してください。おすすめする各テーマについて、id、名前、作者、短い説明、公開 url（codexthemes.ai の詳細ページ。ユーザーがブラウザーでテーマを表示できるよう、必ず記載してください）、およびプレビュー画像を表示します。すべての結果には image URL が含まれています。その画像を一時ファイルにダウンロードし、ローカル画像をユーザーに表示してください。チャットの Markdown でリモート URL を直接表示してはいけません。正しく表示されないことがよくあります。結果に画像がない場合は、壊れた画像を表示する代わりに「プレビューなし」と記載してください。codex-theme-installer が必要とするため、テーマの id は見えるようにしてください。

結果には 3 種類が混在しています。kind と installable を確認してください（各エントリの guidance フィールドにも次の手順が記載されています）。

• installable: true — .codex-theme パッケージです。codex-theme-installer でワンクリックインストールできます。
• kind: "theme"、installable: false — アーカイブパッケージ（zip）です。エージェントではインストールできません。ユーザーに url を案内し、そこでサインインしてアーカイブをダウンロードし、手動でインストールしてもらいます。
• kind: "skin" — パッケージのないデザインリファレンスです。url を共有し、codex-theme-creator で見た目を再現することを提案してください。

結果が空の場合は、その旨を伝えて幅広い検索語を提案するか、codex-theme-creator でカスタムテーマを作成することを提案してください。

ステップ 3：インストールを提案する — 結果の一覧だけで終わらせない

テーマを見つけて終わりではありません。各結果の種類に応じたアクションを提示し、次につなげてください。

• インストール可能な候補が複数ある場合 → どれをインストールするか尋ねます。例：「テーマ id（例：shaolin-kickoff）を返信してください。インストールして適用します。」
• インストール可能な候補がちょうど 1 件だけの場合 → そのテーマを直接提案します。「install と返信してください。<id> をインストールして適用します。」
• アーカイブのみのテーマ（installable: false）→ ユーザーに url を案内し、そこでサインインしてアーカイブをダウンロードし、手動でインストールできることを説明します。
• スキン（kind: "skin"）→ ユーザーに url を案内し、「codex-theme-creator でこの見た目をインストール可能なテーマとして再現できます。作成しますか？」と提案します。

ユーザーが選択したら、codex-theme-installer に引き継ぎます（見つからない場合は、このスキルと同じ方法でセットアップします：npx skills add codexthemes/skills --skill codex-theme-installer -g -a codex）。その後、インストーラーが codex-theme-switcher を使って有効化まで行います。検索結果の一覧だけで終わり、インストール方法を案内しないまま会話を終えてはいけません。

ステップ 4：クォータとレート制限への対処

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

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

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

401 または 403 が返された場合、設定済みのキーが無効であるか、取り消されています。同じ手順で新しいキーを作成するようユーザーに案内してください。