english-learning

An AI-assisted English learning system for long-running, evidence-based study. It combines a structured study track, vocabulary reinforcement in real work contexts, and lightweight speaking or writing feedback.

The repository is portable and suitable for open-source distribution. Public files contain reusable rules and examples; each learner's dates, baseline, progress, credentials, and logs stay in ignored local files inside the Skill directory.

What it provides

Entry	Purpose
/en-init	Measure a vocabulary baseline and create the learner profile
/en-today	Build today's tasks from local state and current evidence
/en-speak	Correct and upgrade expressions collected during the day
/en-read	Run the intensive-reading workflow and classify mistakes
/en-write	Practice and review exam-oriented writing
/en-status	Show progress, risks, and milestone-based phase advice

The root english-learning Skill contains the shared policy. The six entry Skills route concrete learning tasks to it.

Requirements

• macOS or Linux with Bash and Python 3
• Node.js 20.19.x, 22.12+, or 23+
• npm
• A Codex-, Claude Code-, or Agent-compatible Skill directory

Install

Clone the repository anywhere, then run:

git clone https://github.com/fengguanghuai/english-learning.git
cd english-learning
bash install.sh --all
python3 scripts/configure.py

The installer installs the root Skill as english-learning and the six entry Skills into the selected Agent directories. It does not require the source checkout to live at a fixed path.

For daily Skill management and discovery, the recommended command is:

npx skills

If you installed the Skills before configuring them, initialize local configuration from the cloned repository:

python3 scripts/configure.py

The command reads the MaiMemo token without echoing it and writes config/config.json with mode 0600. It also creates data/study-state.json from the public example if the file does not already exist. Neither file is committed.

Then start a new Agent session and run /en-init. Use /en-today as the normal daily entry point.

Local configuration and data

The public repository tracks only examples:

• config/config.example.json
• data/study-state.example.json

Runtime files stay directly in the installed Skill and are ignored by Git:

config/config.json          local credential and integration settings
data/study-state.json       current phase, goals, and progress
data/profile.md             learner profile and weakness summary
data/tech-vocab.md          learner-specific vocabulary map
data/error-log.md           reading error history
data/speak-log.md           expression feedback history
data/writing/               writing drafts and reviews
.runtime/                   temporary integration snapshots and candidates

This layout keeps the Skill self-contained without publishing personal learning history. Back up the ignored files separately when moving between machines.

MaiMemo credential resolution is:

1. MAIMEMO_API_TOKEN environment variable
2. ignored local config/config.json
3. Bitwarden CLI item with a hidden custom field named MAIMEMO_TOKEN
4. GitHub Actions OIDC

Never paste a token into chat, pass it as a command-line argument, or commit it to Git.

MaiMemo boundary

MaiMemo remains the source of truth for spaced repetition, daily queues, and review feedback. This Skill reads the API evidence that is available and uses a small number of suitable words in work-context reinforcement.

The integration is read-only by default. It does not add words, advance study, delete content, or send learning feedback. A failed sync is reported as partial, stale, or unavailable; old or missing data is never presented as current progress.

Study model

The plan is driven by local state and milestones, not hard-coded calendar dates:

Phase	Focus	Example transition evidence
P0	Baseline and habit initialization	baseline recorded, local profile created, stable streak
P1	Vocabulary foundation and sentence parsing	vocabulary threshold, parsing ability, initial reading evidence
P2	Intensive reading and error attribution	stable reading results and reduced unknown-word ratio
P3	Writing and task-specific practice	reusable templates and timed completion
P4	Mock exams and final review	stable mock performance against the learner's target

Exact goals, exam date, time budget, and thresholds are initialized in data/study-state.json. Phase changes are recommendations until the learner confirms them.

Conversation protocol

CLAUDE-snippet.md contains an optional global rule for embedding English in normal technical work. It uses sentence-level recasting, one high-value correction, and an immediate Chinese escape hatch (中文 or cn). Install it only if you want this behavior in every Claude Code session.

Development

npm ci --ignore-scripts --omit=dev
npm test

The repository includes contract tests for installation portability, credential safety, read-only MaiMemo behavior, and the separation between public examples and private learning state.