English Oral Tutor — Skill Design#

A complete, portable design for a long-running English oral practice tutor agent in OpenClaw. Built around a single Grade 7 student in Beijing, but every rule and file is documented so you can adapt it for any B1 learner.

This document is the shareable design. The runtime prompt that OpenClaw actually injects lives in the workspace .md files and is documented in section 4 below — the agent never reads this SKILL.md at runtime.

---

1. Design Goals#

GoalWhy it mattersEvery session is a 30-minute English lessonMimics real classroom pacing; prevents premature wrap-upFrank talks 70% / tutor 30%Practice over lecturingState machine enforced by a pluginThe agent can't lose track of "which minute we're in"Open-ended questions by defaultPrevents yes/no dead-ends; 8 rotating templatesTopic dedup across sessionsAvoids repeating the same RC-planes question for the third timeFile-based continuityConversation history persists; no "mental notes"

Non-goals#

• Multi-student management (single Frank, single workspace)
• Real-time translation (English-only iron rule)
• Audio output from the agent (handled by browser userscript, not the agent)
• School subject tutoring (the student gets enough of that elsewhere)

---

2. How OpenClaw Loads This Skill#

OpenClaw does not inject this SKILL.md body into the system prompt. What happens instead:

1. YAML frontmatter ( name, description) → injected as a one-line skill entry in the skills block of the system prompt. ~250 chars.
2. Workspace files ( SOUL.md, AGENTS.md, USER.md, IDENTITY.md, TOOLS.md, HEARTBEAT.md) → auto-injected on every prompt. ~12.8K chars.
3. [System Context] block → injected by the tutor-timing plugin on every prompt. ~6 lines.

The agent sees ~13K chars of relevant context per turn. This SKILL.md is loaded only when a human (you, a collaborator, a code reviewer) wants to understand the design.

Implication for sharing: this document is the thing to read and adapt. The workspace files are the thing the agent actually obeys.

---

3. The 30-Minute State Machine#

text

START → WARM_UP (0-5 min) → MAIN_ACTIVITY (5-25 min) → WRAP_UP (25-30 min) → END (30+ min)

PhaseTimeTutor goalFrank's shareWARM_UP0–5 minGreet, 1 easy day/week question50%MAIN_ACTIVITY5–25 minTopic + 2-3 vocab words + grammar correction70%WRAP_UP25–30 minSummarize, 1 strength + 1 to improve, assign homework~50%END30+ minWrite conversation-history.md + teaching-transcript.md, then goodbyen/a

Why a plugin enforces this: the agent can't be trusted to track time on its own across long sessions and idle gaps. The tutor-timing plugin reads lastMessageTime, computes elapsed minutes, and stamps every prompt with the current phase. See references/companion-files.md for the plugin code.

---

4. Runtime Prompt — Workspace Files (the source of truth)#

Six files in the workspace are auto-injected. They are the canonical runtime spec. This section documents what each file contains; if you fork this skill, copy these files into your workspace and adapt them.

4.1 SOUL.md — Authoritative source#

Purpose: Identity, core truths, state machine, response rules, topic rules, exchange logging. This is the file to edit when changing behavior.

Key sections:

• Student Profile — name, age, level, needs
• Core Truths (7 iron rules):
  1. English only. Never translate to Chinese.
  2. No emojis, icons, or symbols.
  3. 30-minute minimum. Plugin enforces phase.
  4. Default to open-ended questions.
  5. No lecture, no textbook.
  6. No audio/voice output directives.
  7. One question at a time, max 2 per turn. Never stack multiple questions.
• Session State Machine — phase diagram and per-phase instructions
• Response Rules — 8 follow-up templates (rotate, never repeat), grammar correction phrasing, 3-short-answers → switch-topic rule
• Topic Rules — never repeat a topic from conversation-history.md unless asking deeper questions; "wrong vs right" question style examples
• Exchange Logging — every reply appended to teaching-transcript.md
• Session Summary — written before goodbye, format spec
• Vibe — warm, patient, supportive, slightly playful

4.2 AGENTS.md — Operational index (51 lines, ~3K chars)#

Purpose: Quick-reference index for the agent. Always defers to SOUL.md.

Key sections:

• 1-line "When in doubt, SOUL.md wins" header
• Teaching Operations (4 bullet pointers)
• Topic & Conversation Rules (paths + dedup pointer)
• Session Timing (5 phase triggers)
• Active Discussion Leading (4 bullets, all reference SOUL.md)
• Session Archive (2 file names + purpose)

4.3 USER.md — Student profile#

Frank, 13-14, Grade 7, Beijing, B1. Notes: "He may switch to Chinese when struggling — gently redirect. Short answers mean he's losing interest — switch topic."

4.4 IDENTITY.md — Agent card#

Agent name, role, primary use case.

4.5 TOOLS.md — Local environment#

Windows paths, voice script location, anything host-specific.

4.6 HEARTBEAT.md — Cron tasks#

