Personal Tutor

SKILL.md

---
name: personal-tutor
description: >
  🎓 Personal Tutor — Your private AI learning coach. 你的私人AI学习导师。
  Formerly knowledge-digest, now rebranded and upgraded to v1.0.1.
  原名 knowledge-digest，现已全面升级为 personal-tutor v1.0.1。
  Full-cycle learning management: start a subject → daily lessons → quizzes →
  three-layer post-lesson archiving (learning records + memory + knowledge base).
  全流程学习管理：开新课→每日上课→测验→三层课后归档（学习记录+记忆+知识库）。
  NEW in v1.0.1: Mandatory Post-Lesson Self-Verification Protocol — agent cannot
  declare "lesson complete" until all three archive layers are verified.
  v1.0.1 新增：强制课后自查协议——三层归档全部验证通过，agent 才能说"下课"。
  Trigger / 触发："start learning [subject]" / "开始学[科目]" /
  "continue [subject]" / "继续[科目]" / "update learning records" / "更新学习记录"。
  NOT for: casual Q&A, one-off lookups, non-learning conversations.
  不适用于：随手问答、一次性查询、非学习类对话。
version: 1.0.3
changelog: |
  v1.0.3 (2026-05-29):
  - Hardened Post-Lesson Self-Verification Protocol: added 🚨 red-line warning banner, self-check mantra (1️⃣2️⃣3️⃣), and explicit "user-caught-skipping" failure behavior.
  v1.0.2 (2026-05-29):
  - Updated description with bilingual rebranding announcement (knowledge-digest → personal-tutor).
  - Scenario 2: Added mandatory Post-Lesson Self-Verification Protocol; agent cannot declare "lesson complete" without checking all archive layers.
  - New section: Post-Lesson Self-Verification Protocol — a universal checklist for multi-agent scenarios.
  - Common Edge Cases: Added "Skipped Archiving" failure mode with recovery procedure.
  v1.0.0 (2026-05-28): Initial release.
metadata:
  tags: [learning, knowledge-management, obsidian, productivity, education, study, note-taking]
---

# Personal Tutor — Full-Cycle Learning Management / 全流程学习管理系统

## Overview / 概述

Personal Tutor turns every learning session into structured, searchable, long-term knowledge. It handles three scenarios / 三个场景：

1. **Start a new subject / 开启新学科** — create syllabus, learning log, config entries
2. **Daily lesson / 每日上课** — review → teach → quiz → prompt to archive
3. **Post-lesson archive / 课后归档** — update 6 layers: log, syllabus, memory, knowledge base, index, config

---

## First-Run Onboarding / 首次设置引导

Before executing any workflow, check for a config file at:

```
{workspace}/.personal-tutor-config.json
```

If it does **not** exist, run the onboarding flow / 如不存在则运行引导流程：

### Onboarding Flow / 引导问题

Ask the user these questions (one at a time, or all at once if they prefer)：

