🎓 IELTS Coach

The Most Personalized IELTS Speaking & Writing AI Coach

An AI agent skill that interviews you first, writes in your voice,
and calibrates every sentence to official IELTS band descriptors.

🇨🇳 简体中文

---

📑 Table of Contents

• 🧠 What Makes This Different
• ✨ Features
• 🌐 Topic Discovery Web Form
• ⚡ Quick Start
• 🔄 The Workflow
• 📁 Project Structure
• 🎯 The 4D Personalization Engine
• 👁️ Vision Bridge for Non-Vision Models
• 🤝 Contributing
• 📜 License

---

🧠 What Makes This Different

Most IELTS AI tools work like this:

User: Write me an essay about climate change.
AI:   [Generates a 250-word essay full of Firstly, Secondly, In conclusion]

IELTS Coach works like this:

Coach: Before I write anything, what is YOUR take on this topic?
       [Web form opens → you fill in your thoughts at your own pace]
Coach: Let me make sure I have this right. You believe X because of
       your experience with Y. I will build your answer around that.
User:  Yes, and also mention Z.
Coach: [Polished essay IN THE USER'S VOICE, band-calibrated, zero AI flavor]

	Generic AI	IELTS Coach
Personalization	Vague references to some people or society	Specific: When I was working at [your company]...
AI detection risk	High (dashes, clichés, mechanical linkers)	Near-zero (natural cohesion, human voice)
Memorability	Hard to remember because it is not yours	Easy: it literally IS you, just polished
Scoring alignment	Random	Calibrated to official IELTS descriptors per band
Vision support	Depends on model	Works on any model (DeepSeek included) via MCP bridge
Topic discovery	None	Web form + structured interview, covering all 102

---

✨ Features

🌐	Topic Discovery Web Form Instead of typing answers in the CLI, a beautiful web form opens in your browser. Multi-step forms with progress indicators, image upload, and clipboard paste support. Fill in answers at your own pace, then submit with one click.
🎯	Progressive Topic Discovery Not just onboarding. Every new topic triggers a structured mini-interview. The agent mines your specific memories, opinions, and experiences before writing a single word. 102 topics, 102 personalized answers.
📋	Official Band Descriptor Alignment Writing answers calibrated against the public IELTS Writing Band Descriptors (updated May 2023). Task Response, Coherence and Cohesion, Lexical Resource, and Grammatical Range and Accuracy. All four criteria tuned to your target band.
🚫	Anti-AI-Flavor Enforcement Explicitly screens for and eliminates AI patterns: no em dashes, no scare quotes, no mechanical linkers like Firstly/Secondly/Finally, no This essay will discuss clichés. Reads like polished human writing.
👁️	Vision Bridge for Non-Vision Models Running on DeepSeek? Your agent cannot see charts. The included MCP server proxies images through Alibaba Cloud Bailian's free qwen3.7-plus model via DashScope, or any provider you choose. Agent auto-configures everything. You just provide the API key.
🖼️	Beautiful HTML Output Collapsible day cards with expand/collapse. Responsive, printable. Highlighted vocabulary, structure notes, copy buttons. Navy and gold IELTS-themed design.
🔄	Self-Evolving Study Plan Reschedules missed sessions, prioritizes weak areas, tracks progress across sessions via JSON state files. 102 topics never repeat unless you ask.

---

🌐 Topic Discovery Web Form

The web form is the core interaction interface for Topic Discovery. Instead of answering questions one by one in the CLI, you get a beautiful, multi-step form in your browser.

How It Works

┌──────────────────────────────────────────────────────────┐
│  Agent generates questions                               │
│       │                                                  │
│       ▼                                                  │
│  ┌─────────────────────────────┐                         │
│  │  Web Form Server starts     │  ← Auto-opens browser  │
│  │  http://127.0.0.1:8765/form │                         │
│  └─────────────────────────────┘                         │
│       │                                                  │
│       ▼                                                  │
│  User fills in answers in browser                        │
│  (multi-step, progress bar, image upload)                │
│       │                                                  │
│       ▼                                                  │
│  Submit → Answers saved to JSON → Server auto-closes     │
│       │                                                  │
│       ▼                                                  │
│  Agent reads answers → Generates model answers           │
└──────────────────────────────────────────────────────────┘

Features

• Multi-step forms — Questions organized by topic (Speaking Part 1, Part 2, Writing)
• Progress indicator — Step dots show current progress
• Image upload — Drag & drop or click to upload chart images for Writing Task 1
• Clipboard paste — Ctrl+V to paste screenshots directly
• Auto-save — Answers saved to JSON file, images saved to task1_charts/
• Beautiful UI — Gradient purple background, responsive design, works on mobile

Supported Question Types

Type	Description	Use Case
textarea	Multi-line text input	Most Topic Discovery questions
radio	Single choice from options	Preference questions
image	File upload with preview	Writing Task 1 charts
paste	Clipboard paste or file upload	Screenshots, chart images

Screenshots

Web Form: Topic Discovery

Web Form: Filled Answers

Output HTML: Header & Stats

Output HTML: Collapsible Day Card

Output HTML: Answer Card

Output HTML: Highlight Expressions

---

⚡ Quick Start

# 1. Clone
git clone https://github.com/RomainCHEN/ielts-coach.git
cd ielts-coach

# 2. Copy the skill into your agent's skill directory:
#    Claude Code:     cp -r ielts-coach /your-project/.claude/skills/
#    Other agents:    copy ielts-coach/ into whatever directory your agent uses for skills

# 3. Start your agent and just talk. The skill triggers automatically.

💡 No configuration needed. Say "Start my IELTS preparation" and the agent handles everything. Onboarding → Study Plan → Daily sessions with Topic Discovery → Model answers in HTML.

For DeepSeek and non-vision model users: The first time a chart image fails to load, the agent auto-guides you through the 2-minute Vision Bridge setup. You only provide an API key.

---

🔄 The Workflow

┌──────────────────────────────────────────────────────────┐
│                   FIRST SESSION                           │
│  Onboarding → Study Plan → Ready                         │
│  (5 min: exam date, target score, background, schedule)   │
└─────────────────────┬────────────────────────────────────┘
                      │
                      ▼
┌──────────────────────────────────────────────────────────┐
│                   EVERY SESSION                           │
│                                                          │
│  Greet + progress summary                                │
│       │                                                  │
│       ▼                                                  │
│  ┌─────────────────────────────┐                         │
│  │  TOPIC DISCOVERY             │  ← The secret sauce    │
│  │  ┌──────────────────────┐   │                         │
│  │  │ Web Form opens in    │   │                         │
│  │  │ browser (multi-step) │   │                         │
│  │  │ User fills answers   │   │                         │
│  │  │ Submit → JSON saved  │   │                         │
│  │  └──────────────────────┘   │                         │
│  │  Stage C: Content Confirm   │                         │
│  │  Stage D: Generate Answer   │                         │
│  └─────────────────────────────┘                         │
│       │                                                  │
│       ▼                                                  │
│  Model answer (your voice, your stories)                 │
│  + Highlighted expressions                               │
│  + Band-specific calibration                             │
│  + Anti-AI-flavor check                                  │
│       │                                                  │
│       ▼                                                  │
│  Save to ielts_answers.html                              │
│  Update progress → See you tomorrow                      │
└──────────────────────────────────────────────────────────┘

---

📁 Project Structure

ielts-coach/
├── SKILL.md                              # Complete agent behavior (~800 lines)
├── references/
│   ├── question-bank.md                  # Part 1 + P2&3 New topics (38+29)
│   ├── question_bank_complete.json       # P2&3 Retained + Non-mainland (27+8)
│   ├── band-descriptors.md               # Speaking criteria by band
│   ├── writing-band-descriptors.md       # Official Writing descriptors (May 2023)
│   ├── writing-resources.md              # Task 1 chart language + Task 2 templates
│   └── sample-answers.md                 # Quality calibration examples
├── scripts/
│   ├── state_manager.py                  # JSON state file management
│   ├── build_complete_bank.py            # Question bank builder
│   ├── topic_form_server.py              # Web form server (Topic Discovery)
│   └── vision_mcp_server.py             # MCP vision bridge (DeepSeek → qwen3.7-plus)
├── assets/
│   └── answer_template.html              # HTML template for answer rendering
└── docs/
    └── screenshots/                      # Screenshots for documentation

⚡ Copy the ielts-coach/ folder into your agent's skill directory. That is it. Runtime state files (user_profile.json, study_plan.json, progress.json, ielts_answers.html) are auto-generated in your project root and never tracked here.

---

🎯 The 4D Personalization Engine

IELTS Coach personalizes on 4 dimensions simultaneously. No static template can do this.

Dimension	Source	Example
1. Personal Identity	Onboarding	As a software engineer in Shenzhen...
2. Topic-Specific Experience	Topic Discovery interview (via web form)	When I was debugging that production outage at 3am...
3. Target Band Calibration	User's target score	Band 7 vocabulary density, flexible cohesive devices
4. Human Voice Preservation	User's raw language during Discovery	Their humor, their cultural references, their sentence rhythm

Result: An answer that scores well on IELTS rubrics AND the user can actually remember under exam pressure.

---

👁️ Vision Bridge for Non-Vision Models

┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Your Chart  │────▶│  vision_bridge    │────▶│  qwen3.7-plus    │
│  (PNG/JPG)   │     │  (MCP Server)     │     │  (Free tier)     │
└──────────────┘     └──────────────────┘     └────────┬────────┘
                                                        │
                                              ┌─────────▼─────────┐
                                              │  Structured text   │
                                              │  chart description │
                                              └─────────┬─────────┘
                                                        │
┌──────────────┐     ┌──────────────────┐              │
│  Task 1      │◀────│  Your Agent      │◀─────────────┘
│  Model Answer│     │  (DeepSeek, etc.) │
└──────────────┘     └──────────────────┘

One-time setup (agent does everything): pip install mcp httpx → write .claude/settings.json → restart. Only input needed: your Bailian API key (from bailian.console.aliyun.com). Model: qwen3.7-plus via dashscope.aliyuncs.com/compatible-mode/v1.

Supports custom providers too. Any OpenAI-compatible vision endpoint works.

---

🤝 Contributing

This is a personal exam preparation tool, but improvements are warmly welcome:

• Report topic inaccuracies or missing questions
• Suggest HTML design improvements
• Share calibrated sample answers for the reference pool
• Report AI-flavor patterns that slipped through
• Add screenshots for documentation

Open an issue or PR.

---

📜 License

MIT © Romain Chen. Use freely, modify freely. Good luck on your exam.

---

_{Built for IELTS May–August 2026 season · 102 speaking topics · Speaking + Writing
Made with ❤️ by someone who knows how stressful IELTS prep can be}