spicetify-agent-skill

/spicetify

/spicetify is a dry-run-first local operator for Spicetify workflows. It exposes a compact AI Skill plus an installable Python CLI, spicetify-agent, that plans, audits, snapshots, applies, verifies, reports, and rolls back local Spicetify customization state without granting arbitrary shell access.

The executable is intentionally named spicetify-agent so it does not shadow the real spicetify CLI.

Current release: v0.1.0.

Install and run

Install the portable Agent Skill into supported harnesses from this checkout:

npx skills add <repo-checkout> --skill spicetify -y -g -a antigravity claude-code codex crush cursor gemini-cli github-copilot opencode

Install from the tagged public release:

npx skills add github:wyattowalsh/[email protected] --skill spicetify -y -g -a antigravity claude-code codex crush cursor gemini-cli github-copilot opencode

The installed skill is self-contained under skills/spicetify/. It does not bundle the official Spicetify CLI. Users must install upstream Spicetify separately, and agents must not run installer scripts or package-manager commands without explicit approval.

From this checkout:

PYTHONPATH=skills/spicetify/scripts python3 -m spicetify_agent --help
PYTHONPATH=skills/spicetify/scripts python3 -m spicetify_agent plan "/spicetify Spotify updated and Spicetify broke"
PYTHONPATH=skills/spicetify/scripts python3 -m spicetify_agent research "find a playlist sorting extension"

Local package commands:

uv run spicetify-agent --help
uvx --from . spicetify-agent --help
uv build
pip install dist/*.whl
spicetify-agent --help

Run the helper from the tagged release:

uvx --from git+https://github.com/wyattowalsh/[email protected] spicetify-agent --help

Safety model

• All potentially mutating requests produce a dry-run plan first.
• The public skill interface is prompt-first: /spicetify <prompt input>.
• Existing plugin, extension, theme, custom app, snippet, and Marketplace research is read-only and never installation approval.
• Mutating plans include policy, plan hash, snapshot requirement, verification, report, and rollback metadata.
• Execution uses a central argv-only runner with shell=False.
• Real Spicetify execution is blocked in CI and disabled locally unless explicitly opted in.
• Tests use fake Spicetify binaries and temp roots only.
• Third-party code is staged, audited, hashed, and provenance-locked before enablement.
• Installer scripts, package-manager commands, permission changes, remote debugging, screenshots, DevTools logs, network fetches, publishing, and third-party build scripts remain approval-gated.

Main surfaces

• skills/spicetify/scripts/ — installed-skill Python runtime and CLI.
• skills/spicetify/ — compact /spicetify Skill router and references.
• skills/spicetify/assets/schemas/ — skill-local JSON contracts for plans, runs, reports, policy, provenance, privacy, snapshots, docs, and fixtures.
• openspec/changes/add-spicetify-skill/ — behavior requirements and task graph.
• docs/content/docs/ — durable documentation, generated references, workflows, modes, and validation guidance.
• docs/ — isolated Fumadocs + shadcn/ui-compatible documentation app.
• tests/ — fake-environment, policy, command, mode, audit, privacy, snapshot, CLI, and bundle validation tests.
• CHANGELOG.md and RELEASE.md — release notes and the validation checklist for v0.1.0.

Prompt-first routing

The user-facing interface is natural language:

/spicetify <prompt input>

The runtime infers intent, asset kind, source kind, risk, confidence, and the safest next artifact. Internal modes remain useful for traces, reports, and tests, but users should not need to select them up front.

Examples:

• /spicetify find an extension for playlist sorting returns a read-only research report.
• /spicetify is this GitHub theme safe? returns an audit-oriented report.
• /spicetify safely install this Marketplace theme returns a source-pin/stage/audit dry-run plan that requires confirmation before mutation.
• /spicetify make a small extension that hides podcasts returns a generated-local scaffold plan with audit and dry-run gates.

Research existing plugins, extensions, themes, custom apps, snippets, and Marketplace items as metadata only. GitHub topics, Marketplace presence, README claims, stars, and screenshots never imply trust or install approval.

Local filesystem audit/inspect targets must be staged under an approved asset root. The helper CLI defaults relative --target paths to the current working directory and accepts explicit staged roots with --asset-root; it rejects symlinks, root escapes, secret-like names, and real Spotify/Spicetify state paths.

Validation

Safe checks that do not run real Spotify or Spicetify: