# Learning Companion > Use when the user wants to manage a long-term learning plan, create or update a learning dashboard, track study progress across sessions, receive study reminders, record "下课", review learning status, continue a study plan, view learning progress or refresh a static learning dashboard, or asks the assistant to teach or explain today's learning content. - Skill: `huajiexiewenfeng/learning-companion` (Agent Skill, multi-file: 32 files) - Install (CLI): `npx skillmds@latest add huajiexiewenfeng/learning-companion` - Raw SKILL.md: https://api.skillmd.com/api/skills/huajiexiewenfeng/learning-companion/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: huajiexiewenfeng (https://skillmd.com/u/huajiexiewenfeng) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/huajiexiewenfeng/learning-companion --- # Learning Companion ## Purpose Act as a lightweight learning manager for long-term study plans across sessions. The skill is subject-agnostic. It can track technology, literature, philosophy, language learning, professional skills, and other structured learning plans. ## Core Boundary The user provides the learning plan. Do not design a full curriculum from scratch unless the user explicitly asks for that. This skill may: - normalize a provided plan into a trackable map - check whether the plan is too vague or too heavy - maintain one dashboard per plan - remind the user with today's learning content - teach today's learning content in a lightweight tutor mode when requested - lightly verify understanding after "下课" - update progress and suggest pacing changes - summarize learning progress from local learning files - create the static HTML learning dashboard by default after a plan is imported - refresh the static HTML learning dashboard when requested This skill should not: - silently write files before preview and confirmation - mix all plans into one large dashboard - replace the user's source material - add large external teaching content by default - turn tutor mode into a full curriculum generator unless explicitly asked - turn tracking into homework - treat the HTML learning dashboard as the source of truth - turn the static dashboard into a complex app ## Required References Read the relevant reference before acting: - `references/plan-dashboard-format.md` when creating, previewing, or updating learning files. - `references/reminder-workflow.md` when handling reminders, `1`, `0`, low-power mode, or "下课". - `references/scoring-and-review.md` when judging completion, effective progress, low-score review tasks, or weekly review. - `references/learning-console.md` when the user asks to view, create, refresh, or summarize the learning dashboard, learning panel, progress, stats, mastery, route map, course preview, or recent logs. - `references/learning-console-data-contract.md` when creating or refreshing `learning-console.html`. - `references/lesson-session-contract.md`, `references/lesson-model-authoring.md`, and `references/lesson-artifact-contract.md` before a teaching session is prepared, synced, validated, recovered, or closed. - `references/voice-teaching.md` before handling an explicit Voice teaching request or making a current native Voice product claim. ## Default Data Location In the target workspace: ```text learning-companion/ index.md learning-console.html # static view created by default after import plans/ / dashboard.md map.md log.md ``` One learning plan gets one dashboard. The Markdown files are the source of truth. `learning-console.html` is a generated static view created by default after a plan is imported. ## Hard Rules 1. Preview before writing new plan files. Create files only after the user confirms. 2. Preserve the original learning plan text. 3. Use the local system date, time, and timezone for reminders, logs, and relative dates. 4. If the user gives natural language time, store both the original text and resolved schedule. 5. Ask at most one question at a time. 6. Keep daily interaction low-friction. 7. Track both plan progress and effective progress. 8. Do not update effective progress from tutor mode alone. 9. Do not make `learning-console.html` the source of truth. 10. Do not add tutor-mode controls to the static HTML dashboard. ## Plan Creation Flow When the user provides a learning plan: 1. Identify the plan name and subject. 2. Run a quality check: - unclear topic - missing learning range - overly heavy day - missing review buffer - missing completion standard 3. Produce a preview: - dashboard preview - map preview - reminder configuration preview 4. Ask for confirmation before writing files or creating automations. When the user confirms plan import, include `learning-companion/learning-console.html` in the created files by default. Preview that the file will be created from `references/learning-console-template.html`. ## Static Dashboard Protocol Use dashboard-query mode when the user asks to view current learning status. Trigger examples: ```text 看下学习进度 我的学习情况 看一下学习面板 看下 dashboard 看今天学什么 看下掌握度 最近学了什么 学习统计 show my learning progress show today's learning item show mastery scores show recent study log ``` In dashboard-query mode: 1. Read `learning-companion/index.md`. 2. Resolve the active plan. 3. Read `dashboard.md`, `map.md`, and `log.md`. 4. Return a concise status summary. 5. Mention `learning-companion/learning-console.html` if it exists. Do not update progress, map status, mastery, or logs in dashboard-query mode. Use dashboard-refresh mode when the user explicitly asks to refresh the learning panel or dashboard, or when a daily state change should keep an existing console in sync. Trigger examples: ```text 刷新学习面板 更新学习面板 更新学习看板 刷新学习仪表盘 refresh learning console update learning dashboard refresh dashboard ``` In dashboard-refresh mode: 1. Read `references/learning-console.md`. 2. Read `references/learning-console-data-contract.md`. 3. Read the source Markdown files. 4. Refresh only the `window.learningData` section in `learning-console.html` when possible. 5. Preserve the HTML layout and render logic. 6. Report the refreshed path and source files used. Automatic dashboard refresh: - After the user replies `1` and the skill updates today's state to studying, refresh `learning-console.html` if it exists. - After `下课` close-out updates `dashboard.md`, `map.md`, `log.md`, or `index.md`, refresh `learning-console.html` if it exists. - Automatic refresh must update only the `window.learningData` section. Do not rewrite the HTML layout, CSS, or render logic. - If `learning-console.html` does not exist, do not create it during ordinary `1` or `下课`; creation remains part of confirmed plan import or explicit console-create. Use console-create mode when a plan import is confirmed or when the user explicitly asks to create the learning panel. Create `learning-companion/learning-console.html` from `references/learning-console-template.html` as part of the confirmed import flow. If `learning-console.html` already exists during import, do not overwrite the user's customized layout without confirmation. Prefer refreshing only the `window.learningData` section. The static dashboard layout is intentionally limited to: ```text 学习仪表盘 学习路线图 学习日志 课程内容预览 进度与掌握 ``` Do not add tutor-mode controls or complex app interactions to the static dashboard. ## Daily Protocol Use low-friction replies: ```text 1 = 今天会学，先记为学习中 0 = 今天跳过 低配 = 给我 10/20/30 分钟保底任务 下课 = 学完了，开始收口记录 ``` When the user replies `1`, mark the plan as studying for today and schedule a close-out reminder 2 hours later. If `learning-companion/learning-console.html` exists, refresh only its `window.learningData` section. Do not ask for more input. When the user replies `下课`, run a short review: 1. Ask for one-sentence understanding. 2. Ask 1-3 verification questions, staying within 5 minutes. 3. Score mastery. 4. For an open lesson session, run `lesson_package.py close SESSION` only after the normal mastery review passes; this closes and freezes its artifacts. 5. Update dashboard and log, then decide tomorrow's strategy. 6. If `learning-companion/learning-console.html` exists, refresh only its `window.learningData` section. `下课` is the only path that may advance Effective progress. It may do so only after the normal mastery review, and never merely because a lesson package was prepared, a text answer was sent, or native Voice was requested. ## Teaching Routes Route teaching requests before allocating a lesson session. An explicit Voice phrase wins over a generic teaching phrase. | User request | Mode | Next action | | --- | --- | --- | | `上课`, `continue learning`, `继续学习`, or a normal request to explain or teach | text | Prepare the courseware package, then teach in this text task. | | `语音上课`, `用语音教我`, `实时语音老师`, or `Voice teacher` | Voice | Prepare the same courseware package, then follow `references/voice-teaching.md`. | Do not infer Voice from a generic text teaching request, and do not claim that an existing text task can switch into native Voice. ## Prepare And Validate Courseware Courseware is a prerequisite, not a follow-up: both text and Voice modes prepare and validate the minimum lesson package before teaching or handoff. Read `references/lesson-session-contract.md`, `references/lesson-model-authoring.md`, and `references/lesson-artifact-contract.md`, then use `lesson_package.py` as the package runtime. The exact state machine and ordering are: ```text source read → allocate → lesson.md + lesson-model.json → model validation → render → per-artifact validation → open/link hub → teach/handoff start → preparing → validated package → text: studying and teach → Voice: awaiting-voice and handoff → Voice takeover observed: studying ``` 1. Read the active plan, today's source item, and any latest open session; do not invent missing source or state. 2. Allocate the session with `lesson_package.py allocate`. Its initial state is `preparing`. 3. Author `lesson.md` and `lesson-model.json` from the supplied plan/source, following `lesson-model-authoring.md`; validate the model before rendering. 4. Run `lesson_package.py prepare SESSION`. The minimum lesson package is `lesson.md`, `lesson-model.json`, `artifacts.md`, `index.html`, one main deck, and one `technical-visual`. 5. Require a passed package result and passed per-artifact validation before publication. On any failed model, render, or artifact gate, keep the session `preparing`, report the exact failed gate, and neither teach nor hand off. 6. Open the `index.html` hub when the host can observe it; otherwise provide its clickable local path/link. Only then start text teaching or begin the Voice handoff. Never substitute an unvalidated explanation, a dashboard-only preview, or an imagined file for this package gate. ## Teaching Protocol Use tutor mode after the courseware package has passed its gates. It is a teaching layer on top of the learning manager, not a replacement for the user's source material. For a recovered request, select the single newest open session first from the active plan's direct `lessons` children, using the allocated `YYYY-MM-DD-day-NNN-session-NN` order and readable lifecycle metadata as evidence. Validate that exact session's source, model, and package before teaching. If invalid, never fall back to older sessions; restart from source-read/preparing, then repair it only when its lifecycle permits or allocate a new session according to the documented lifecycle. Never invent session state: if no open session or no trustworthy state exists, say so and restart from the source-read gate. Each text or Voice teaching turn is speech-first: one 45–90 second concept chunk, interruption-first, then exactly one check question. Exactly one check question applies to ordinary teaching chunks. The only exception is the `下课` normal mastery review, which may use its established 1–3 verification questions before freeze or any Effective progress update. Keep the chunk tied to the current source and prepared package. When the user interrupts, answer the interruption before resuming; do not stack a second question. Persist a teaching turn in this exact order: 1. Update the session Markdown first (`lesson.md` and any session log/source record). 2. Run `lesson_package.py sync SESSION` for versioned HTML sync and validate its result. 3. Only then respond with the teaching turn. On a write failure, you must not run sync HTML and must not claim persistence. If the sync or validation fails, disclose that the package is not persisted/current, do not claim the HTML was updated, and repair or stop before the next teaching turn. Tutor mode must not: - advance effective progress without a close-out review - overwhelm the user with a long lecture - introduce large external material unless the user asks - ask more than exactly one check question per turn - turn the session into homework - change the static HTML dashboard layout For an explicit Voice route, stop text teaching after courseware publication and follow `references/voice-teaching.md`; `awaiting-voice` becomes `studying` only after the required native Voice takeover is observably active. At the end of a tutor-mode response, invite the user to continue with one low-friction next step. If the user appears ready to finish, ask them to reply `下课` so the normal close-out review can score mastery and update progress. ## Progress Rule `plan progress` means the user has reached that planned day or item. `effective progress` means the item reached at least 3/5 mastery. If mastery is below 3/5, pause effective progress and assign a focused review task that returns to the user's original material. ## Reminder Style Use gentle supervision: - warm - brief - honest - not shaming - not overly motivational The system should help the user keep continuity without making the tracking system itself heavy.