# Vocabulary Builder

> Build and review vocabulary from books, podcasts, and daily encounters. Use when the user wants to READ a book, shares a new word, asks about a word while reading a book, requests a vocabulary quiz, asks about word progress, or when a cron/heartbeat triggers a scheduled quiz. Handles reading sessions, word collection, 3-step learning, spaced repetition, and progress tracking.

- Skill: `johnalbertini14-glitch/vocabulary-builder` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add johnalbertini14-glitch/vocabulary-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/johnalbertini14-glitch/vocabulary-builder/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: johnalbertini14-glitch (https://skillmd.com/u/johnalbertini14-glitch)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/johnalbertini14-glitch/vocabulary-builder

---


# Vocabulary Builder

This skill reads and writes the following files (paths relative to workspace):
- **Vocabulary tracker:** `memory/vocabulary.md` — all word data lives here
- **Audio clips directory:** `docs/tts-fr/` — read-only; user places pronunciation audio files here

Ensure these paths exist or create them before first use.

## Reading Workflow

When the user wants to read/practice reading a book:
1. Ask what book they're reading
2. Check the vocabulary tracker for words from that book — read the END of the Active Words section (use `tail` or read the last entries) to find the actual last word. Note: `memory_search` may return partial/ranked results, so also verify by reading the file directly when checking the latest entry.
3. Tell them the last word added + page number so they know where to continue
4. Ask if they want to: practice pending words, or keep reading and add new ones

## Adding New Words

When the user gives a new word:

1. Give **pronunciation** (IPA, American English)
2. Give **meaning** — clear, simple
3. Give **synonyms** — similar words they might know
4. **Add to tracker** after confirming with the user (e.g., "Adding [word] to your vocabulary — ok?")
5. **Show the word card** after adding

Add to the `## Active Words` section, at the END (before `---` separator for Long-Term Review).

### Word Entry Format

```markdown
### [word]
- **Type:** noun/verb/adj/adv
- **Learned:** YYYY-MM-DD HH:MM TZ
- **Book:** [source name]
- **Page:** [number]
- **Pronunciation:** /IPA/
- **Meaning:** [explanation]
- **Synonyms:** [similar words]
- **Context:** "[sentence from source]"
- **Practice History:**
  - YYYY-MM-DD HH:MM TZ: Step N ✓/✗ (notes)
```

### French Words

- **Context:** French sentence only
- **English Translation:** Separate field with English translation
- Do NOT mix French and English in the same field
- User places audio clips in `docs/tts-fr/` → add **Audio** field with the file path

## 3-Step Learning Process

Run all 3 steps in one conversation flow (not spread across hours):

- **Step 1:** Show the plain word → ask "Do you know the pronunciation?" → user types word to confirm
- **Step 2:** Ask "What does it mean?" → check if correct/close enough
- **Step 3:** Ask user to write a sentence using the word

Trust-based pronunciation — no voice/ASR check. User types word to confirm.

## Spaced Repetition Schedule

After completing all 3 steps, review at:
- Next day → 3 days → 1 week → 2 weeks → 1 month → 3 months
- After 3-month review: word is **mastered**

### Word Progression

Words move through three sections in the tracker:
1. **Active Words** — currently learning
2. **Long-Term Review Words** — completed all steps, in spaced review
3. **Mastered Words** — passed all reviews through 3 months

## Quiz Rules

- **One word per quiz** — no rapid-fire
- **No spam:** If no reply to previous quiz today → don't send new one
- **Reset next day:** New day = can send quiz even if yesterday's unanswered
- **Sleep hours:** No messages 11 PM – 7 AM (user's timezone)
- **Priority:** due for review > newer words (incomplete steps) > refresher

### Random Word Selection

Count unpracticed words (N), take current Unix timestamp, calculate:
`(timestamp % N) + 1` = position. Pick that word.

### On-Demand Quizzes

User can request specific quizzes anytime — these override normal priority and spam rules:

- "Quiz me" → random word
- "Quiz me on [word]" → specific word
- "Quiz me on words from [book]" → random from that book
- "Quiz me on words from this week" → last 7 days
- "Quiz me on [book] page [N] to [M]" → page range
- "Give me 3 quizzes" → run 3 words in a row

On-demand refresher: If no words are due/pending, pick random word from all learned words. Still record quiz date.

## Quiz State Tracking

Keep a `## Quiz State` section at the top of the tracker file:

```markdown
## Quiz State
- **Pending quiz:** [word] ([review type], [step] sent)
- **Last quiz sent:** YYYY-MM-DD HH:MM TZ
```

Update after each quiz interaction.

## References

- Video: [Why I Stopped Using Flashcards and Started Using AI](https://youtu.be/wjWrVpZZXSg)