← Files Vocabloot Deck KitARCHIVED FILE
README.md
14 KB · Oct 2, 2026 · 00:34 UTC
# Vocabloot Deck Kit
[](https://github.com/vaazh-studios/vocabloot-deck-kit/actions/workflows/check.yml)
[](LICENSE)
[](https://nodejs.org)
[](https://chatgpt.com/plugins/plugins_6aaafa1735208191ac6afb27325cc385)
[](#install)
Make a [Vocabloot](https://vocabloot.com) deck from a conversation. Say which language you speak, which you are learning and what the deck is about; get a `.vlbackup` the app opens as its own, with everything a word's detail page shows: pronunciation, grammar, two example sentences with translations, tap-a-word meanings and a sticker.
Six skills for Claude Code or Codex, six small Node scripts, no API key.
**Get it:** [in the ChatGPT plugin directory](https://chatgpt.com/plugins/plugins_6aaafa1735208191ac6afb27325cc385) for Codex and ChatGPT, or as a [Claude Code plugin](#install) from this repo (submitted to Anthropic's community marketplace, in review).
<p align="center"><img src="docs/images/card-in-app.png" width="300" alt="A word detail page in the Vocabloot app: a sticker of a megaphone, the headword die Ansage, its meaning, part of speech, and an example sentence with its translation"></p>
<p align="center"><sub>What a card is: a deck imported into the app, on iPhone. A kit deck fills this same page, with two sentences and tap-a-word meanings.</sub></p>
- [How it works](#how-it-works)
- [What a card contains](#what-a-card-contains)
- [Install](#install)
- [Try it](#try-it)
- [The workflow](#the-workflow)
- [Without an assistant](#without-an-assistant)
- [Languages](#languages)
- [The deck folder](#the-deck-folder)
- [The gates](#the-gates)
- [The example deck](#the-example-deck)
- [What is public and what is not](#what-is-public-and-what-is-not)
- [Questions](#questions)
- [When something refuses](#when-something-refuses)
- [Contributing](#contributing)
- [License](#license)
## How it works
You tell your assistant what deck you want. It asks the few things it needs (I speak, I'm learning, the topic, how many words, the level), checks the language pair against the app's live registry, and proposes a word list you can change.
Then the assistant writes the cards itself. For each word it gets a request file with the card rules for that language and level, the headword and the exact JSON schema, and answers it: article, gender and plural where the language has them, IPA, the translation, two short sentences a learner at that level would say, and for every word in those sentences a token with its lemma, part of speech, grammar codes and meaning. The scripts validate every answer field by field, turn the answers into the deck folder and write a review report you go through together.
Every card also gets a picture idea. A bread roll is a bread roll; "Guten Morgen" is a rising sun; "Freut mich" is a handshake; only words with no honest picture stay text-only. You make the images with any tool you like from the prompts the kit writes (or with your own OpenAI key), the kit checks them mechanically, the assistant looks at each one and says whether a learner would get the meaning, and you approve, reject or defer on a contact sheet.
The packer is the Vocabloot app's own codec compiled to JavaScript. It refuses, with the card named, while anything is unresolved. The file it writes is the file the app exports, so the app opens it as its own.
## What a card contains
One card from the example deck, trimmed. The learning-language side lives in `cards.json`; the side in your language lives in `localizations/<your language>.json`, aligned token by token.
```jsonc
// cards.json
{
"key": "Guten Morgen||phrase",
"text": "Guten Morgen",
"partOfSpeech": "phrase",
"phonetic": "/ˌɡuːtn̩ ˈmɔʁɡn̩/",
"sticker": { "mode": "symbolic", "concept": "a rising sun over a flat horizon in warm morning light" },
"examples": [{
"source": "Guten Morgen! Hast du gut geschlafen?",
"tokens": [
{ "text": "Guten", "lemma": "gut", "partOfSpeech": "adjective", "grammarCodes": ["accusative"] },
{ "text": "Morgen", "lemma": "Morgen", "partOfSpeech": "noun", "grammarCodes": ["masculine"] },
{ "text": "Hast", "lemma": "haben", "partOfSpeech": "verb", "grammarCodes": ["present"] }
]
}]
}
// localizations/en-US.json
{
"key": "Guten Morgen||phrase",
"translation": "good morning",
"examples": [{ "target": "Good morning! Did you sleep well?",
"tokens": [{ "meanings": ["good"] }, { "meanings": ["morning"] }, { "meanings": ["have", "did"] }] }]
}
```
In the app: the headword with its pronunciation, the meaning, the sentence with a play button, and every word tappable for its meaning.
## Install
Needs [Node 22](https://nodejs.org) and one of the assistants below.
```bash
git clone https://github.com/vaazh-studios/vocabloot-deck-kit
cd vocabloot-deck-kit && npm install
```
**Claude Code.** Open the kit folder in Claude Code and the six skills are there (`.claude/skills/`). From another folder, load it as a plugin for the session:
```bash
claude --plugin-dir /path/to/vocabloot-deck-kit
```
Or register it once and install it like any other plugin:
```bash
claude plugin marketplace add vaazh-studios/vocabloot-deck-kit
claude plugin install vocabloot-deck-kit@vocabloot-deck-kit
```
**ChatGPT and Codex.** The kit is in the OpenAI plugin directory: [Vocabloot Deck Kit](https://chatgpt.com/plugins/plugins_6aaafa1735208191ac6afb27325cc385), "Install plugin". Or open the kit folder in Codex and the skills are found in `.agents/skills/` (Codex reads that folder at repo scope).
**Any folder, either assistant.** Copy the skills into your user skill folders with the kit's path written into every command:
```bash
npm run install-skills
```
That writes to `~/.claude/skills` (Claude Code) and `~/.agents/skills` (Codex); pass `--claude` or `--codex` for one of them. Restart the assistant afterwards.
## Try it
Say any of these to your assistant:
- "Make me a German deck about the bakery."
- "I speak Spanish and I'm learning Japanese: 20 words for greetings."
- "/deck-create"
It will ask the rest.
## The workflow
Each step is one skill; each skill runs one script, answers what the script asks, and shows you the result before moving on.
1. **`/deck-create`** asks I speak, I'm learning, the topic, how many words, the level, words to include or avoid; checks the pair against the app's registry; the assistant proposes the word list and you edit it until it is right. Leaves `deck.json` and `words.json`.
2. **`/deck-text`** the assistant writes every card to the card prompt and the JSON schema; the script validates each one (a wrong field is named), writes `cards.json`, `localizations/<your language>.json` and `review/report.md`, and the assistant walks you through anything flagged. Fixes go through the word list or `--refresh`, never through editing the generated files.
3. **`/deck-stickers`** a picture idea per card and a prompt for any image model in `prompts/stickers.json`; you make the images (or the kit does, with your key); mechanical checks, the assistant's look at every image, a contact sheet; you approve, reject or defer each sticker. A deferred card ships text-only and keeps its picture idea for later.
4. **`/deck-check`** every gate, and `review/preview.html`: the deck as the app shows it.
5. **`/deck-pack`** the `.vlbackup`, with its SHA-256.
6. **`/deck-publish`** how to open it on iPhone or Android. Publishing to the Vocabloot community is coming; until then sharing the file is sharing the deck.
Answers are cached in the deck folder, so rerunning a step is free and reproducible.
## Without an assistant
The scripts run on their own with your OpenAI key in `OPENAI_API_KEY` or a `.env` file next to the deck (the key is read from nowhere else):
```bash
node scripts/create.mjs --known English --learning German --topic "at the bakery" --count 20 --level A1
node scripts/text.mjs de-at-the-bakery --verify
node scripts/stickers.mjs de-at-the-bakery --provider openai
node scripts/check.mjs de-at-the-bakery
node scripts/pack.mjs de-at-the-bakery
```
`--verify` adds a second grading pass per card. With a key and an assistant, `--agent` keeps the writing on the assistant.
## Languages
Only the languages the Vocabloot app offers, read live from `https://vocabloot.com/api/capabilities` when you run `/deck-create` (a dated snapshot in `registry/` is the offline fallback). The language you speak and the language you learn must differ. The kit does not claim any language the app does not have.
## The deck folder
```
de-bakery/
deck.json learningLanguage, knownLanguage, direction (derived), topic, level, author, licence
words.json the confirmed word list
cards.json learning-language content: headword, article, gender, plural, IPA, romanization, sticker mode, two sentences with tokens
localizations/en-US.json translations and token meanings, aligned by card and token
prompts/stickers.json sticker prompts for any image model
stickers/<slug>.png prepared 768 px stickers; stickers/source/ holds the originals
review/ report.md, stickers.html, review.json (decisions), preview.html
work/ the scripts' requests and the assistant's answers (safe to delete once cards.json exists)
de-bakery.vlbackup the result
```
Reusable content and localization are separate on purpose: a German headword, its IPA, sticker and German sentences serve English → German and Spanish → German alike; only the localization file differs.
## The gates
The packer refuses, with the card named, when a sentence's tokens do not reproduce it or leave a word uncovered, when a referenced sticker is missing, when an image failed a check, when a sticker card has no decision, or when a card carries an unresolved flag. Fixes go through the word list, `--refresh`, or the sticker review, never through editing generated JSON.
## The example deck
`examples/de-greetings`: English (US) → German, Greetings, 20 cards. It imports into the app as is (the app's own test suite imports it). Six stickers come from the Vocabloot German A1 pool (CC BY-NC-SA 4.0, © 2026 Vaazh Studios); the fourteen greeting formulas carry a symbolic picture idea each (see `prompts/stickers.json`) and are deferred until those images exist, so they ship text-only for now. `review/report.md` is what `/deck-text` writes.
## What is public and what is not
Public here: the schema, the folder, the registry identifiers, the content and sticker quality rules, the prompts in `prompts/`, validation, the packer, the skills, the example deck. Not here: Vocabloot's production prompts and per-language rules, the backend's logic, internal content, the official decks' card registry. Official decks use this same pipeline with a private `--prompt-file`.
## Questions
**Do I need an API key?** No. The assistant you are talking to writes the content; the scripts validate it. A key is only for generating images with OpenAI's image model, or for running the scripts unattended.
**Which languages?** Only the ones the Vocabloot app offers, read live from the app's registry when you start a deck. The kit never claims a language the app does not have.
**Where do the images come from?** From you: any image tool, using the prompts the kit writes (transparent background, one subject). Or from OpenAI with your own key. Every image is checked mechanically and looked at by the assistant before you approve it.
**What leaves my machine?** One request to `vocabloot.com/api/capabilities` for the language list. Nothing else, unless you configure an OpenAI key, in which case the kit calls OpenAI with it. There is no Vocabloot account, upload or telemetry in the kit.
**Can I edit the generated files by hand?** `deck.json` (name, description, author, licence) yes. `cards.json` and the localization no: fixes go through the word list, `--refresh`, or the sticker review, so every card stays validated. The one exception is `sticker.concept`, when a picture idea is wrong.
**How does the deck reach the app?** As a `.vlbackup` file: AirDrop, mail or Files on iPhone, a download on Android. Opening it merges the words into the wordbook; opening it twice adds nothing.
**Can I publish a deck for everyone?** Not yet. Sharing the file is sharing the deck; community publishing on vocabloot.com is in the works.
## When something refuses
- `The kit's dependencies are not installed. Run: npm install --prefix "<kit>"`: run exactly that command; the kit's one native dependency (`sharp`) is missing.
- `Vocabloot does not offer <language> as a language to learn yet`: the app's registry does not have it; the message lists what it has.
- `N requests to answer, then run the same command again`: the assistant has request files to answer in `work/`; nothing is wrong.
- `<card key>: sticker not approved yet`: open `review/stickers.html` and approve, reject or defer that sticker.
- `<card key>: unresolved flags: ...`: read that card in `review/report.md`; the fix goes through `--refresh "<word>"` or the word list.
- The registry cannot be reached: the kit falls back to the dated snapshot in `registry/` and says so; a snapshot older than 30 days is refused; run `npm run registry:refresh` online.
## Contributing
Issues and pull requests at [github.com/vaazh-studios/vocabloot-deck-kit](https://github.com/vaazh-studios/vocabloot-deck-kit/issues). `npm run check` runs formatting, lint and the tests; a change to a prompt bumps its `promptVersion` line; a change to the packer is made in the Vocabloot app repo and published here. Skills follow the [Agent Skills](https://agentskills.io/specification) format: `name` equals the folder, `description` says what and when, the body stays short.
## License
Code is MIT. The prompts and guides in `prompts/` are CC BY 4.0. The example deck's stickers are CC BY-NC-SA 4.0, © 2026 Vaazh Studios.
SHA-256: 5e2313117a354ade0263bd203fde38700be4c118289b73ecb9d619908e00acaf