Cc theme dev
Author, validate, and locally install Claude Code themes in the claude-themes marketplace — scaffold a new family from a canonical palette, catch tokens that render silently wrong, and symlink themes into the Claude Code themes directory for live testing.From its SKILL.md
npx -y skills add matcra587/claude-themes --skill cc-theme-devAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
SKILL.md
4.9 KB, as published. Nobody here has run it
Theme Development
Author, validate, and locally install themes for the claude-themes
marketplace. Scope: this repository's plugins/<family>/themes/*.json files
validated against schemas/theme.schema.json.
Core Concepts
- A theme file has three keys:
name,base, andoverrides. Tokens absent fromoverridesfall through to thebasepreset at runtime. schemas/theme.schema.jsonis the authority on token names and color value formats.
Current Environment
- uv: !
command -v uv >/dev/null && echo installed || echo "NOT INSTALLED"
If uv reads NOT INSTALLED, do NOT run the uv run commands; use the jq
fallback under Validating.
Authoring a New Family
- Source the palette before writing any token value — an upstream GitHub
repo, official spec, or colorscheme file, fetched with
gh api -H "Accept: application/vnd.github.raw". Never invent palette values. - Scaffold using an existing family as the structural reference —
plugins/catppuccin/shows the layout:themes/<family>-<variant>.json(plus a-ansi.jsonsibling),.claude-plugin/plugin.json, and a README. Register the family in.claude-plugin/marketplace.jsonand the root README table. - Map tokens per
CONTRIBUTING.md(Semantic mapping, Shimmer derivation) covering the full token set. For*-ansi.jsonfiles, follow.claude/rules/ansi-variants.md. When the palette documents no role for a token family (no orange forclaude, no violet forautoAccept...), put the mapping choice to the user as a question before writing values instead of silently picking one. - Validate, then install to test live (both below).
NEVER
- NEVER trust a theme because it renders. Unknown or misspelled tokens are silently ignored at runtime — a typo'd override is an invisible no-op. Validation is the only thing that catches it.
- NEVER copy a full preset into
overrides. Tokens added by future Claude Code versions then never fall through. Override only what differs. - NEVER swap
claudeandpermission. Brand orange and blue must differ in hue family — every original community theme shipped this swap. - NEVER collapse
subtle,inactive, andinactiveShimmerto one value. They are a three-tier dim hierarchy: comment-grade muted, darker disabled, mid-tone respectively.
Validating a Theme
All commands run from the repository root. Validation is owned by
scripts/schema-validation.py — the same script CI runs, so local results
match CI exactly (uv resolves its jsonschema dependency from the script's
inline metadata):
uv run scripts/schema-validation.py --changed path/to/theme.json
uv run scripts/schema-validation.py --all # every theme in the repo
Failures print as ::error file=... lines and the exit code is non-zero.
To list candidate files: git status --porcelain -- 'plugins/*/themes/*.json'.
Fallback without uv (syntax + token names only, no schema checks):
python3 -m json.tool theme.json > /dev/null # syntax
jq -r '.overrides | keys[]' theme.json # tokens, eyeball against schema
Installing to Test Locally
scripts/themes.py symlinks marketplace themes into the Claude Code themes
directory (~/.claude/themes, or $CLAUDE_CONFIG_DIR/themes), creating it if
needed. Symlinks keep the installed theme in sync with the file being edited,
so a /theme switch shows edits immediately.
uv run scripts/themes.py install <family> # symlink a family's themes
uv run scripts/themes.py install <family> --dry-run # preview
uv run scripts/themes.py list # show installed themes
uv run scripts/themes.py uninstall <family> # remove them
Uninstall only removes symlinks resolving back into this repo — a hand-written
theme or a link pointing elsewhere is never touched, and install guards those
behind --force. After installing, tell the user to run /theme and pick the
family to see it live.
Resolving Effective Colors
Resolving a theme to its effective palette (base preset merged with overrides)
needs the built-in preset values, which live in the private cc-theme-presets
skill. Use that skill's resolver when override coverage or fall-through
inspection is needed.