Vocabloot Deck Kit

View saved version →

---
name: deck-check
description: Validate a Vocabloot deck folder before packing: schema, language and localization alignment, token offsets and coverage, sticker references and decisions, blocking flags; renders an app-like preview. Use before /deck-pack, when a creator asks whether a deck is ready, correct or complete, or says /deck-check.
license: MIT
compatibility: Requires Node 22 and the kit's scripts (npm install in the kit folder); network access to vocabloot.com for the language registry, with an offline snapshot fallback.
---

# /deck-check

**Show your work.** This is step 4 of 6. Say so before the command. Show the preview: render `review/preview.html` (a screenshot or an inline render where the host can), otherwise show the first three cards as text with their stickers displayed. Then the problems, if any, with the card named, or "ready to pack".

Commands below run from the kit's root, the folder two levels above this file (`<kit>/skills/<this skill>/SKILL.md`); from anywhere else, prefix `scripts/` with that path. If a script answers that dependencies are not installed, run the `npm install` it prints.

```bash
node scripts/check.mjs <deck-folder>
```

It prints every problem with the card key in front, or "ready to pack". It also writes `review/preview.html`: the deck as the app and vocabloot.com/decks will show it, one card per tile, sentences with hover-to-see meanings. Open it with the creator and scroll through all of it together; this is the last look before the file exists.

If there are problems, route each one: a token or sentence problem goes back to `/deck-text --refresh "<word>"`; a sticker problem goes back to `/deck-stickers`; a `deck.json` problem (name, description, author) can be edited directly in `deck.json`. Never edit `cards.json` or the localization by hand.

Referenced files: 1

View saved version →

---
name: deck-create
description: Start a Vocabloot deck from a conversation: asks which language the creator speaks and which they are learning, the topic, how many words, the level, words to include or avoid; checks the pair against the Vocabloot app's live language registry; scaffolds the deck folder and has you propose the word list. Use when someone wants to make, start or build a Vocabloot deck, a vocabulary deck, a word list or flashcards for a language, or says /deck-create.
license: MIT
compatibility: Requires Node 22 and the kit's scripts (npm install in the kit folder); network access to vocabloot.com for the language registry, with an offline snapshot fallback.
---

# /deck-create

**Show your work.** This is step 1 of 6. Say so before the first command ("Step 1 of 6: creating the deck folder and proposing the words") and end the step with the list itself, not a summary of it. One deck per run: if the creator asks for several decks, make them one after another, and show each one finished before starting the next. Never work in silence for more than one command; say what is happening between commands.

Commands below run from the kit's root, the folder two levels above this file (`<kit>/skills/<this skill>/SKILL.md`); from anywhere else, prefix `scripts/` with that path. If a script answers that dependencies are not installed, run the `npm install` it prints.

You are starting a Vocabloot deck for a creator. Ask, one at a time, and keep each question to one line:

1. **"Which language do you speak?"** (the known language: translations and explanations will be in it). Say "I speak" in your wording; never assume a native language.
2. **"Which language are you learning?"** (the learning language: headwords, pronunciation, example sentences).
3. **"What is the deck about?"** (the topic, a few words: "greetings", "at the bakery", "my apartment").
4. **"How many words?"** (suggest 20 for a first deck; 5 to 200).
5. **"Which level?"** (A1 to C2; suggest A1 for beginners).
6. **"Any words you want in, or want to avoid?"** (optional).

Then run:

```bash
node scripts/create.mjs --known "<answer 1>" --learning "<answer 2>" --topic "<answer 3>" --count <answer 4> --level <answer 5> --include "<in>" --avoid "<avoid>" --author "<the creator's name, or Anonymous>" --out <where they want the deck folder>
```

The script checks the pair against the app's registry at `https://vocabloot.com/api/capabilities`. If it refuses a language, show its message verbatim and ask again with the languages it lists; never work around it and never promise a language or a pair the registry does not offer. If "English" is ambiguous, the script picks English (US); say so and offer English (UK).

The script scaffolds the folder and, unless a key is configured, leaves one request for you: `work/words/proposal.request.md`. **You propose the words**: read the request, write the list as JSON to the answer file it names (exactly the schema at the end of the request, nothing else), and run the same command again. It then prints the list.

Show the proposed word list exactly as printed and ask: **"Keep this list, or change anything?"** Apply changes by editing `words.json` (add, remove, rename entries; keep `include: true`), then show the list again. Do not move on until the creator says the list is right. Then say the next step is `/deck-text`.

Needs: Node 22. No API key: you are the model. (With `OPENAI_API_KEY` set the script asks OpenAI instead; `--agent` keeps it on you.)

Referenced files: 1

View saved version →

---
name: deck-pack
description: Pack an approved Vocabloot deck folder into a .vlbackup with the app's own codec; refuses with the card named while any check fails. Use when a checked deck should become the file the app opens, or when the creator says /deck-pack, export the deck, or make the file.
license: MIT
compatibility: Requires Node 22 and the kit's scripts (npm install in the kit folder); network access to vocabloot.com for the language registry, with an offline snapshot fallback.
---

# /deck-pack

