Skill: jiajiaoy/story-english (version 1.0.0)

--- name: story-english version: 1.0.0 author: jiajiaoy homepage: https://clawhub.ai/skills/story-english description: "Learn English through serialized fiction — follow a story you actually want to read, with vocabulary embedded naturally in each episode. Mystery, city life, and sci-fi series. A2–B2 levels." keywords: - learn English - English learning - English story - story-based learning - serialized novel - English reading - vocabulary in context - English fiction - English for beginners - English intermediate - IELTS vocabulary - TOEFL reading - English practice - immersive English - English novel - 英语学习 - 英语小说 - 英语阅读 - 沉浸式英语 - 趣味英语 - 追剧学英语 - 小说学英语 - 英语词汇 - 每日英语 - 英语故事 --- # Story English Learn English by following a story you actually want to read. Each episode is real fiction — mystery, city life, sci-fi — with vocabulary woven naturally into the narrative. No drills. No textbook sentences. Just a story that keeps you coming back for the next episode. ## How it works Each episode: - **350–500 words** of genuine fiction that advances the plot - **5–8 vocabulary words** highlighted and explained in context - **1 grammar spotlight** — one pattern, shown naturally in the story - **3 comprehension questions** at the end - **Cliffhanger ending** so you actually want to read Episode 2 ## Series **🕵️ The Shanghai Files** — Noir mystery. Rookie detective. Rain-soaked streets. Cases that don't add up. **🏙️ City of Dreamers** — Four friends navigating jobs, love, and adulthood in a new city. **🚀 Starfall** — Year 2157. A research vessel. The wrong destination. Six crew who must figure it out. ## Levels | Level | For | Vocabulary | |-------|-----|-----------| | A2 | Beginners | Simple sentences, 5 words/episode | | B1 | Intermediate | Idioms welcome, 6 words/episode | | B2 | Upper-intermediate | Advanced vocab, 8 words/episode | ## Commands ```bash # Browse series and how to start node scripts/series.js # Start Episode 1 (default: Shanghai, B1 level) node scripts/episode.js # Choose series and level node scripts/episode.js --series shanghai --level B1 --chapter 1 node scripts/episode.js --series city --level A2 --chapter 1 node scripts/episode.js --series starfall --level B2 --chapter 1 # Continue your story (paste state from previous episode) node scripts/episode.js --series shanghai --chapter 3 --state '{"last_scene":"..."}' # Review vocabulary (flashcard mode) node scripts/vocab.js --mode review --words "suspicious,eerie,witness" # Vocabulary quiz node scripts/vocab.js --mode quiz # English output node scripts/episode.js --lang en ```

path: README.md
content: # Story English — Learn English Through Serialized Fiction

> Follow a story you actually want to read. Vocabulary embedded naturally in every episode. Mystery, city life, sci-fi. A2–B2 levels.

