Back to Details

codex-theme-finder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Find Codex themes on CodexThemes

在CodexThemes上查找Codex主题

Search the published theme gallery on codexthemes.ai. This skill is standalone: its TypeScript scripts own the search request and API key storage. It does not create, install, or submit themes — codex-theme-creator, codex-theme-installer, and codex-theme-submitter own those jobs. The only required local tools are Node.js 20+ and 
npx
.
Read 
references/search-api.md
before diagnosing an unexpected API response or changing endpoint behavior. Run all commands from the installed skill directory.
搜索codexthemes.ai上已发布的主题库。此Skill是独立的：其TypeScript脚本负责处理搜索请求和API密钥存储。它不负责创建、安装或提交主题——这些工作由codex-theme-creator、codex-theme-installer和codex-theme-submitter负责。仅需的本地工具为Node.js 20+和
npx
。
在排查异常API响应或更改端点行为之前，请阅读
references/search-api.md
。所有命令均需从已安装的Skill目录运行。

Step 1: search

步骤1：搜索

Turn the user's request into short search terms (style, subject, mood — for example 
dark anime
, 
pastel floral light
), then run:
bash
npx tsx scripts/find-themes.ts <terms...> [--limit <1-50>] [--page <n>] [--sort <popular|newest|name>]
Searching works without any API key inside a free anonymous quota, so do not demand a key up front. When a key is already configured (
CODEXTHEMES_API_KEY
environment variable or 
~/.codexthemes/credentials.json
), the script sends it automatically for higher limits; the output's 
auth
field shows which mode was used.
Run more than one search with different terms when the first result set is thin, but never loop on the same query.
将用户的请求转化为简短的搜索关键词（风格、主题、氛围——例如
dark anime
、
pastel floral light
），然后运行：
bash
npx tsx scripts/find-themes.ts <terms...> [--limit <1-50>] [--page <n>] [--sort <popular|newest|name>]
无需API密钥即可在免费匿名配额内进行搜索，因此不要一开始就要求用户提供密钥。当已配置密钥（
CODEXTHEMES_API_KEY
环境变量或
~/.codexthemes/credentials.json
文件）时，脚本会自动发送密钥以获得更高限制；输出的
auth
字段会显示使用的模式。
当首次搜索结果较少时，可使用不同关键词进行多次搜索，但切勿重复执行同一查询。

Step 2: present the results

步骤2：展示结果

Present the closest matches — several candidates (up to 5) when the gallery has them, not just the first hit; run one or two broader searches before concluding there is only a single match. For each recommended theme show: id, name, author, short description, the public 
url
(its codexthemes.ai detail page — always include it so the user can view the theme in the browser), and its preview image. Every result carries an 
image
URL: download it to a temporary file and display that local image to the user — do not hotlink the remote URL in chat markdown, it often fails to render. If a result has no image, say "no preview" instead of showing a broken embed. Keep the theme 
id
visible — codex-theme-installer needs it.
Results mix three kinds — check 
kind
and 
installable
(each entry's 
guidance
field restates its next step):
  • installable: true
    — a 
    .codex-theme
    package; codex-theme-installer can install it one-click.
  • kind: "theme"
    , 
    installable: false
    — an archive package (zip). Not agent-installable: point the user to 
    url
    to sign in, download the archive, and install manually.
  • kind: "skin"
    — a design reference with no package. Share 
    url
    , and offer to recreate the look with codex-theme-creator.
If the result is empty, say so and suggest broader terms, or offer to create a custom theme with codex-theme-creator.
展示最匹配的结果——如果主题库中有多个候选（最多5个），不要只展示第一个结果；在得出仅存在单个匹配项的结论之前，先进行一到两次范围更广的搜索。每个推荐主题需展示：id、名称、作者、简短描述、公开
url
（其codexthemes.ai详情页——务必包含该链接，以便用户在浏览器中查看主题），以及预览图片。每个结果都带有一个
image
URL：将其下载到临时文件并向用户展示本地图片——不要在聊天markdown中直接链接远程URL，因为它通常无法渲染。如果某个结果没有图片，请显示“无预览”，而非展示损坏的嵌入内容。保持主题
id
可见——codex-theme-installer需要用到它。
结果分为三类——检查
kind
和
installable
字段（每个条目的
guidance
字段会说明下一步操作）：
  • installable: true
    — 一个
    .codex-theme
    包；codex-theme-installer可一键安装它。
  • kind: "theme"
    ，
    installable: false
    — 一个归档包（zip格式）。无法通过Agent安装：引导用户访问
    url
    登录，下载归档包并手动安装。
  • kind: "skin"
    — 一个无安装包的设计参考。分享
    url
    ，并主动提出使用codex-theme-creator复刻该外观。
