Download a published theme's portable package from codexthemes.ai and unpack its source files into . This skill is standalone: its TypeScript scripts own the download, validation, and local installation. It does not search the gallery (codex-theme-finder), create themes (codex-theme-creator), or submit them (codex-theme-submitter). Applying belongs to codex-theme-switcher — but a successful install chains directly into it (Step 4); installing files and stopping is not a finished job. The only required local tools are Node.js 20+ and .

Read before diagnosing an unexpected API response or changing endpoint behavior. Run all commands from the installed skill directory.

Resolve what to install to a theme id — the lowercase slug from codex-theme-finder results or from a URL. The script accepts either form. If the user only describes a style without naming a theme, find candidates with codex-theme-finder first instead of guessing ids.

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

Downloads work without any API key inside a free anonymous quota, so do not demand a key up front. When a key is already configured ( environment variable or ), the script sends it automatically for higher limits.

The script validates the downloaded package (format, schema version, matching theme id, safe relative filenames, ≤30 MB) before writing anything, then unpacks , the stylesheet, the artwork, and the readme into . It refuses to overwrite an existing non-empty theme directory; pass only after the user confirms replacing their local copy — the directory may hold their own edits.

Updating an installed theme: published themes are updated in place on codexthemes.ai, so when the user asks to update, upgrade, or re-download a theme they already installed, re-run the install with — the update request itself is the confirmation, unless the local copy holds edits the user made (then warn first). After the files land, continue into Step 4 so the running app actually switches to the new version; a hot swap of the same theme id re-injects the updated CSS.

On HTTP or the free quota is exhausted; the script's error message includes any value. Do not retry in a loop. Tell the user the free download quota is used up and guide them to configure a personal API key:

Check the current key state with ; remove a stored key with . Never print a full key (scripts only show a masked form), never write it into a project file, and never commit it.

On / the configured key is invalid or revoked — guide the user to create a fresh key the same way. On the theme id does not exist; re-check the id with codex-theme-finder.

An install request means the user wants to see the theme in Codex, not merely store its files. Report the installed path (), the theme version, and the files written — then continue directly into activation with codex-theme-switcher. If codex-theme-switcher is not installed, bootstrap it the same way this skill was bootstrapped ().

Never end the conversation with only "files installed, not applied" and no actionable next step, and never claim the theme is active until the switcher's reports .