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 re...

Security Scan

The skill's behavior (reading/writing a local vocabulary file and managing quizzes) matches its description; it doesn't request credentials or install code, but it will store user-provided text in workspace files so consider privacy of saved content.

Purpose & Capability

Name/description (vocabulary collection, quizzes, spaced repetition) align with the actions in SKILL.md: reading and appending structured entries to memory/vocabulary.md and reading audio files from docs/tts-fr/. Nothing requested is unrelated to the stated purpose.

Instruction Scope

Instructions explicitly tell the agent to read and write the workspace file memory/vocabulary.md (including using 'tail' or direct file reads) and to read audio files from docs/tts-fr/. This is within scope, but the skill will persist user-provided text (context sentences, book excerpts) to a local file — a privacy consideration. The doc also references 'memory_search' (platform memory API) but does not declare or explain it; that is likely a platform capability but is not otherwise required by the skill metadata.

Install Mechanism

No install spec or code files are present (instruction-only). Nothing is downloaded, installed, or executed beyond recommended file reads/writes, so install risk is minimal.

Credentials

The skill declares no environment variables, credentials, or config paths. Its file access is limited to the workspace paths it documents. There are no unexplained credential requests.

Persistence & Privilege

always:false (no forced inclusion). The skill expects to store user data in a workspace file and mentions scheduled/cron-triggered quizzes; combined with autonomous invocation allowed by default, this means the agent could run these quizzes automatically if the broader agent environment triggers the skill. This is not inherently dangerous but is a privacy/notification consideration for users.

Assessment

This skill is coherent and does what it says: it adds and manages vocabulary entries in a local workspace file (memory/vocabulary.md) and reads audio files from docs/tts-fr/. Before installing, consider: (1) privacy — the skill will save sentences and context you provide into a file in the agent workspace (don’t paste sensitive excerpts if you don’t want them stored); (2) backups — if you want to keep or remove saved vocab, verify or back up the memory/vocabulary.md file; (3) scheduled quizzes — the skill references scheduled/cron quizzes and can be invoked by the agent autonomously, so if you prefer no automatic prompts make sure your agent's trigger settings prevent unwanted runs. If you want to be extra cautious, inspect the workspace file after first use and confirm the file paths match your expectations.

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 in American English IPA first (for example: /ˈtrɑːli/)
2. Give meaning — clear, simple
3. Give synonyms — similar words they might know
4. Add to tracker immediately unless the user says not to add it
5. Show the word card after adding

Always prefer IPA over ad-hoc respelling in both the explanation and the word card. If a plain-English pronunciation hint is helpful, include it only after the IPA, not instead of it.

If the user says they are focusing on pronunciation, ask which words they confuse (for example: seem / same / sim). In pronunciation-focused mode:

• Treat the set as a single comparison entry if the user's goal is sound comparison, not three separate vocabulary items
• Show each word's pronunciation separately in the reply and in the word card
• Record the entry with a combined title like ### seem / same / sim
• Use the Meaning field to explain how to pronounce the words and what sound difference to notice, not the usual vocabulary meaning
• Keep the pronunciation explanation short, practical, and contrast-focused
• If the user does not provide a sentence, generate very very simple context lines for each word
• Use the shared book/page/context the user gives

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

Word Entry Format

### [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)

Pronunciation Comparison Entry Format

### [word 1] / [word 2] / [word 3]
- **Type:** pronunciation comparison set
- **Learned:** YYYY-MM-DD HH:MM TZ
- **Book:** [source name]
- **Page:** [number]
- **Pronunciation:**
  - **[word 1]** — /IPA/
  - **[word 2]** — /IPA/
  - **[word 3]** — /IPA/
- **Meaning:** Short pronunciation guidance explaining the sound difference (for example: `[word 1]` has /iː/, `[word 2]` has /eɪ/, `[word 3]` has /ɪ/)
- **Synonyms:** pronunciation set, minimal comparison set
- **Context:**
  - **[word 1]:** "[very simple sentence]"
  - **[word 2]:** "[very simple sentence]"
  - **[word 3]:** "[very simple sentence]"
- **Practice History:**

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 + review count (e.g. "reviewed 0 times" or "reviewed 3 times") → 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.

Pronunciation-Focused Practice

If the user wants pronunciation practice instead of meaning-first vocabulary study:

• Ask which words they confuse
• Show the pronunciation for each word clearly, using IPA first
• Highlight the key sound contrast briefly
• Explain how to say the sounds (mouth shape, long/short vowel, tongue or lip position when useful) instead of focusing on dictionary meaning
• Record the set as one pronunciation comparison entry when that is more useful than separate entries
• Use very simple example sentences in the Context field, one short line per word when possible
• Do not force the normal meaning-first 3-step flow for a pure pronunciation comparison request

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

1. Count each word's total practice history entries (all steps and reviews combined)
2. Sort all words by review count ascending (least reviewed first)
3. Take the group with the minimum review count
4. Within that group, randomize: count words (N), use (current_timestamp_ms % N) + 1 to pick position
5. Never pick the same word twice in a row. Check Quiz State for the last quizzed word and skip it.

Always show review count when quizzing: e.g. "(reviewed 0 times)" or "(reviewed 3 times)".

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:

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

Update after each quiz interaction.

Cron Setup

When the user asks to set up a scheduled vocabulary quiz:

1. Ask for: frequency (default: every 1h), delivery channel + target
2. Job name: vocabulary-quiz-{agentName} (e.g. vocabulary-quiz-english)
3. Create a cron job with these settings:
   • Session: isolated
   • Timeout: 120 seconds
   • Message: instruct the agent to use the vocabulary-builder skill to run a quiz
4. Quiz constraints (include in the cron message):
   • Check Quiz State — skip if pending quiz unanswered today
   • Respect sleep hours: no messages 11PM–7AM (user's timezone)

References

• Video: Why I Stopped Using Flashcards and Started Using AI