---
name: velo-theme-authoring
description: Author, review, pack, and publish Velo Theme Plugins (installable palettes). Use when writing 主题, creating a theme pack, editing theme tokens, adding a community theme, validating targets:["theme"], or converting a Velo UI palette into an installable .vplug/.vplugz. Requires Velo Desktop 0.2.0+. Theme Plugins are separate from selection plugins and must not contain actions, WASM, network, secrets, scripts, or arbitrary CSS.
---

# Velo Theme Plugin Authoring

> If the request is about selection-bar actions, PopClip, or `targets: ["selection"]`, stop and load `../velo-plugin-authoring/SKILL.md` instead.

Velo Theme Plugins are **signed design-token packs** for the Appearance page. They are not CSS/JS themes and cannot change UI structure, open windows, run WASM, or call the network.

Requires **Velo Desktop 0.2.0+** (macOS). `min_host_version` must be `0.2.0` or newer. `api_version` stays `1.0.0`. Older `0.1.0` hosts reject theme packs.

Public URL: `https://velo.var.li/skills/velo-theme-authoring/SKILL.md`
Catalog: `https://velo.var.li/skills/index.json`
Human guide: `https://velo.var.li/plugin-guide.html` (repo: `docs/THEME_PLUGIN_AUTHORING.md`)
Contract: `schemas/plugin-v2.schema.json`, `docs/PLUGIN_DEVELOPMENT.md`.

Other developers: copy this whole folder (including `references/`) into `.agents/skills/velo-theme-authoring/`.

## Load references as needed

- Unsure about type, version, or forbidden fields → [references/contract.md](references/contract.md)
- Filling `theme.tokens` → [references/tokens.md](references/tokens.md)
- Packing or community submit → [references/publish.md](references/publish.md)
- Reviewing a failing pack → [references/pitfalls.md](references/pitfalls.md)

If a field is not in the schema, **do not invent it**.

## Workflow

1. Restate the job as **one Theme Plugin, imported from Appearance, token replacement only**.
2. Confirm the user is targeting **Velo 0.2.0+**. Do not claim compatibility with 0.1.0.
3. Choose a reverse-DNS id (`com.example.theme.paper`). Never use `velo` / `velo.*` unless shipping an official pack with an out-of-repo official key.
4. Scaffold:

```bash
./scripts/install-plugin-cli.sh
velo-plugin init --theme ./the-theme com.example.theme.paper "Paper"
velo-plugin validate ./the-theme
velo-plugin pack ./the-theme ./the-theme.vplugz
```

5. Set `schema: 2`, `targets: ["theme"]`, `permissions: []`, `actions: []`, `min_host_version: "0.2.0"`.
6. Provide `theme.appearance`, exactly three safe `swatch` colors, and at least the 16 required tokens.
7. Tell the user to import from **Appearance**, not Selection. Do not run tests/builds unless this turn authorized them.

## Hard no

- Selection actions, empty noop actions, WASM, Options, Secrets, Network, Shell, JS, WASI
- Raw CSS rules, selectors, `url()`, `var()`, fonts, images, remote assets
- `min_host_version` below `0.2.0`
- In-app catalog / plugin-owned windows
- Mapping a community theme onto built-in `light` / `dark` / `system`

## Deliver

Return: plugin id, **required app version (0.2.0+)**, files to write, validate/pack commands, and import steps (Velo → Appearance → Import). If publishing, list attest steps without uploading keys.