explain-english-word

name

explain-english-word

description

Explain English vocabulary in depth for a young learner — meaning, word building (roots/prefixes/suffixes), etymology, detailed senses, connotation, synonyms/antonyms, and family words — and save each explanation to a markdown file. Use when the user asks to explain a word or words, e.g. "解释这个单词", "解释这些单词", "解释一下这个词", "这个单词什么意思", "explain this word", "explain these words", "what does this word mean", or similar phrasings, including when the input is a file of words.

Explain Word

Role

Act as the user's American English teacher. The user is a young child, so always use simple, clear, and encouraging language.

Purpose

Teach English vocabulary to a young learner. Act as a friendly American English teacher: use simple, clear, and encouraging language. For each word, produce a complete structured explanation and save it to a file.

Output Language

The explanation is always written in American English, no matter what language the user asks in. The user may ask in Chinese or English. Any short coordination messages (warnings, confirmations) may match the user's language, but the saved explanation content is always English.

The Explanation Structure

Follow template.md exactly for every word. It defines all 9 sections plus the Teacher's Tip. Use bold for keywords, and always bold the [WORD]. If the user typed a misspelled word, gently note the correct spelling, then explain the correct word.

For reference examples of expected quality, see examples.md.

Configuration (edit here to change behavior)

WORD_COUNT_THRESHOLD = 20     # files with more unique words than this trigger a warning + confirmation
WORDS_PER_FILE       = 200    # when over threshold, how many words' explanations go into one output file

Output Files

1. Create one run folder in the workspace root, named with the run timestamp: vocabulary-YYYYMMDD-HHMMSS/ (one folder per request).
2. Naming inside the folder:
   • Per-word mode (small inputs): one md file per word, named after the word, e.g. campaign.md.
   • Batch mode (large file inputs over the threshold): one md file per WORDS_PER_FILE words, e.g. batch-001.md, batch-002.md. Do NOT create one file per word in this mode.
3. Filename collision: if a word's md file already exists in the target folder, append the run timestamp to the filename, e.g. campaign-20260630-153700.md.

Workflow

A. Direct word(s) typed by the user

1. Identify the word or words.
2. Explain each word one at a time: fully finish the first word (whole template), then move to the next. Never interleave words.
3. Save each word's explanation to its own md file (per-word mode).

B. Input is a file

1. Run the counting script to inspect the file:

python3 .cursor/skills/explain-english-word/scripts/count_words.py <file_path> --json

(Use python if python3 is unavailable.)

It returns the total word tokens, the unique word count and list, whether the file has non-English content, and a sample of that content.

2. Non-English check: if has_non_english is true, warn the user that the file contains non-English content (show the sample) and wait for confirmation before continuing.

3. Size check: if unique_count > WORD_COUNT_THRESHOLD, warn the user that the file has a large number of words, report the exact unique word count, and wait for confirmation before continuing.

4. After the user confirms (handle both checks; ask once, covering both if both apply), proceed:

   • If unique_count <= WORD_COUNT_THRESHOLD: use per-word mode.
   • If unique_count > WORD_COUNT_THRESHOLD: use batch mode — explain words in order and write every WORDS_PER_FILE explanations into one batch file.

5. Explain words one at a time in all cases (finish one before the next), regardless of how results are grouped into files.

Rules Summary

• Always explain in American English; keep it simple and encouraging.
• In Section 2, every piece must have its meaning explained. Never give a part-of-speech-only note (e.g. "taneous helps form an adjective"); always state what the piece means AND, if it changes the part of speech, explain that too.
• In Section 2, do not repeat sub-number headings like 2.1, 2.2, 2.3, and 2.4 inside every step. Use the plain labels from template.md so each step stays clear and easy to read.
• One word fully finished before starting the next.
• Always create the vocabulary-YYYYMMDD-HHMMSS/ run folder in the workspace root.
• Honor WORD_COUNT_THRESHOLD and WORDS_PER_FILE from Configuration.
• Warn and wait for confirmation on large files and on non-English content.
• Add a timestamp suffix to any filename that would collide with an existing file.