如果结果为空，请告知用户并建议使用更宽泛的关键词，或主动提出使用codex-theme-creator创建自定义主题。

Step 3: offer installation — never end at the list

步骤3：提供安装选项——切勿仅停留在结果列表

Finding is not the finish line; close the loop with the action that fits each result's kind:
  • Several installable candidates → ask which one to install, for example: "Reply with a theme id (e.g. 
    shaolin-kickoff
    ) and I will install and apply it."
  • Exactly one good installable match → offer it directly: "Reply 
    install
    and I will install and apply 
    <id>
    ."
  • Archive-only theme (
    installable: false
    ) → give the user its 
    url
    and explain they can sign in there to download the archive for manual install.
  • Skin (
    kind: "skin"
    ) → give the user its 
    url
    and offer: "I can recreate this look as an installable theme with codex-theme-creator — want me to?"
When the user picks, hand off to codex-theme-installer (bootstrap it the same way this skill was bootstrapped if missing: 
npx skills add codexthemes/skills --skill codex-theme-installer -g -a codex
); the installer then chains into activation via codex-theme-switcher. Never end the conversation with only a result list and no install path.
找到主题并非终点；需根据每个结果的类型采取相应操作，完成闭环：
  • 多个可安装候选主题 → 询问用户要安装哪一个，例如：“回复主题id（如
    shaolin-kickoff
    ），我将为您安装并应用它。”
  • 恰好有一个合适的可安装匹配项 → 直接提供安装选项：“回复
    install
    ，我将为您安装并应用
    <id>
    主题。”
  • 仅归档包主题（
    installable: false
    ） → 向用户提供其
    url
    ，并说明他们可登录该链接下载归档包进行手动安装。
  • Skin（
    kind: "skin"
    ） → 向用户提供其
    url
    ，并主动提出：“我可以使用codex-theme-creator将此外观复刻为可安装主题——需要我这么做吗？”
当用户做出选择后，将任务移交至codex-theme-installer（如果未安装，可按照此Skill的引导方式进行安装：
npx skills add codexthemes/skills --skill codex-theme-installer -g -a codex
）；安装程序随后会通过codex-theme-switcher完成主题激活。切勿仅展示结果列表而不提供安装路径就结束对话。

Step 4: handle quota and rate limits

步骤4：处理配额和速率限制

On HTTP 
429
or 
402
the free quota is exhausted; the script's error message includes any 
Retry-After
value. Do not retry in a loop. Tell the user the free search quota is used up and guide them to configure a personal API key:
  1. Create a key at 
    https://codexthemes.ai/settings/apikeys
    .
  2. Store it: 
    printf '%s' "<api-key>" | npx tsx scripts/apikey.ts set
    (stdin keeps the key out of shell history; 
    apikey.ts set <key>
    also works).
  3. Re-run the search.
Check the current key state at any time with 
npx tsx scripts/apikey.ts status
; remove a stored key with 
npx tsx scripts/apikey.ts clear
. Never print a full key (scripts only show a masked form), never write it into a project file, and never commit it.
On 
401
/
403
the configured key is invalid or revoked — guide the user to create a fresh key the same way.
当出现HTTP 
429
或
402
状态码时，说明免费配额已用尽；脚本的错误消息会包含
Retry-After
值。切勿循环重试。告知用户免费搜索配额已用完，并引导他们配置个人API密钥：
  1. 在
    https://codexthemes.ai/settings/apikeys
    创建密钥。
  2. 存储密钥：
    printf '%s' "<api-key>" | npx tsx scripts/apikey.ts set
    （通过标准输入可避免密钥出现在shell历史记录中；
    apikey.ts set <key>
    同样有效）。
  3. 重新运行搜索。
可随时使用
npx tsx scripts/apikey.ts status
检查当前密钥状态；使用
npx tsx scripts/apikey.ts clear
删除已存储的密钥。切勿打印完整密钥（脚本仅会显示掩码形式），切勿将其写入项目文件，也切勿提交到版本控制系统。
当出现
401
/
403
状态码时，说明已配置的密钥无效或已被撤销——按照相同方式引导用户创建新密钥。