1. **Learning root directory / 学习资料根目录** — Where should subject folders be stored?
   - Example: `D:\Learning\` or `~/Documents/Learning/`
   - This is where syllabus files and learning logs live.

2. **Knowledge base tool / 知识库工具** — What do you use for long-term notes?
   - `obsidian` — wikilinks (`[[link]]`), vault-based
   - `plain` — standard Markdown, folder-based / 纯文件夹
   - `notion` — notes only (API integration not included)
   - `none` — skip concept archiving entirely / 跳过概念归档

3. **Knowledge base path / 知识库路径** (if tool ≠ `none`) — Where is your vault/notes root?
   - Example: `D:\Obsidian\MyVault\` or `~/Notes/`

4. **Archive depth / 归档深度** — How thorough should post-lesson archiving be?
   - `light` — update log + syllabus + memory only / 仅更新记录+大纲+记忆
   - `full` — light + extract concepts to knowledge base + refresh index / 完整归档含概念入库+索引刷新

5. **Preferred language / 内容语言** — `zh` (Chinese), `en` (English), `zh-en` (bilingual / 中英双语), or `auto` (follow user's language)

6. **Knowledge base schema / 知识库规则文件** (if tool = `obsidian` or `plain`) — Do you have a rules file that defines how concepts should be structured, named, and linked?
   - If yes, provide the path (e.g., `D:\Notes\WIKI-SCHEMA.md`). This file will be read before every concept extraction and its rules **take priority** over built-in defaults.
   - If no, the built-in Knowledge Base Rules (see section below) will be used.

### Config File Schema / 配置文件结构

After onboarding, create:

```json
{
  "version": "1.0",
  "learningRoot": "/path/to/learning/",
  "knowledgeBase": {
    "tool": "obsidian",
    "path": "/path/to/vault/",
    "schemaPath": "/path/to/WIKI-SCHEMA.md"
  },
  "archiveDepth": "full",
  "language": "auto",
  "subjects": {}
}
```

The `subjects` field will be populated as new subjects are added.

---

## Scenario 1: Starting a New Subject / 场景一：开启新学科

### Trigger / 触发条件

User says "start learning [subject name]" or "open a new subject: [name]"。
中文触发："开启[学科名]学习"、"新建学科[学科名]"。

### Workflow / 工作流

1. **Read config / 读取配置** — Load `.personal-tutor-config.json` to get `learningRoot` and preferences.

2. **Detect category structure / 检测分类结构** — Scan `{learningRoot}/` for existing subdirectories:
   - If subdirectories exist (e.g., `大学专业知识/`, `职业发展/`, `Academic/`, `Professional/`), they are treated as **categories / 分类**。Present them to the user and ask which one the new subject belongs to. If none fit, offer to create a new category.
   - If `{learningRoot}/` is flat (no subdirectories), the subject goes directly under `{learningRoot}/`.
   - Store the chosen category in the subject's config entry as `category`.

3. **Create subject directory / 创建学科目录** — Under `{learningRoot}/{category}/` (or `{learningRoot}/` if no category), create a folder named after the subject.

4. **Create syllabus file / 创建教学大纲** — `{learningRoot}/{category}/{subject}/syllabus.md`
   - Content: subject overview, learning objectives, phased plan (by day/week), key topics per phase, estimated completion, expected outcomes.
   - If the user provides specific goals or a textbook, incorporate them.
   - Leave the first phase/day marked as `⏳ Pending / 待学`.

5. **Create learning log file / 创建学习记录** — `{learningRoot}/{category}/{subject}/learning-log.md`
   - Content: an empty tracking table with columns: Date | Content | Mastery | Issues | Next
   - Initial entry: today's date, "Subject initialized", N/A, "None", "Day 1 — start learning"

6. **Update config / 更新配置** — Add to `subjects`:
   ```json
   "subject-name": {
     "currentDay": 1,
     "category": "大学专业知识",
     "syllabusPath": "{learningRoot}/{category}/{subject}/syllabus.md",
     "logPath": "{learningRoot}/{category}/{subject}/learning-log.md",
     "status": "active",
     "startedAt": "YYYY-MM-DD"
   }
   ```

7. **Update memory / 更新记忆** — If the agent has a memory system (MEMORY.md or equivalent), record the new subject there.

8. **Create knowledge base folder / 创建知识库文件夹** (if `archiveDepth` = `full` and `knowledgeBase.tool` ≠ `none`) — Create an empty subject folder under `{knowledgeBase.path}/` if it doesn't exist.

9. **Report / 汇报** (output in configured language，按配置语言输出):

```
✅ New subject "[Subject Name]" is ready. / 新学科"[学科名]"已开启。

Created / 已创建：
  📋 Syllabus: {category}/{subject}/syllabus.md
  📝 Learning log: {category}/{subject}/learning-log.md
  ⚙️  Config updated / 配置已更新

You're all set for Day 1. Say "start learning [subject]" when ready.
```

---

## Scenario 2: Daily Lesson / 场景二：每日上课

### Trigger / 触发条件

User says "start learning [subject]" or "continue [subject]"。
中文触发："开始[学科名]学习"、"继续[学科名]学习"。

### Workflow / 工作流

1. **Read config / 读取配置** — Load current progress from `.personal-tutor-config.json`.

2. **Read syllabus and log / 读取大纲与记录** — Load `syllabus.md` and `learning-log.md` to understand where we are.

3. **Review previous lesson / 回顾上节课** — Briefly summarize the last session's core content (read from the learning log). Keep it under 3 bullet points.

4. **Teach new content / 讲授新知** — Deliver the next topic(s) according to the syllabus. Follow these teaching principles:
   - Start with "why this matters" before "how it works" / 先讲"为什么重要"再讲"怎么运作"
   - Use concrete examples before abstract definitions / 用具体例子引导抽象定义
   - Break complex topics into digestible chunks / 把复杂话题拆成可消化的模块
   - Pause for questions between major sections / 大段落之间主动询问

5. **Interactive check / 互动测验** (if applicable to the subject) — Ask 2-5 questions to verify understanding. Wait for user's answers, then give feedback and corrections.

6. **Session notes / 课堂记录** — Mentally record: what was covered, what the user struggled with, what needs review.

7. **Post-Lesson Self-Verification / 课后自查（强制执行）** — Before telling the user the lesson is complete, run the **Post-Lesson Self-Verification Protocol** (see dedicated section below). If any layer is missing, fix it immediately. Do NOT say "lesson complete" / "学完了" / "done" until all layers pass.

8. **End prompt / 课堂结束语** (only after self-verification passes, output in configured language):

```
📚 Today's lesson on [Subject] (Day [N]) is complete. / 今日课程完成。