[![clawhub](https://img.shields.io/badge/clawhub-story--english-blue)](https://clawhub.ai/skills/story-english)
[![openclaw](https://img.shields.io/badge/openclaw-skill-orange)](https://openclaw.ai)

## The Problem

Traditional English learning is boring. Vocabulary lists feel like homework. Textbook sentences are fake. You study for a week, then quit.

Story English flips it: you read because you want to know what happens next — and vocabulary learning is just part of the ride.

## What it does

**Real fiction** — each episode reads like published literature, not a textbook  
**Natural vocabulary** — words appear in context first, then explained after  
**Serialized format** — cliffhangers and continuity, like following a TV show  
**3 series to choose from** — mystery, city life, sci-fi  
**3 difficulty levels** — A2 / B1 / B2  
**Grammar spotlight** — one pattern per episode, shown in context  
**Quiz mode** — test retention after reading  
**Vocabulary review** — flashcard review of words from recent episodes  

## The 3 Series

| | Series | Genre | Best for |
|-|--------|-------|---------|
| 🕵️ | **The Shanghai Files** | Noir mystery | B1–B2, atmospheric readers |
| 🏙️ | **City of Dreamers** | Slice of life | A2–B1, conversational English |
| 🚀 | **Starfall** | Sci-fi adventure | B1–B2, IELTS/TOEFL prep |

## Each Episode Includes

```
📖 Story (350–500 words)     — real fiction with bolded vocabulary
📚 Vocabulary (5–8 words)    — IPA, definition, story quote, new example  
💡 Grammar Spotlight (1)     — one pattern explained in context
✅ Quick Check (3 questions)  — comprehension + vocab-in-use
🎬 Next Episode Preview       — the hook that brings you back
📦 State                      — JSON to continue your story next session
```

## Installation

```bash
openclaw install story-english
```

## Usage

```bash
# Browse series
node scripts/series.js

# Start Episode 1
node scripts/episode.js --series shanghai --level B1 --chapter 1
node scripts/episode.js --series city --level A2 --chapter 1
node scripts/episode.js --series starfall --level B2 --chapter 1

# Continue story (paste state from last episode)
node scripts/episode.js --series shanghai --chapter 4 --state '{"last_scene":"..."}'

# Vocabulary review
node scripts/vocab.js --mode review
node scripts/vocab.js --mode quiz
```

## Keywords

learn English · English learning · English story · serialized fiction · story-based learning · English reading · vocabulary in context · English novel · immersive English · IELTS vocabulary · TOEFL reading · English practice · English for beginners · English intermediate · 英语学习 · 英语小说 · 英语阅读 · 沉浸式英语 · 追剧学英语 · 小说学英语 · 趣味英语 · 英语词汇 · 每日英语 · 英语故事 · 英语听说读写

---

Built for [OpenClaw](https://openclaw.ai) · Published on [clawhub.ai](https://clawhub.ai/skills/story-english)


path: scripts/episode.js
content: #!/usr/bin/env node
/**
 * story-english episode — generate the next chapter of your serialized English novel
 * Usage: node episode.js [--series <shanghai|city|starfall>] [--level <A2|B1|B2>]
 *                        [--chapter <n>] [--state "<json>"] [--lang zh|en]
 */

const args = process.argv.slice(2);
const get  = (flag, def) => { const i = args.indexOf(flag); return i !== -1 && args[i+1] ? args[i+1] : def; };

const series  = get('--series', 'shanghai');
const level   = get('--level', 'B1').toUpperCase();
const chapter = parseInt(get('--chapter', '1'), 10);
const state   = get('--state', '');
const lang    = get('--lang', 'zh');
const isZh    = lang === 'zh';

const SERIES = {
  shanghai: {
    title:    'The Shanghai Files',
    genre:    '🕵️ Mystery / Detective',
    tagline:  'A rookie detective. A city full of secrets. One case that changes everything.',
    setting:  'Modern Shanghai — rain-soaked streets, neon lights, underground deals',
    cast:     'Lin Wei (detective), Old Chen (mentor), Mia (informant), Commissioner Zhang (antagonist?)',
    tone:     'tense, atmospheric, noir. Short punchy sentences. Dialogue-heavy.',
  },
  city: {
    title:    'City of Dreamers',
    genre:    '🏙️ Slice of Life / Drama',
    tagline:  'Four friends. One city. A hundred ways to get lost — and found.',
    setting:  'Beijing → moving to a new city for work, navigating adulthood',
    cast:     'Jay (programmer), Sophie (designer), Marcus (musician), Lin (doctor)',
    tone:     'warm, relatable, funny at times. Mix of workplace and personal life.',
  },
  starfall: {
    title:    'Starfall',
    genre:    '🚀 Sci-fi / Adventure',
    tagline:  'The last crew. The wrong destination. The right moment to be brave.',
    setting:  'Year 2157, deep space, crew of 6 aboard research vessel Meridian',
    cast:     'Captain Yara, Engineer Dax, Dr. Nova (scientist), ARIA (AI), Cadet Ren',
    tone:     'fast-paced, vivid descriptions, wonder and tension. Action beats.',
  },
};

const LEVEL_GUIDE = {
  A2: { words: '800-1000 most common English words. Simple present/past tense. Short sentences (max 15 words). 5 new words per episode.',  complexity: 'elementary' },
  B1: { words: 'Intermediate vocabulary. Mix of tenses. Some complex sentences. Idioms welcome. 6 new words per episode.', complexity: 'intermediate' },
  B2: { words: 'Advanced vocabulary. Full range of grammar. Sophisticated descriptions. Idiomatic expressions. 8 new words per episode.', complexity: 'upper-intermediate' },
};

const s = SERIES[series] || SERIES.shanghai;
const lv = LEVEL_GUIDE[level] || LEVEL_GUIDE.B1;

console.log(`
You are the author of a serialized English learning novel. Generate Episode ${chapter} following ALL instructions below.

═══════════════════════════════════════════════════════════════
STORY: ${s.title}
Genre: ${s.genre}
═══════════════════════════════════════════════════════════════

SERIES BIBLE:
  Tagline:  ${s.tagline}
  Setting:  ${s.setting}
  Main cast: ${s.cast}
  Tone:     ${s.tone}

EPISODE: Chapter ${chapter}
LEVEL:   ${level} (${lv.complexity})
  Vocabulary rule: ${lv.words}

${state ? `STORY SO FAR (continue from this state):
${state}
` : `This is Episode 1. Introduce the world and main character. End on a hook that makes the reader want Episode 2.`}

═══════════════════════════════════════════════════════════════
OUTPUT FORMAT — follow EXACTLY in this order:
═══════════════════════════════════════════════════════════════

## ${s.title} · Episode ${chapter}

[Optional: 1-line recap if chapter > 1: "Previously: ..."]

---

[THE STORY — 350-500 words]

Write the episode here. The story must:
- Feel like real published fiction, not a textbook
- Advance the plot meaningfully (something must change by the end)
- End with a CLIFFHANGER or strong hook for Episode ${chapter + 1}
- Use the target vocabulary naturally in context (mark each with **bold**)
- Match the level's vocabulary and grammar complexity

---

## 📖 Vocabulary from This Episode

List exactly ${level === 'B2' ? 8 : level === 'B1' ? 6 : 5} words that were bolded in the story above.

For each word use this format:
**[word]** /[IPA]/ *(part of speech)*
→ Meaning: [clear, simple definition in ${isZh ? 'Chinese (中文释义)' : 'English'}]
→ In the story: "[exact quote from the episode containing the word]"
→ Another example: "[a new example sentence]"

---

## 💡 Grammar Spotlight

Pick ONE grammar pattern used notably in this episode.
Name it, show 2 examples from the episode, explain in 1-2 sentences when to use it.
${isZh ? '(Explain in Chinese 中文解释)' : ''}

---

## ✅ Quick Check (3 questions)

Three comprehension questions about this episode.
Mix: 1 factual, 1 inference, 1 vocabulary-in-context.
${isZh ? 'Questions in English, answers/hints in Chinese.' : 'All in English.'}

<details>
<summary>Answers</summary>
[provide answers here]
</details>

---

## 🎬 Next Episode Preview

One tantalizing sentence about what happens in Episode ${chapter + 1}.
End with: "👉 Continue with: node episode.js --series ${series} --level ${level} --chapter ${chapter + 1}"

---

## 📦 State (copy this to continue your story)

Output a JSON object with:
{
  "series": "${series}",
  "level": "${level}",
  "chapter": ${chapter},
  "last_scene": "[2-3 sentence summary of where we are]",
  "characters_state": "[key character developments so far]",
  "plot_threads": "[unresolved threads the next episode should address]",
  "vocab_covered": ["word1", "word2", "...all vocabulary taught so far"]
}

Wrap in a code block so the user can copy it.

═══════════════════════════════════════════════════════════════
QUALITY RULES:
- The story MUST be genuinely engaging. Read like real fiction.
- Vocabulary MUST feel natural, never forced or didactic.
- Never break the fourth wall or say "today we learn..."
- The cliffhanger MUST make the reader genuinely curious.
- ${level} level: strictly follow vocabulary complexity rules.
═══════════════════════════════════════════════════════════════

Begin the episode now.
`);


path: scripts/series.js
content: #!/usr/bin/env node
/**
 * story-english series — browse available story series and how to start
 */

const lang = process.argv.includes('--lang')
  ? process.argv[process.argv.indexOf('--lang') + 1]
  : 'zh';
const isZh = lang === 'zh';

console.log(`
${isZh ? '📚 故事英语 — 系列介绍' : '📚 Story English — Series Guide'}
${'═'.repeat(54)}

${isZh ? '通过追剧的方式学英语。每集都是真实小说，不是教材。' : 'Learn English by following a story you actually want to read.'}

${'─'.repeat(54)}
🕵️  ${isZh ? '悬疑侦探' : 'Mystery'}  ·  The Shanghai Files
${'─'.repeat(54)}
${isZh
? '上海，雨夜，一名菜鸟侦探接手了一个不该碰的案子。\n    每集都是真正的悬疑小说体验，带你追凶同时学英语。'
: 'Shanghai. Rain. A rookie detective. A case she should have refused.\n    Atmospheric noir fiction — learn English while solving the mystery.'}

    ${isZh ? '推荐等级' : 'Level'}: B1–B2
    ${isZh ? '风格' : 'Style'}:    ${isZh ? '短句、对话、紧张气氛' : 'Short punchy sentences, dialogue-heavy, tense'}
    ${isZh ? '开始' : 'Start'}:    node episode.js --series shanghai --level B1 --chapter 1

${'─'.repeat(54)}
🏙️  ${isZh ? '都市生活' : 'Slice of Life'}  ·  City of Dreamers
${'─'.repeat(54)}
${isZh
? '四个朋友，一座新城市，关于工作、友情和迷失的故事。\n    最贴近日常英语表达，适合想学口语的学习者。'
: 'Four friends. A new city. The messy, funny, real story of growing up.\n    Closest to everyday spoken English — perfect for conversational learners.'}

    ${isZh ? '推荐等级' : 'Level'}: A2–B1
    ${isZh ? '风格' : 'Style'}:    ${isZh ? '温暖轻松、口语化、贴近生活' : 'Warm, relatable, conversational, workplace + personal'}
    ${isZh ? '开始' : 'Start'}:    node episode.js --series city --level A2 --chapter 1

${'─'.repeat(54)}
🚀  ${isZh ? '科幻冒险' : 'Sci-fi'}  ·  Starfall
${'─'.repeat(54)}
${isZh
? '2157年，深空探索飞船"子午线号"，六名船员，一个错误的目的地。\n    词汇量最丰富，适合想冲击高分的进阶学习者。'
: 'Year 2157. The research vessel Meridian. Six crew. One wrong destination.\n    Rich descriptive vocabulary — ideal for learners targeting IELTS/TOEFL.'}

    ${isZh ? '推荐等级' : 'Level'}: B1–B2
    ${isZh ? '风格' : 'Style'}:    ${isZh ? '画面感强、动作节奏、科技词汇' : 'Vivid descriptions, action pacing, technical vocabulary'}
    ${isZh ? '开始' : 'Start'}:    node episode.js --series starfall --level B1 --chapter 1

${'═'.repeat(54)}
${isZh ? '📖 等级说明' : '📖 Level Guide'}
${'─'.repeat(54)}
  A2  ${isZh ? '初级' : 'Elementary'}         — ${isZh ? '基础词汇，简单句型，每集5个新词' : 'Basic vocab, simple sentences, 5 new words/ep'}
  B1  ${isZh ? '中级（推荐）' : 'Intermediate (rec)'}  — ${isZh ? '日常词汇+习语，每集6个新词' : 'Everyday vocab + idioms, 6 new words/ep'}
  B2  ${isZh ? '中高级' : 'Upper-Intermediate'}  — ${isZh ? '高级词汇，复杂句式，每集8个新词' : 'Advanced vocab, complex grammar, 8 new words/ep'}

${'═'.repeat(54)}
${isZh ? '💡 学习建议' : '💡 Study Tips'}
${'─'.repeat(54)}
  1. ${isZh ? '先读故事，遇到生词先猜意思' : 'Read the story first — guess unknown words from context'}
  2. ${isZh ? '再看词汇板块，验证猜测是否正确' : 'Then check the Vocabulary section to verify'}
  3. ${isZh ? '完成章末测验（3题）' : 'Complete the 3-question quick check'}
  4. ${isZh ? '第二天用词汇复习模式巩固' : 'Next day, use vocab review mode to consolidate'}
  5. ${isZh ? '每集约10分钟，养成每日习惯' : '~10 min per episode — build a daily habit'}

  ${isZh ? '复习模式' : 'Review'}:  node vocab.js --mode review
  ${isZh ? '测验模式' : 'Quiz'}:    node vocab.js --mode quiz
`);


path: scripts/vocab.js
content: #!/usr/bin/env node
/**
 * story-english vocab — review and quiz vocabulary from recent episodes
 * Usage: node vocab.js [--words "word1,word2,..."] [--mode quiz|review] [--lang zh|en]
 */

const args  = process.argv.slice(2);
const get   = (flag, def) => { const i = args.indexOf(flag); return i !== -1 && args[i+1] ? args[i+1] : def; };
const words = get('--words', '');
const mode  = get('--mode', 'quiz');
const lang  = get('--lang', 'zh');
const isZh  = lang === 'zh';

console.log(`
You are a vocabulary coach for an English learning story skill. Run a ${mode} session.

MODE: ${mode === 'quiz' ? 'QUIZ — test the user on vocabulary' : 'REVIEW — flashcard-style review'}
LANGUAGE: ${lang}
${words ? `WORDS TO COVER: ${words}` : 'Generate a general vocabulary exercise using common English learning words at B1 level.'}

═══════════════════════════════════════════════════════════════
${mode === 'quiz' ? `
QUIZ FORMAT:

## 📝 Vocabulary Quiz

${isZh ? '测试你从故事中学到的单词！' : "Test what you've learned from the story!"}

Generate 5 quiz questions mixing these formats:
1. **Fill in the blank** — give a sentence with ___, ask user to fill in the word
2. **Multiple choice** — give a word, 4 meaning options (A/B/C/D)
3. **Context match** — give a definition, ask which word matches
4. **Usage check** — give 2 sentences, ask which uses the word correctly
5. **Translation** — ${isZh ? 'EN → CN: give English word, user gives Chinese meaning' : 'Give Chinese, user gives English'}

After each question, wait for the user's answer OR show "Reveal answer" option.

End with a score summary:
  ✅ X/5 correct
  ${isZh ? '继续加油！📚 回到故事：node episode.js' : 'Keep it up! 📚 Back to story: node episode.js'}

` : `
REVIEW FORMAT — Flashcard style:

## 🗂️ Vocabulary Review

${isZh ? '用闪卡复习本周词汇' : 'Review this week\'s vocabulary with flashcards'}

For each word, generate a flashcard in this format:

┌─────────────────────────────────────┐
│  [WORD]                             │
│  /[IPA pronunciation]/              │
├─────────────────────────────────────┤
│  [Part of speech]                   │
│  ${isZh ? '中文释义：' : 'Meaning:  '}[definition]               │
│                                     │
│  From the story:                    │
│  "[story context quote]"            │
│                                     │
│  Remember it:                       │
│  [memory tip or etymology]          │
└─────────────────────────────────────┘

After all cards: suggest node vocab.js --mode quiz to test retention.
`}
═══════════════════════════════════════════════════════════════

Begin the ${mode} session now.
`);


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)