SuperAPI AI Directory
Partner中文AI newsFavorites
Skillscodex-theme-maker

codex-theme-maker

General & other

View repository

Updated 10-16 09:54

About this skill

Codex Theme Maker — build a Codex skin at the level of the "Ultraman Tiga theme" from scratch

You (the Agent) will turn a concept image or an IP style into acomplete, interactive, toggleablematerialized theme in the Codex desktop app. This document is the complete battle manual: follow the seven phases, and the tools, parameters, and pitfalls of each step have already been smoothed out for you. The baseline is the built-in theme guts-terminal(Ultraman Tiga TPC/GUTS command terminal) — when you are done, your theme should reach the same level.

The final deliverable is not a theme directory, but a .codexskin package(produced in Phase 6) — it is the unified format consumed by the Codex App Manager's gallery, import, and subsequent cloud distribution. A theme that passes acceptance but has not been packaged into .codexskin is considered incomplete.

What counts as "Ultraman Tiga theme level" (acceptance baseline)

  • Materialized rather than color-graded: the background, input console, cards, all icons, brand logo, and button props are all AI-generated bitmap assets; all text is live native DOM (never burn text into assets).
  • Full coverage: the home page, conversation page, settings page, sidebar, right panel, bottom panel, overlay menus, and tooltips — no native style is left uncovered.
  • Light and dark dual mode: automatically switches following the Codex appearance setting, and all text is readable in both modes.
  • Zero breakage: all interactions work normally, with no new scrolling, no layout shift, and no flicker;off one click fully restores the native look.
  • Has surprises: narrative details such as a splash animation and dual-state buttons (e.g., Spark Lens open shell = can send / closed = disabled).

