codex-theme-finder — Claude Code skill: what it does, how to install
codex-theme-finder queries published themes on codexthemes.ai directly from the coding agent. Works out of the box with free anonymous quotas.
Apache-2.0 241 installs ★ 7 updated 2026-07-21
npx skills add codexthemes/skills --skill codex-theme-finder -a claude-codeWhat codex-theme-finder does
The skill connects your AI assistant to the codexthemes.ai catalog. It converts conversational requests into keywords, query filters, and sort orders (popular, newest, name). Standalone TypeScript utilities handle catalog querying and credential persistence. Local dependencies are minimal: Node.js 20+ and npx.
Matches come in three formats: ready .codex-theme bundles, zip archives requiring manual downloads, and visual skins. The skill downloads candidate previews to local temporary files, preventing broken chat embeds, and surfaces identifiers alongside detail page links.
Finding themes is its only role. The skill does not bundle themes or edit local settings, so turning a discovered theme into an active design requires handing off the id to codex-theme-installer.
What it helps with
- search published Codex interface themes by aesthetic or topic
- preview theme images locally before applying changes
- store CodexThemes API tokens to raise search rate limits
- identify one-click installable
.codex-themepackages
Example prompts for the agent
- Find light pastel themes on codexthemes.ai
- Search for popular cyberpunk Codex themes
- Configure my codexthemes API key
How to install codex-theme-finder
1Skills CLI (Vercel)
npx skills add codexthemes/skills --skill codex-theme-finder -a claude-code2Manually: put the files in place
~/.claude/skills/codex-theme-finder/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/codex-theme-finder/
1Skills CLI (Vercel)
npx skills add codexthemes/skills --skill codex-theme-finder -a codex2Manually: put the files in place
.agents/skills/codex-theme-finder/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add codexthemes/skills --skill codex-theme-finder -a cursor2Manually: put the files in place
.cursor/skills/codex-theme-finder/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install codexthemes/skills skills/codex-theme-finder2Manually: put the files in place
.github/skills/codex-theme-finder/SKILL.md1Skills CLI (Vercel)
npx skills add codexthemes/skills --skill codex-theme-finder -a gemini-cli2Platform CLI
gemini skills install https://github.com/codexthemes/skills --path skills/codex-theme-finderManually: put the files in place
.devin/skills/codex-theme-finder/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add codexthemes/skills --skill codex-theme-finder -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about codex-theme-finder
How to install codex-theme-finder in Claude Code?
Run npx skills add codexthemes/skills --skill codex-theme-finder -a claude-code in your terminal.
What does codex-theme-finder do?
It queries the codexthemes.ai catalog API, renders local image previews, and provides theme IDs for installer agents.
Is an API token mandatory?
No, searches operate anonymously under a free quota. A key from https://codexthemes.ai/settings/apikeys is needed only after encountering HTTP 429 or 402 limits.
Source text
SKILL.md · Apache-2.0
--- name: codex-theme-finder description: Search and browse published Codex themes on codexthemes.ai through the themes API, anonymously within a free quota or with a CodexThemes API key for higher limits. Use when a user asks to find, search, browse, list, or discover Codex themes on CodexThemes, wants theme recommendations from the gallery, or hits a search rate limit and needs API key guidance. --- # Find Codex themes on CodexThemes 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. ## Step 1: search 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. ## Step 2: present the results 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. ## Step 3: offer installation — never end at the list 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. ## Step 4: handle quota and rate limits 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.
© codexthemes · Apache-2.0 · codexthemes/skills