borispolonsky/vocab-mastery-tracker · Skillset Overview

Core Idea

Principles & Methodology

The author's design philosophy, what sets this apart from peer projects, and quick notes on the key workflows. Skill names mentioned in the text auto-link to their detail pages.

Core Philosophy

vocab-mastery-tracker follows the principle of "minimal agent surface + lemmatization/normalization handled skill-side." The agent only sends raw text; lemmatization, normalization, and storage are all handled internally by the skill, reducing cognitive load on the agent.

Design Principles

Minimal agent surface: Only 6 commands exposed (record-learner / preview-reply / lookup-lemma / mark-known / seed-known / due-for-practice), no fuzzy matching, no mastery levels
Normalization on tracker side: Agent sends raw text; lemmatization uses registered language backends (simplemma for base install, pymorphy3 for Russian optional)
Data isolation: (learner_id, language) as the isolation unit; different learner+language combinations never share data rows
Idempotent operations: Repeated mark-known and seed-known calls produce no side effects
Strict read/write separation: record-learner only on learner messages (writes), preview-reply only on agent draft replies (read-only)

Skill Architecture

/vocab-tracker: Single core skill exposing all functionality via scripts/run.py CLI entry point. Contains four reference files: setup.md (dependency installation), record-learner-flags.md (exclusion and misuse flagging guide), cli-and-errors.md (JSON contract and error handling), persistence.md (data directory management). Progressive disclosure design — agents load reference files on demand.

Typical Workflow

Setup: Install dependencies with uv pip install -r scripts/requirements.txt, set VOCAB_TRACKER_DATA_DIR or pass --data-dir on each call
Conversation loop: Each turn: learner message → record-learner (log unknown lemmas + usage) → draft reply → preview-reply (check unknowns, iterate) → send → mark-known when appropriate
Practice recommendation: After accumulating sufficient data, call due-for-practice to generate a ranked practice list by predicted recall probability

Differentiation

Unlike full-stack language learning platforms such as Duolingo, this skill does not provide course content, glosses, or grammar explanations. It focuses on the narrow but deep layer of quantitative tracking — "which words were learned, how many times used, which ones need review" — as a composable capability module for AI language teachers.

Skill Relationships

Usage Relationships Between Skills

Skill → Skill usage relationships, with cross-layer references. Same color blocks indicate the same skill form.

Relationship Count

0

Standalone Skills

1

Most Referencing

No relationships

Most Referenced

No relationships

Note: Each dependency line reads as "the current Skill depends on" the Skill it points to.

Skill Composition

How skills in this set are triggered

Each skill is designed for a specific kind of caller — some only fire when you name them, others load automatically when the model judges them relevant. The split below summarises both modes at a glance.

User-Invoked0

These skills only fire when you call them by name. The agent will not load them on its own — they stay inert until invoked.

No skill in this set is recommended for manual invocation.

Model-Invoked1

These skills are loaded automatically by the agent when it judges the context relevant. You usually don't need to call them yourself.

vocab-tracker

Skill List

1 Skills · Filter by name or domain

vocab-tracker

Provides vocabulary mastery tracking for language-training AI agents. Agents can record lemma usage from learner messages (tokenized, lemmatized, with production counts), preview unknown words in draft replies, look up individual lemma status, mark lemmas as known, seed known-lemma lists in bulk, and rank unknown lemmas by predicted recall for practice scheduling. The core value is quantitative known-set + usage-frequency data to drive pedagogical decisions, without qualitative glosses or lesson notes. Uses a Python CLI backed by SQLite for persistence.

Domain: CodingOthers
Form: CLI ManualWorkflow
Location: src/skills/vocab-tracker/SKILL.md

Showing 1 / 1

Installation

One command to install the entire Skillset.

Copy and run in your terminal to add borispolonsky/vocab-mastery-tracker to your Agent environment.

$npx skills add borispolonsky/vocab-mastery-tracker