Dependencies (must be confirmed before starting)

  1. Workbench：awesome-codex-skins repository's studio/— the CLI, injector, and runtime are all here, and the reference skin is in the same repository at skins/guts-terminal. Location order: environment variable CODEX_SKINS_REPO → ~/awesome-codex-skins → ask the user for the clone location (git clone https://github.com/Wangnov/awesome-codex-skins). All subsequent node bin/codex-theme.mjs … are executed under <repo>/studio/ ; the skin directory is <repo>/skins/<id>/(the CLI locates it automatically, and it can be overridden with CODEX_SKINS_ROOT ).
  2. Asset generation — choose one: prefer gpt-image-2-skill(open source, includes a magenta-background matting and alpha verification pipeline,node <skill>/scripts/gpt_image_2_skill.cjs --json ...; before starting, check the version according to its runtime freshness rules, then run config inspect、doctor、auth inspect；Provider makes no assumptions: use --provider auto, with global parameters placed before command groups such as images edit / transparent generate ). In the Codex environment, you may also fall back to Codex's built-in image generation capability — the generation quality requirements remain unchanged, but matting/verification must go through this repository's scripts/ Python pipeline on your own.Regardless of which engine is used, the hard asset constraints (magenta background, no text, 2MB limit, alpha verification) remain unchanged.
  3. Runtime environment: macOS, Node ≥ 20 (system node or Codex's bundled Contents/Resources/cua_node/bin/node), official Codex.app (bundle id com.openai.codex), Python3 + Pillow (asset post-processing).

Seven-phase pipeline

Phase 0 — Preflight

doctor pass;node bin/codex-theme.mjs status check workbench status; place concept art in reference/. If there is no concept art, first confirm the style imagery with the user (IP, color scheme, materials, signature props); you may first use gpt-image-2 to generate a concept image for the user to confirm.

Phase 1 — Design breakdown (the most important decision phase)

Break the concept art into two layers, output an "asset list × DOM component mapping table" before starting:

  • Bitmap layer(AI-generated): wall/ambient background, character art, input deck, card screen, icon set (16 functional slots), brand Logo wordmark, signature prop buttons, watermark, small capsule base. For typology and specs, see references/asset-pipeline.md。
  • DOM layer(CSS + decoration layer): all copy, progress bars, status lights, and the contents of the stage/overlay dual decoration layers.
  • The background must belayered(wall cover / character art anchored bottom-right / tabletop drawn with CSS); do not use one large image covering everything—it will drift when the window deforms.

Phase 2 — Asset production

The full workflow (generation → magenta-background chroma keying → alpha normalization → strict validation → optical bbox cropping → WebP → inventory registration) follows references/asset-pipeline.md execution. Key points:bounded concurrency, per-task timeout, observable JSON Events, item-by-item failure summary; if the composition or styling is unsuitable, regenerate; for transparent shadow/margin issues, normalize at the asset layer; do not use CSS to patch different bad bboxes separately; for props, prefer real-object reference images;a single asset data URL must be < 2MB。

Phase 3 — Theme assembly

themes/<id>/：theme.json(schemaVersion 2: colors/strings/assets mapping + codexTheme native theme block) + theme.css(all selectors prefixed with html.codex-theme-studio ) + chrome.html(stage/overlay dual-layer decoration).codexTheme The block lets controls not covered by assets (dropdowns, fonts, accent) also receive the theme—asset-based UI + native theme variables are a combo; neither can be missing. Before writing CSS,read through references/css-recipes.md the DOM map and all recipes; it can save ten rounds of debugging. Three conventions: register the intro asset as the assets "intro" key (runtime plays it accordingly); write the theme's default appearance to codexTheme.appearanceTheme(the CLI writes it into config.toml during the restart flow); both the hero copy and the intro animation must usethat IP's own symbols and rituals(NERV uses its motto, EVA uses launch catapult), do not apply the format of a previous theme.

Phase 4 — Injection iteration

node bin/codex-theme.mjs start --theme <id>   # 首次：启动 Codex(CDP)+守护+原生主题写入
node bin/codex-theme.mjs use <id>             # 每次改完主题文件：热重载
node bin/codex-theme.mjs screenshot /tmp/s.png

Loop: modify → use → screenshot → compare side by side with the concept art → fix. When styles do not take effect, follow css-recipes' "debugging methodology" and use CDP to inspect computed style / cascade / clipping,do not guess. If you changed src/(non-theme files), you must stop + start restart the daemon.

Phase 5 — Full acceptance (only counts as complete if all pass)

  1. verify --screenshot pass; but do not trust only the overall boolean: before screenshotting, wait for #cts-intro to disappear, and assert that the current route is really the target route (during homepage acceptance, .cts-home、.cts-home-shell and the suggestion card exist at the same time).off after doingattribute-level zero residue(class/style/decoration layers + [data-cts-glyph]/[data-cts-icon]/[data-cts-logo] counts all 0);use Restore; CDP sends Page.reload then the daemon automatically reinjects.
  2. Page-by-page walkthrough: home page, chat page (including the message action row not being blocked), settings page,right panel expanded state, chat floating window, dropdown menu, tooltip—each of the two appearance modes once (appearance is switched on the settings page using CDP mouse events).
  3. Interaction hard metrics:composer.scrollWidth-clientWidth === 0 && scrollHeight-clientHeight === 0; number of scrollable containers on the home page is 0 (criterion: check computed overflow + actual scrollability, not the diff value); the button boxes of the four suggestion cards and thevisible armored borderare the same size; the visible area of the send prop must not intersect with adjacent buttons such as model, approval, attachment, etc.; no flicker when opening dropdowns/popovers; all capsule/button text is legible and clickable; the native fixed top bar is still fixed (y=0, no duplicate placeholder).
  4. Screenshots at two window resize sizes (real resize or CDP Emulation.setDeviceMetricsOverride): the character art is not cropped, the counter surface does not drift, the cards are not covered by the counter surface.
  5. During iteration the user may be using the app at the same time—all DOM assertions and screenshots are collected atomically at the same instant (see css-recipes debugging methodology 7/8).

Phase 6 — Delivery packaging (output .codexskin）

After Phase 5 fully passes, turn the theme into a distributable deliverable. Three steps:

  1. Complete delivery metadata（theme.json, all compatible with schemaVersion 2):
    • version: the theme's own semver, first version "1.0.0", bump on every substantive change thereafter;
    • author: creator (string or { "name", "url" }）；
    • codexVerified: the Codex version at acceptance time, read using /usr/bin/defaults read /Applications/Codex.app/Contents/Info.plist CFBundleShortVersionString ,do not fill in manually；
    • appearance："dark" | "light" | "dual"（codexTheme carrying both dark+light means dual）；
    • license: AI-generated IP-style assets are written as "personal-use"by default—themes with unclear copyrightmust notbe publicly distributed.
  2. Standard preview screenshot: first use CDP to tidy the interface into the standard state—the sidebar's projects, tasks, and pinned section are all collapsed(locate DOM controls per the css-recipes sidebar map), navigate to the home page, wait for the intro animation to finish; then: 
    node bin/codex-theme.mjs preview-shot <id>              # → previews/home.webp（封面，1280×800 WebP）
# 推荐再补一张对话页（先手动/CDP 进入一个对话）：
node bin/codex-theme.mjs preview-shot <id> --name chat
    The command automatically asserts the home route and that the intro has disappeared, captures at 2× then scales to 1280×800, writes previews/ and registers it into theme.json.previews（home fixed as the cover). A single image over 500KB triggers a warning—use Pillow to re-save at lower quality.
  3. Packaging： 
    node bin/codex-theme.mjs pack <id>                      # → dist/<id>-<version>.codexskin
    pack is a strict quality gate: directory name matches id,version/codexVerified/previews complete, preview file exists and ≤1MB; if any is not satisfied, exit code 2 and list the problems. The product zip root is the package content (theme.json at the root), and the Manager consumes it via the "Import Theme" button / drag-and-drop .codexskin .

Definition of Delivery (DoD)：pack Successfully produce .codexskin + report to the user the artifact path, version, and preview image list.

Hard constraints (violating any one means failure)

  • Do not modify/unpack/replace app.asar or any application file; CDP only listens on 127.0.0.1.
  • No text/numbers/logo text of any kind on assets (brand artistic-word Logo assets are the only exception—the text itself is the design object).
  • Everything is reversible: all selectors are attached html.codex-theme-studio; decorative elements are placed only #cts-stage / #cts-chrome；config.toml automatic backup before writing (built into the CLI).
  • Decoration layer pointer-events: none, never intercept interactions.
  • Assets are always inlined into the stylesheet as WebP + data URL (blob URLs forbidden); a single asset < 2MB.
  • Every transparent source PNG must, before being admitted to the repository, transparent verify --strict pass: real alpha, transparent RGB scrubbed, transparent margin left at the edges, matte residue checked; assets in the same group must also have a contact sheet generated at the actual rendered size for optical size comparison.
  • config.toml can only be written while Codex is not running (the CLI's start flow already handles this; do not bypass it manually).

Reference files

  • references/asset-pipeline.md — Asset production manual: typology, spec tables, prompt template library, cutout/post-processing/9-slice measurement, quality gates.
  • references/css-recipes.md — Injection-side technical manual: Codex DOM map, core mechanisms, per-component recipes, dark variants, iron rules and debugging methodology.Must-read before writing any CSS.
  • references/reuse-and-validation.md — Must-read when making a new theme based on an existing theme: keep/replace boundaries, cleanup order to prevent old IP contamination, prompt inheritance boundaries, shared live isolation, evidence grading.
  • scripts/normalize_alpha.py — Transparent PNG normalization: clear low alpha, scrub transparent RGB, crop and pad margin.
  • scripts/asset_contact_sheet.py — Generate grouped asset contact sheets according to the real CSS render box, and output alpha/optical bbox data.
  • scripts/verify-alpha.py — Local review implementation of the alpha gate.
  • scripts/audit-theme.mjs — Pre-delivery static audit: schema/reference integrity/size/2MB limit/CSS bracket balance/--forbid old-word scan.forbid word list = ids, character names, mecha names, exclusive asset keys of all other themes under themes/(hand-picking per theme will miss things — the lesson of kaworu missing guts in the first round); run it for every theme before delivery.