# Spicetify Skills

> Author and debug Spicetify themes, extensions, custom apps, and @spicemod/creator (spicetify-creator / sc / sanoojes spicetify-creator) projects, including Marketplace-compatible extensions. Use whenever the task involves Spicetify development, color.ini/user.css themes, Extensions/*.js, CustomApps, @spicemod/creator TypeScript/React/SCSS builds (create/dev/build -a), or the Spicetify API Wrapper — Spicetify.Player, Spicetify.Platform, Spicetify.CosmosAsync, Spicetify.GraphQL, Spicetify.URI, Spicetify.Keyboard, Spicetify.LocalStorage, Spicetify.ContextMenu, Spicetify.Topbar, Spicetify.Playbar, React components, panels, or related TypeScript types. Prefer @spicemod/creator over deprecated create-spicetify-app / FlafyDev Spicetify Creator. Prefer TypeScript over JavaScript for new work. Prefer this skill over guessing APIs or scraping spicetify.app.

- Skill: `jochemkuipers/spicetify-skills` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add jochemkuipers/spicetify-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jochemkuipers/spicetify-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: JochemKuipers (https://skillmd.com/u/jochemkuipers)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jochemkuipers/spicetify-skills

---


# Spicetify Development

Learn how to create themes, extensions, and custom apps for Spicetify. This skill is a **router**: keep this file for orientation, then open the matching `references/*.md` file for full docs, signatures, and examples (copied from the official Spicetify docs).

## Conventions

- **Prefer TypeScript over JavaScript** for all new extensions, custom apps, themes-with-JS, and `@spicemod/creator` projects (`.ts` / `.tsx`, `spice.config.ts`, `--language ts`).
- Use plain JavaScript only when maintaining an existing JS codebase or the user explicitly asks for JS.
- Prefer `@spicemod/creator` for multi-file / React / typed work instead of hand-rolled single `.js` files.

## Four development paths

| Path                  | What you ship                                                             | Start here                                                         |
| --------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Theme**             | `color.ini` + `user.css` (+ optional `theme.js` / assets)                 | [references/themes.md](references/themes.md)                       |
| **Extension**         | A JS/TS file that runs with Spotify (prefer TypeScript via Creator)       | [references/extensions.md](references/extensions.md)               |
| **Custom app**        | Sidebar React page (`index.js` + `manifest.json`, or Creator + TS)        | [references/custom-apps.md](references/custom-apps.md)             |
| **@spicemod/creator** | TS/React/SCSS project via `@spicemod/creator` (`create` / `dev` / `build -a`) | [references/spicetify-creator.md](references/spicetify-creator.md) |

Build/watch tooling, React DevTools, and Spotify CLI flags: [references/build-tooling.md](references/build-tooling.md).

API Wrapper (global `Spicetify` object): start at [references/api-overview.md](references/api-overview.md), then the method/class/function/property/type refs below.

---

## Theme — project structure

```text
~/.config/spicetify/Themes/       # Linux/macOS
%appdata%\spicetify\Themes\       # Windows
└── MyTheme/
    ├── color.ini                 # Required: color definitions
    ├── user.css                  # Required: custom CSS rules
    ├── theme.js                  # Optional: theme-specific JavaScript
    └── assets/                   # Optional: images, fonts, etc.
```

Required: `color.ini` (CSS variables) and `user.css`. Home-directory themes override executable-directory themes with the same name.

**Read:** [references/themes.md](references/themes.md) for color formats (hex, decimal, env/`xrdb`), scheme sections, and CSS guidance.

---

## Extension — project structure

```text
~/.config/spicetify/Extensions/   # Linux/macOS
%appdata%\spicetify\Extensions\   # Windows
├── myExtension.js
└── ...
```

Minimal pattern: wait until `Spicetify.Player` / `Spicetify.Platform` exist, then run. Enable with:

```bash
spicetify config extensions myExtension.js
spicetify apply
```

Key namespaces: `Spicetify.Player`, `Platform`, `CosmosAsync`, `URI`, `React` / `ReactDOM`, `Topbar`, `Playbar`, `ContextMenu`.

For multi-file work, TypeScript, or npm packages, use `@spicemod/creator` with `--language ts` instead of a raw single `.js` file.

**Read:** [references/extensions.md](references/extensions.md) (includes JS/NPM modules).

---

## Custom app — project structure

```text
~/.config/spicetify/CustomApps/   # Linux/macOS
%appdata%\spicetify\CustomApps\   # Windows
└── my-app/
    ├── index.js                  # Required: main entry with render()
    ├── manifest.json             # Required: app metadata and icons
    ├── style.css                 # Optional
    └── src/                      # Optional subfiles
```

`manifest.json` keys: `name`, `icon`, `active-icon`, optional `subfiles`, optional `subfiles_extension`. Vanilla custom apps use `Spicetify.React` / `createElement` (no JSX unless using Creator).

**Read:** [references/custom-apps.md](references/custom-apps.md).

---

## @spicemod/creator — project structure

The old FlafyDev Spicetify Creator / `create-spicetify-app` is **deprecated**. Use the maintained toolchain:

```bash
npx @spicemod/creator create
# or: bunx @spicemod/creator create
```

Repo: [sanoojes/spicetify-creator](https://github.com/sanoojes/spicetify-creator). Templates: `extension`, `theme`, `custom-app`. Default to **TypeScript** (`--language ts`) and React when UI is involved; use JS/vanilla only if requested.

Typical layout:

```text
my-app/
  package.json
  spice.config.ts       # defineConfig from @spicemod/creator
  tsconfig.json         # when using TypeScript
  src/
    app.tsx             # extension/theme entry, or custom-app page
    extension/          # custom-app companion extension (when applicable)
    ...
```

- **Extension:** `src/app.*` runs on Spotify startup.
- **Theme:** JS+CSS entries via `spice.config` (see Creator reference).
- **Custom app:** `src/app.*` page component + `src/extension/` + icons/SCSS modules.

Scripts: `dev` (HMR), `build` (use `-a` to apply to Spicetify), `update-types`, `clean-spice`.

**Read:** [references/spicetify-creator.md](references/spicetify-creator.md).

---

## Build tooling

Open [references/build-tooling.md](references/build-tooling.md) when you need:

- Compiling / watch workflows for extensions and apps
- React DevTools setup inside Spotify
- Spotify CLI flags useful for Spicetify development

---

## API Wrapper — which reference to open

Access `Spicetify` in DevTools, extensions, or `window.top.Spicetify` from an iframe app.

| Task                                                                                                                 | Open                                                         |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| What the wrapper is; exposed modules (`React`, `ReactDOM`, `ReactHook`, Tippy, …)                                    | [references/api-overview.md](references/api-overview.md)     |
| `Platform`, `CosmosAsync`, `GraphQL`, `Player`, `Keyboard`, `LocalStorage`, `URI`, `PopupModal`, `Panel`, `AppTitle` | [references/api-methods.md](references/api-methods.md)       |
| `ContextMenu`, `Menu`, `Topbar`, `Playbar`                                                                           | [references/api-classes.md](references/api-classes.md)       |
| `addToQueue`, `removeFromQueue`, `colorExtractor`, `getAudioData`, `showNotification`, `getFontStyle`                | [references/api-functions.md](references/api-functions.md)   |
| `Config`, `SVGIcons`, `Queue`, `ReactComponent`, `ReactHook`, `TippyProps`                                           | [references/api-properties.md](references/api-properties.md) |
| Shared TS types (`PlayerState`, CosmosAsync bodies, React component props, GraphQL `Query`, …)                       | [references/api-types.md](references/api-types.md)           |

Do **not** invent method signatures — copy from these reference files.

---

## Agent workflow

1. Identify the path (theme / extension / custom app / `@spicemod/creator`) and open that reference.
2. Default to **TypeScript** (and `@spicemod/creator` when scaffolding); use JavaScript only if the project already is JS or the user asks for it.
3. For any `Spicetify.*` API use, open the matching API reference and use signatures/examples verbatim.
4. After Creator code changes, prefer `build -a` / `npm run build -- -a` (or `dev` while iterating); otherwise remind the user of `spicetify apply`.
5. When the user mentions Spicetify Creator, `create-spicetify-app`, or `spcr-*`, steer new work to `@spicemod/creator` — see [references/spicetify-creator.md](references/spicetify-creator.md).