Covered / 内容: [brief summary]
Mastery / 掌握: [assessment]
Issues / 问题: [any problems noted]

✅ Archive verified / 归档自检:
  📁 Learning records: updated
  🧠 Knowledge base: [N concepts created/updated, or "no changes"]
  ⚙️  Config: updated

Ready for Day [N+1]! / 准备好下一课了！
```

---

## Scenario 3: Post-Lesson Archive / 场景三：课后归档

### Trigger / 触发条件

User says "update learning records" or "archive today's learning"。
中文触发："更新学习记录"、"归档今天的学习"。

### Workflow / 工作流

This is the most important scenario — it turns a conversation into permanent knowledge.
这是最关键的步骤——把对话变成永久知识。

### Step 1: Update Learning Log / 更新学习记录

Append to the learning log (path from config):

```markdown
## Day [N] — YYYY-MM-DD

**Content / 内容:** [summary of what was covered]
**Mastery / 掌握程度:** [good / okay / needs review]
**Quiz results / 测验成绩:** [scores & wrong answers if applicable]
**Issues / 遇到问题:** [concepts the user struggled with]
**Next / 下一步:** Day [N+1] — [next topic from syllabus]
```

### Step 2: Update Syllabus Progress / 更新大纲进度

In `syllabus.md`, mark the current phase/day as `✅ Complete / 完成`. If a milestone was reached, note it.

### Step 3: Update Config / 更新配置

In `.personal-tutor-config.json`, update:
```json
"subject-name": {
  "currentDay": N+1,
  ...
}
```

### Step 4: Update Memory / 更新记忆

If the agent has a memory system, update it with the subject's new progress.

### Step 5: Extract Concepts to Knowledge Base / 提取概念入库

**Only if `archiveDepth` = `full` and `knowledgeBase.tool` ≠ `none`.**

Follow the **Knowledge Base Rules** section below. If a custom `schemaPath` is configured, read that file first — its rules take priority over built-in defaults.

从当日课程提炼核心概念，严格按照下方「知识库规则」章节执行。如配置了自定义 schema 文件，先读取它——其规则覆盖内置默认。

**If no new concepts were introduced:** note this in the report / 如无新概念，在汇报中说明。

### Step 6: Report / 汇报 (output in configured language)

```
✅ Learning records updated. / 学习记录已更新。

  📚 Subject: [Subject Name]
  📍 Progress: Day [N] → Day [N+1]
  🆕 New concepts: [list, or "none"]
  📁 Archived to: {path}
  🧠 Knowledge base: [updated / no changes]
  ⚙️  Config updated / 配置已更新