**Show your work.** This is step 5 of 6. Say so before the command, then post the result line (cards, stickers, size, SHA-256) and offer the file itself where the host can attach or download it, not only its path.

Commands below run from the kit's root, the folder two levels above this file (`<kit>/skills/<this skill>/SKILL.md`); from anywhere else, prefix `scripts/` with that path. If a script answers that dependencies are not installed, run the `npm install` it prints.

```bash
node scripts/pack.mjs <deck-folder>
```

The packer runs every check first and refuses with the reasons if any fail; there is no override. On success it prints the card and sticker counts, the file's SHA-256 and the path (`<deck-folder>/<deckId>.vlbackup`).

The packer is the Vocabloot app's own codec compiled to JavaScript (`packer/`, built from the app's `shared/format` module); the file it writes is the same format the app exports. Tell the creator the file is ready and hand over to `/deck-publish` for how to open it.

Referenced files: 1

View saved version →

---
name: deck-publish
description: Explain how to open a packed Vocabloot deck (.vlbackup) in the app on iPhone or Android and what a card shows there; publishing to the Vocabloot community is a future capability. Use after /deck-pack, or when a creator asks how to install, import, share or publish a deck, or says /deck-publish.
license: MIT
compatibility: Requires Node 22 and the kit's scripts (npm install in the kit folder); network access to vocabloot.com for the language registry, with an offline snapshot fallback.
---

# /deck-publish

**Show your work.** This is step 6 of 6. Say so, then the three points below, in the creator's words if they asked in another language.

Tell the creator, in this order:

1. **Get the file onto the phone.** iPhone: AirDrop it, mail it to yourself, or save it to Files. Android: copy or download it.
2. **Open it with Vocabloot.** Tap the `.vlbackup` file and choose Vocabloot when asked. The words merge into the wordbook; nothing already there is touched, and opening the same file twice adds nothing.
3. **Look at a card.** The word detail shows the sticker, the headword, its meaning, the pronunciation, the part of speech, and the two sentences; tapping a word in a sentence shows its meaning.

Publishing the deck for everyone on vocabloot.com/community is not available yet; when it is, this skill will point at it. Until then, sharing the file directly is sharing the deck.

Referenced files: 1

View saved version →

---
name: deck-stickers
description: Decide which cards get a sticker (a picture idea per card: a rising sun for Guten Morgen), write provider-agnostic sticker prompts, take images made with any tool or generate them with the creator's own OpenAI key, run mechanical checks, look at every image yourself, render a contact sheet, and record approve, reject or defer decisions; never regenerates an approved sticker unless asked. Use after /deck-text, when a deck needs images, stickers or pictures, or when the creator says /deck-stickers.
license: MIT
compatibility: Requires Node 22 and the kit's scripts (npm install in the kit folder); network access to vocabloot.com for the language registry, with an offline snapshot fallback.
---

# /deck-stickers

**Show your work.** This is step 3 of 6. Say so before the first command. Every image goes into the chat the moment it exists: display the file (the PNG in `stickers/source/` or `stickers/`) next to its word and mode, one by one as they are generated or arrive, not as a list of paths at the end. When all are in, show the contact sheet (`review/stickers.html` rendered, or the images in a grid if the host cannot render HTML) and the check results per sticker. Never describe an image the creator has not seen, and never approve one for them.

Commands below run from the kit's root, the folder two levels above this file (`<kit>/skills/<this skill>/SKILL.md`); from anywhere else, prefix `scripts/` with that path. If a script answers that dependencies are not installed, run the `npm install` it prints.

Ask the creator how they want images: **"Make them with any image tool you like, or generate them with your own OpenAI key?"**

- With their own tool (the default, no key): `node scripts/stickers.mjs <deck-folder> --provider none`. Tell them the prompts are in `prompts/stickers.json` (one per sticker card, with a negative prompt) and that each image goes to `stickers/source/<slug>.png` (any size, transparent background). Rerun the same command once the files are in place.
- With OpenAI: `node scripts/stickers.mjs <deck-folder> --provider openai` (needs `OPENAI_API_KEY` in the environment or a `.env` file; the script says so if it is missing).

**You are the vision check.** Once images exist, the script leaves one request per image in `work/vision/<slug>.request.md`. Open the image it names and look at it (do not guess from the file name or the prompt), answer honestly whether a learner who does not know the word would get the meaning from the picture alone, write `{"depicts": true|false, "reason": "..."}` to the answer file, and rerun. A vague picture is `false`; say why. With a key the script asks OpenAI's vision model instead.

What the script does, so you can explain it. Every card has one of four modes, chosen by `/deck-text` and kept here:

- **sticker**: a concrete noun or a clear action one centred picture shows (a bread roll, a person waving).
- **symbolic**: a conventional visual metaphor a learner reads without the word. Greetings and formulas belong here, not in text-first: a rising sun for "Guten Morgen", a crescent moon with stars for "Gute Nacht", a handshake for "Freut mich", a thumbs-up for "Mir geht es gut", a hand raised in apology for "Entschuldigung", a clock for "Bis später", a calendar page for "Bis morgen". If the creator says a metaphor is wrong, change `sticker.concept` on that card in `cards.json` (the one field a creator may edit by hand) and rerun.
- **contextual**: a contrast or a small scene, only where that is what makes the meaning unmistakable.
- **text-first**: no image, only when no honest picture exists (articles, "auch", "kein", "wie"). Function words are text-first by rule whatever the model said.