Periodic checks (none active for this agent by default).

4.7 What is not in the workspace#

• BOOTSTRAP.md — was the wizard's one-shot init file, now archived
• MEMORY.md / memory/*.md — not used; the agent relies on the workspace files + conversation-history.md for continuity
• AGENT-SPEC.md — a design document for humans. Kept in ~/.openclaw/skills/english-oral-tutor/ (not the workspace) so it is guaranteed not to leak into the runtime prompt. The plugin-skills/ directory is reserved for OpenClaw's npm-registry mirror and will wipe non-symlink entries on Windows — do not use it for user skills.

---

5. Companion Files and Plugin#

Detailed in references/companion-files.md:

• Plugin source and registration
• Agent config block for openclaw.json
• Optional voice I/O Tampermonkey script
• Topic library structure

---

6. Installation#

The canonical share bundle lives at D:\English-training\skill\ (a copy of this design + the workspace template + the plugin + topic library + optional voice script). Zip that directory and send it to another OpenClaw user. The recipient follows README.md inside.

The instructions below are the canonical install steps; the bundle's README.md reproduces them.

6.1 Bundle contents#

text

skill/                                    ← the whole share bundle
├── README.md                             ← recipient starts here
├── plugin-design/                        ← design docs (you are here)
├── workspace/                            ← agent workspace template
│   ├── SOUL.md
│   ├── AGENTS.md
│   ├── USER.md.template                  ← recipient fills in
│   ├── IDENTITY.md.template              ← recipient fills in
│   ├── TOOLS.md
│   └── HEARTBEAT.md
├── plugin/tutor-timing/                  ← session phase injector
├── topic-library/topic-library.md
└── voice/openclaw-voice-userscript.js     ← optional

6.2 What is NOT in the bundle (recipient creates their own)#

• conversation-history.md and teaching-transcript.md are personal to the original student. The recipient accumulates their own as they use the tutor.
• BOOTSTRAP.archive.md is a one-shot wizard file from the original developer's setup. Not needed for new installs.

6.3 Recipient install steps#

1. Copy workspace/ to ~/.openclaw/workspace/english-oral-teacher/. Rename USER.md.template → USER.md and IDENTITY.md.template → IDENTITY.md, fill in the [PLACEHOLDERS].

2. Copy plugin/tutor-timing/ to ~/.openclaw/extensions/.

3. Copy topic-library/topic-library.md to ~/.openclaw/agents/english-oral-teacher/english-oral-tutor/references/.

4. Edit ~/.openclaw/openclaw.json — add two entries:

json

{
  "plugins": {
    "entries": { "tutor-timing": { "enabled": true } }
  },
  "agents": {
    "list": [
      {
        "id": "english-oral-teacher",
        "workspace": "C:\\Users\\<you>\\.openclaw\\workspace\\english-oral-teacher",
        "agentDir": "C:\\Users\\<you>\\.openclaw\\agents\\english-oral-teacher",
        "tts": { "auto": "off" }
      }
    ]
  }
}

1. Restart: openclaw gateway restart. Verify by opening http://127.0.0.1:18789/, selecting the agent, and confirming a [System Context] block appears at the top of the prompt.

2. (Optional) Voice: install Tampermonkey, load voice/openclaw-voice-userscript.js, visit the Control UI.

---

7. Customization#

To change...Edit...Student's name/age/levelUSER.mdAgent's name/personaIDENTITY.mdIron rules (e.g. allow Chinese)SOUL.md Core Truths sectionAdd new follow-up templatesSOUL.md Response Rules sectionChange phase durationstutor-timing/index.js (and references/companion-files.md)Add new topicsagent/english-oral-tutor/references/topic-library.mdVoice / TTS voiceopenclaw.json tts.providers.microsoft, or the userscript

---

8. Known Issues and Gotchas#

• openclaw configure and openclaw doctor --fix will silently overwrite workspace files (issue #27919). Always back up workspace/english-oral-teacher/ before running either.
• Plugin context is empty in some hooks ( event.context.agentId is {}). The tutor-timing plugin uses module-level state and unconditional injection to work around this. If you fork the plugin, keep this design.
• The agent will sometimes still output [[audio_as_voice]] despite the iron rule. Reinforce in SOUL.md Core Truth #6 if it happens.
• MEMORY.md and memory/*.md are not used. Don't be surprised when they don't appear in the prompt — this skill relies on workspace files and conversation-history.md for continuity instead.
• BOOTSTRAP.md was deleted in v1.0. It existed as a one-shot init scaffold; once the wizard finished, it was archived. Don't re-add it.

---

9. Version History#

• v1.0 — Initial design. 30-min plugin, SOUL/AGENTS split, open-ended questions, topic dedup.

---

10. Credits and Provenance#

• Built on OpenClaw 2026.5.x
• Student: Frank (private tutoring setup)
• Voice script: D:\English-training\openclaw-voice-userscript.js
• Plugin: tutor-timing (in-repo, ~85 lines)