```

---

## Post-Lesson Self-Verification Protocol / 课后自查协议（v1.0.1 新增）

> 🚨 **THIS IS A RED LINE. DO NOT CROSS IT.**
> 这是红线。不可越界。
>
> Every agent that teaches a lesson via this skill **MUST** self-verify all three layers below before telling the user "lesson complete" ("学完了"/"done"/etc). If any layer is missing, **you are NOT done.** There is no exception. There is no "I'll do it later." Fix the gap now.
>
> 每个使用此 skill 教课的 agent，在告诉用户"学完了"之前，**必须**自检以下三层。少一层就不是"学完了"。没有例外。没有"待会补"。现在修。

After every lesson (whether triggered via Scenario 2 or via the agent's own workflow), the agent MUST self-verify the following three layers before declaring the session complete:

### The Three-Layer Verification / 三层验证

| # | Layer / 层 | What to check / 检查内容 | How to verify / 验证方式 |
|:-:|-----------|------------------------|------------------------|
| 1 | 📁 **Learning Records** / 学习记录 | Learning log appended with new knowledge + quiz results; syllabus marked as complete | Read the last few lines of the log file; check syllabus for ✅ mark |
| 2 | 🧠 **Agent Memory** / 智能体记忆 | MEMORY.md or equivalent updated with current progress | Read the subject's progress line in memory |
| 3 | 📝 **Knowledge Base** / 知识库 | Each core concept has its own `.md` file with proper frontmatter, bilingual content, and wikilinks | List files in the subject's knowledge base folder; verify new files exist and are non-empty |

### Self-Check Mantra / 自查口诀

Before saying anything that means "done", mentally run this checklist:

```
1️⃣ D盘/Learning records → ✅ ?
2️⃣ Agent memory → ✅ ?
3️⃣ Knowledge base → ✅ ?
→ All three checked? NOW you can say "lesson complete."
```

### When to skip Layer 3 / 何时可跳过第三层

Only skip knowledge base archiving if:
- `archiveDepth` is set to `light` (not `full`), OR
- `knowledgeBase.tool` is set to `none`, OR
- The lesson was pure review with zero new concepts introduced

In all other cases, Layer 3 is mandatory.

### Failure Recovery / 故障恢复

If any verification fails:
1. **Do NOT tell the user the lesson is complete** — fix the gap first
2. If the gap cannot be fixed (e.g., missing path), report it to the user with a clear description
3. Record the failure in the learning log so the next session can catch up

**If the user catches you skipping a layer** (they will notice):
- Stop immediately. Do not argue. Do not defend.
- Fix the missing layer right there.
- Record this as a lesson learned — update your own rules (SOUL.md, TOOLS.md, etc.) to make it harder to skip next time.

### Multi-Agent Guarantee / 多智能体保障

This protocol is designed for environments where different agents may handle different sessions. Each agent is independently responsible for completing all three layers. Do not assume a previous agent already did it — verify.

---

## Knowledge Base Rules / 知识库规则（内置默认）

> ⚠️ If a custom `schemaPath` is configured, read that file before every concept extraction — its rules take priority over the defaults below.
> 如配置了自定义 schema 文件，每次提取概念前先读取它——其规则优先于以下默认。

When extracting concepts from a lesson, follow these rules strictly:
从课程提炼概念时，严格遵循以下规则：

### 1. One Concept = One File / 一个概念一个文件

- Each core concept gets its own `.md` file. Never bundle multiple concepts into one file.
- File name format: `{NN}-{ConceptName}.md` (e.g., `01-Derivative.md`, `01-导数.md`)
- Use a numbered prefix to maintain sort order within the folder.
- Place files in the appropriate subject folder under `{knowledgeBase.path}/`.

### 2. File Format / 文件格式

Every concept file must include:

```markdown
---
aliases:
  - ConceptName
  - 别名1
  - 别名2
---

# ConceptName / 概念名

> One-line summary. 一句话概述。

## Core Content / 核心内容
...