Every image is checked mechanically (transparent background, subject not touching the edge, at least 512 px, readable at 96 px) and by the vision check above, which knows the mode (does a learner see the meaning from the image alone; is a symbolic metaphor conventional and read at a glance). An armchair for "quiet" fails the vision check on purpose.

Then open `review/stickers.html` with the creator and go through every sticker: approve, reject or defer each one.

```bash
node scripts/stickers.mjs <deck-folder> --approve "<card key>"
node scripts/stickers.mjs <deck-folder> --reject "<card key>"
node scripts/stickers.mjs <deck-folder> --defer "<card key>"
```

Approving prepares the 768 px sticker into `stickers/`. Rejecting makes the card text-first (the creator decided there is no honest picture). Deferring keeps the mode and the picture idea but ships the card text-only for now, so a deck can pack before every image exists; the prompt stays in `prompts/stickers.json` and the next run with an image in `stickers/source/` picks it up. A failed image cannot be approved: regenerate it with `--force "<card key>"` (only on an explicit request from the creator; this is the one way an approved sticker is ever replaced) or drop a better file into `stickers/source/`.

Nothing packs while a sticker is pending, failed or missing, so finish the sheet before `/deck-check`.

Referenced files: 1

View saved version →

---
name: deck-text
description: Write every app-ready field of a Vocabloot deck: article, gender, plural, IPA, romanization, translation, two example sentences with translations, tappable tokens with lemma, part of speech, grammar codes and meanings, and a sticker picture idea per card; the script validates each card and writes cards.json, the localization file and a review report. Use after /deck-create, when a deck folder has words.json but no cards.json, or when the creator says /deck-text, generate the cards, or write the sentences.
license: MIT
compatibility: Requires Node 22 and the kit's scripts (npm install in the kit folder); network access to vocabloot.com for the language registry, with an offline snapshot fallback.
---

# /deck-text

**Show your work.** This is step 2 of 6. Say so before the first command. While you answer the requests, do them in batches of five and post one line after each batch ("Cards 1 to 5 of 20 written: Hallo, Guten Morgen, Guten Tag, Guten Abend, Gute Nacht"), so the creator sees the deck grow. After the rerun, post the result line (N cards, N flagged) and then three full cards exactly as they will read in the app: headword, pronunciation, meaning, both sentences with their translations. Never work in silence for more than one command.

Commands below run from the kit's root, the folder two levels above this file (`<kit>/skills/<this skill>/SKILL.md`); from anywhere else, prefix `scripts/` with that path. If a script answers that dependencies are not installed, run the `npm install` it prints.

Run on the deck folder the creator made with `/deck-create`:

```bash
node scripts/text.mjs <deck-folder>
```

Without an API key the script leaves one request per word in `work/text/<word>.request.md` and lists them. **You write the cards.** For each request: read it in full (the instructions are the card prompt filled in for this deck's languages and level; the input is the headword; the JSON schema is at the end), then write the card as one JSON object to the answer file it names. Every field to the letter: IPA between slashes, article, gender and plural for nouns where the language has them, two short natural sentences a learner at this level would say, and for every word of every sentence one token with its exact visible text, lemma, part of speech, grammar codes from the list, and one to three meanings in the creator's language. Choose the sticker mode with care: a formula like "good morning" is symbolic (a rising sun), not text-first. Then run the same command again: it validates every answer against the schema (a wrong field is named), turns the answers into `cards.json` (learning-language content), `localizations/<known>.json` (translations and token meanings), `cards-cache.json` (so reruns are free) and `review/report.md`. Answers you already gave are cached; only the ones it names are still open.

With `OPENAI_API_KEY` set, the script asks OpenAI instead and `--verify` adds a second grading pass per card; `--agent` keeps the writing on you even with a key.

Then open `review/report.md` and walk the creator through **"Needs a look"** first: every flagged card, with the flag in plain words (an uncovered word, a low-confidence field, a safety concern, a verify problem). For each flagged card the creator can:

- accept it as is (say so; the flag stays and the packer will refuse until it is resolved, so this is only for reading),
- regenerate it: `node scripts/text.mjs <deck-folder> --refresh "<word>"` (this drops the cached answer; delete `work/text/<word>.json` too, then write a better answer to the new request),
- replace the word in `words.json` and rerun.

Never edit `cards.json` or the localization by hand to fix a flag; the fix goes through the word list or a refresh. After the flags, show the creator two or three cards in full (headword, meaning, both sentences with their translations) so they see what a card is, and ask **"Does this read right?"** Then say the next step is `/deck-stickers`.

Rules: no key is needed and none is ever read but the creator's own; the deck's prompt is `prompts/card.md` (a `--prompt-file` override exists for people who maintain their own). Never write `cards.json` or the localization directly; your answers go through the script so every card is validated the same way.

Referenced files: 1