## Related / 关联
- [[path/to/related-concept|Related Concept]] — relationship description
```

- **YAML frontmatter with `aliases`** — list synonyms and translations for searchability
- Output language follows the user's configured `language` setting
- If `language` = `zh-en`, output bilingual (Chinese + English)

### 3. Naming & Linking / 命名与链接

**Obsidian (wikilink) mode:**
- Use `[[full/path/to/file|Display Name]]` format — full path from vault root, pipe (`|`) without spaces
- Always reference the numbered filename (e.g., `[[01-Derivative]]`, not `[[Derivative]]`)
- Cross-discipline links: `[[OtherFolder/SomeFile|Display]]`

**Plain Markdown mode:**
- Use standard relative links: `[Display Name](../folder/file.md)`

**Bidirectional linking / 双向链接:**
- If A links to B, also add a backlink from B to A (create or update B's file)
- Tag cross-discipline links with type hints: `💡 方法借鉴` (method reference), `💡 思维模型类比` (mental model analogy)

### 4. Duplicate Detection / 去重检查

Before creating any new file, check for existing content:

1. Search for files with the same or similar name (including `aliases` in frontmatter)
2. If an exact match exists → add a wikilink to it, do NOT create a duplicate / 已存在则不新建，直接引用
3. If partial overlap → enrich the existing file with new content, do NOT create a duplicate / 部分重叠则补充已有文件
4. If contradictory content found → mark `⚠️ 待确认` and flag to the user / 发现矛盾则标记待确认

### 5. Index & Outline Updates / 索引与总纲更新

If the knowledge base has an index file (e.g., `00_概念索引.md`) or subject outlines (e.g., `XX-XXX总纲.md`):

- Add new concepts to the index under the correct subject
- Update the subject outline to include new concept entries with correct wikilink paths
- Verify that outline links point to actual files on disk
- If the knowledge base has a link-checking script, run it after major updates

### 6. Post-Archive Verification / 归档后验证

After creating or modifying knowledge base files:

1. Verify all new wikilinks resolve to existing files
2. Check numbering consistency within the subject folder (no gaps or collisions)
3. Report any broken links or inconsistencies to the user

---

## Configuration Reference / 配置参考

### `.personal-tutor-config.json`

| Field | Type | Description |
|:------|:-----|:------------|
| `version` | string | Config schema version (`"1.0"`) |
| `learningRoot` | string | Absolute path to the learning directory / 学习资料根目录 |
| `knowledgeBase.tool` | string | `"obsidian"` / `"plain"` / `"notion"` / `"none"` |
| `knowledgeBase.path` | string | Absolute path to vault/notes root / 知识库路径 |
| `knowledgeBase.schemaPath` | string | (Optional) Path to custom knowledge base rules file / 自定义规则文件路径 |
| `archiveDepth` | string | `"light"` (log + syllabus + memory) or `"full"` (includes knowledge base + index) |
| `language` | string | `"zh"` / `"en"` / `"zh-en"` / `"auto"` |
| `subjects` | object | Keyed by subject name, each containing `currentDay`, `category`, `syllabusPath`, `logPath`, `status`, `startedAt` |

### Directory Structure / 目录结构 (after setup)

```
{learningRoot}/
├── {Category/分类}/
│   ├── {Subject Name/学科名}/
│   │   ├── syllabus.md
│   │   └── learning-log.md
│   └── {Another Subject}/
│       ├── syllabus.md
│       └── learning-log.md
├── {Another Category}/
│   └── ...
└── ...

{knowledgeBase.path}/
├── {Subject Name}/
│   ├── 01-concept.md
│   ├── 02-concept.md
│   └── ...
└── (existing vault structure preserved / 现有结构保留)
```

---

## Design Principles / 设计原则

1. **Progressive disclosure / 渐进展开** — Lightweight onboarding, fully optional deep features
2. **Tool-agnostic / 工具无关** — Works with Obsidian, plain folders, or no knowledge base at all
3. **Conversation-first / 对话优先** — The lesson happens in chat; the skill handles the paperwork behind the scenes
4. **Incremental / 增量式** — Each day builds on the last; the log and syllabus grow together
5. **Non-destructive / 非破坏性** — Never overwrite existing knowledge base content; always check for duplicates first
6. **Language-respecting / 语言自适应** — Follow the user's configured language for all generated content

---

## Common Edge Cases / 常见边缘情况

| Situation / 情况 | Handling / 处理方式 |
|:----------|:---------|
| User forgot which day they're on / 忘记学到哪了 | Read config → `currentDay`, confirm with user |
| User wants to skip ahead / 想跳过某天 | Update config to the new day, note in log |
| User restarted a subject from scratch / 重启学科 | Archive old log (rename with date suffix), create fresh files |
| Multiple subjects in one session / 同一会话多学科切换 | Process each archive command independently |
| Knowledge base tool is `none` / 未配置知识库 | Silently skip Steps 5-6 in Scenario 3 |
| Config file is corrupted/missing / 配置文件损坏或缺失 | Re-run onboarding; old learning files are preserved |
| Subject name has special characters / 学科名含特殊字符 | Sanitize for filesystem: replace `<>:"/\|?*` with `-` |
| **Agent skipped knowledge base update / Agent 漏了知识库归档** | **v1.0.1 新增**。This is the most common failure mode. Recovery: (1) Check if the subject folder exists at `{knowledgeBase.path}`; (2) Read the latest learning log to identify which concepts were taught; (3) Create/update `.md` files for each missing concept; (4) Run Post-Lesson Self-Verification Protocol; (5) This failure suggests the agent DID read the skill but skipped verification — after recovery, the agent should update its local rules (SOUL.md, TOOLS.md, etc.) to prevent recurrence. |