Zhizhi Math Coach

SKILL.md

---
name: zhizhi-math-coach
description: "Primary-school math coaching skill created to help my first-grade daughter Zhizhi: grade worksheet photos or wrong questions, track weak points and learning progress, explain concepts for parents and students, and generate printable PDF/HTML practice aligned with grade, semester, textbook, exam, and holiday plans."
---

# Zhizhi Math Coach

## Core Loop

Use a local evidence loop for every task:

1. Read local memory, curriculum, school calendar, progress, and relevant weak-point files before deciding.
2. Infer grade, semester, school phase, textbook volume, and exam/break window from local rules.
3. Accept completed paper photos, teacher-marked work, generated worksheets, or direct `question + student answer + correct answer`.
4. Grade only what is clear; mark uncertain handwriting or missing context as `need-confirmation`.
5. Compare mistakes with historical weak points before assigning causes.
6. Explain the correction in parent-friendly language, and include a shorter student-facing version when useful.
7. Generate short validation practice for the cause, not just the surface topic.
8. Update the mistake book, progress dashboard, weak-point records, memory, and next-practice suggestion only when evidence supports it.

## Expected Workspace

Use these paths in the user's personal learning project unless they provide different names. The project repository may be public or private; do not assume either.

- `memory/long-term.md`: stable student rules, parent preferences, school-entry year, textbook edition, grade overrides.
- `memory/short-term.md`: current observations, active priorities, pending checks.
- `memory/local-memory-rules.md`: read/write/promotion rules for memory.
- `curriculum/profile.md`: student grade, textbook edition, textbook volume, source links, and current scope.
- `curriculum/scope.md`: unit-to-knowledge-point map for the current textbook.
- `curriculum/progress.md`: school progress, learned/not-yet-learned topics, and exam scope.
- `curriculum/school-calendar.md`: China school-year, semester, midterm/final, winter/summer break, and local overrides.
- `knowledge-points/<topic-slug>.md`: parent explanation card, student summary, skills, common errors, validation tasks, and mastery evidence.
- `weak-points/<topic-slug>.md`: long-lived weak-point records.
- `mistakes/index.md`: mistake-book schema, semester ranges, review rules.
- `mistakes/school-mistakes.md`: school papers, weekly tests, official homework.
- `mistakes/system-mistakes.md`: worksheets generated by this system.
- `records/learning-progress.md`: dated progress dashboard.
- `records/YYYY-MM-DD-<source>-diagnosis.md`: one diagnosis per paper/photo batch/wrong-question batch.
- `worksheets/YYYY-MM-DD-<topic-slug>/worksheet-spec.json`: compact worksheet source.
- `worksheets/YYYY-MM-DD-<topic-slug>/worksheet.html`: child-facing printable worksheet.
- `worksheets/YYYY-MM-DD-<topic-slug>/worksheet.pdf`: child-facing printable PDF for direct file delivery.
- `worksheets/YYYY-MM-DD-<topic-slug>/answer-key.md`: answers, grading, and next-step rules.

If the personal learning project is not initialized yet, run the bundled initializer from the workspace root:

```bash
python3 {baseDir}/scripts/init_learning_workspace.py \
  --workspace . \
  --student-name <nickname> \
  --school-entry-year <YYYY> \
  --grade <一年级> \
  --semester <上学期|下学期> \
  --textbook-edition <人教版> \
  --textbook-volume <一年级下册>
```

The initializer creates missing files only by default. Use `--force` only when the parent explicitly wants to overwrite existing local templates.

## Recommended Model Capability

Prefer a frontier multimodal reasoning model for this skill. The model should support:

- image understanding for worksheet photos, handwritten answers, and teacher-marked papers;
- long-context reading across local `memory/`, `weak-points/`, `records/`, `curriculum/`, and worksheet files;
- reliable tool use and local file edits;
- structured JSON/text output for worksheet specs, diagnosis records, and progress updates;
- configurable reasoning effort.

Why this matters:

- Photo grading is common: parents will upload exercise sheets, teacher corrections, or handwritten answers. A text-only model cannot reliably read the question layout, child answer, correction marks, or geometry diagrams.
- Handwriting and low-quality images need uncertainty handling: the model must decide when to grade, when to mark `need-confirmation`, and when to ask for a clearer photo.
- Long-term learning follow-up needs context: weak-point repair depends on comparing current mistakes with `memory/`, `records/`, `mistakes/`, and `weak-points/` history.
- Worksheet generation needs structure: the skill writes compact `worksheet-spec.json`, deterministic HTML, answer keys, and progress records, so structured output reliability matters.
- Hard math tasks need reasoning: geometry, multi-step word problems, exam review planning, and transfer-failure diagnosis require more than shallow pattern matching.

Recommended settings:

- Default daily use: balanced reasoning, such as OpenAI `gpt-5.2` or a newer frontier GPT-5.x model with medium reasoning.
- Hard cases: use higher reasoning for multi-image grading, low-confidence handwriting, complex word problems, geometry, midterm/final review planning, or memory consolidation.
- Fast/simple tasks: use lower reasoning for reminders, checklist updates, or formatting existing records.
- Avoid small text-only models for grading photos, geometry diagrams, or updating long-term learning records.

## Trigger And Sync Boundary

This skill is triggered by the user's OpenClaw request, such as `$zhizhi-math-coach 批改...` or `$zhizhi-math-coach 出一张...`, while the working directory is the personal learning project.

Explicit GitHub advanced-setup trigger phrases include:

- `进阶：配置 GitHub 云同步`
- `进阶：开启 GitHub Pages 在线访问`
- `生成 GitHub Deploy key`
- `配置云端备份`
- `返回 SSH 公钥`
- `配置公开链接`

When these phrases appear, treat the request as advanced GitHub setup. Do not grade or generate a worksheet unless the user also asks for that. Run or suggest `prepare_github_deploy_key.py`, return only the SSH public key, and include this public guide URL:

`https://github.com/linzi007/zhizhi-math-coach-openclaw/blob/main/docs/github-advanced-setup.zh-CN.md`

The advanced setup reply must include:

- SSH public key copied only from `public-key-start` to `public-key-end`;
- guide URL above;
- GitHub path: `Settings -> Deploy keys -> Add deploy key`;
- permission instruction: enable `Allow write access`;
- next step: after the parent replies `已添加`, run `check_git_sync.py --workspace . --check-push`.

If the GitHub owner or repository name is missing and cannot be inferred from `origin`, ask for both in plain Chinese:

`请告诉我你的 GitHub 用户名和个人学习数据仓库名，例如 linzi007 / zhizhi-math-learning-data。`

Always treat the current workspace root as the personal learning project root for `memory/`, `weak-points/`, `mistakes/`, `records/`, `curriculum/`, `knowledge-points/`, `worksheets/`, and `site/`. The reusable skill repository only provides instructions, scripts, references, templates, and sanitized examples.

If the current workspace appears to be the reusable source repository `zhizhi-math-coach-openclaw` (for example it contains `docs/openclaw-release.md` and `examples/student-workspace/`), warn before writing student learning data. Do not warn merely because a personal workspace has an installed `skills/zhizhi-math-coach/` bundle from ClawHub. Only write student data into the source repository when the user explicitly says it is the intended personal learning workspace or the task is skill development with sanitized examples.

Do not assume background sync. Local files are changed by the current task only:

- grading or diagnosis may write `records/`, `mistakes/`, `weak-points/`, and evidence-backed `memory/` updates;
- worksheet generation may write `worksheets/<date-topic>/worksheet-spec.json`, `worksheet.html`, `worksheet.pdf`, and `answer-key.md`;
- publishing may write `site/` and `worksheets/<date-topic>/publish.json`.
- GitHub Pages setup may write `.github/workflows/pages.yml` when the parent has chosen a public repository, selected GitHub Actions as the Pages source, and asked OpenClaw to set up publishing.

When publishing, rebuild `site/index.html` as the full worksheet list from `worksheets/`, sorted by date descending. Include only public-safe metadata: date, practice status, title, child-facing file links, topic, grade, item count, and completion summary. Infer status from `worksheets/status.md` when available; do not expose answers or diagnosis details in `site/`.

PDF is the default worksheet delivery format. After worksheet generation, return or send `worksheet.pdf` first when it exists. If Chrome/Chromium is unavailable and PDF export was skipped, return the local `worksheet.html` path and mention that PDF export needs Chrome/Chromium.

GitHub sync and GitHub Pages are advanced cloud features, not required for normal use. If GitHub sync is configured, sync generated learning data and worksheet artifacts when requested or enabled. If a worksheet is generated in a workspace that already has public Pages mode configured (`.github/workflows/pages.yml`, GitHub Pages source set to Actions, and Git preflight passes), publish to Pages after the PDF is available only when the user needs a public link: run `publish_and_wait_pages.py`, wait for GitHub Actions deployment to finish, then reply with the PDF path/file, index URL, and worksheet URL. If the Actions run fails or times out, return the PDF/local paths, pushed commit if available, and Actions/setup guidance.

Do not run `git add`, `git commit`, or `git push` unless the parent explicitly asks to sync, publish, push, commit to GitHub, send a public link, or has enabled automatic Pages publishing for generated worksheets. When sync is requested, read `references/github-sync-authorization.md` first and run the bundled preflight before committing or pushing. Do not require GitHub CLI or provider-level token configuration; a repository-scoped SSH deploy key is the preferred setup. If authorization is missing, return the PDF/local file paths and setup guidance instead of treating generation as failed. If the personal repository is public, warn before committing sensitive learning records or answer keys unless the parent has explicitly accepted full public learning-data sync.

On the first meaningful reply in a personal learning workspace, use `references/openclaw-quickstart.md` for a short setup check focused on local workspace readiness and PDF delivery. Do not mention GitHub setup during ordinary grading or worksheet generation unless the parent asks for cloud sync, push, public links, Pages, or a publish preflight fails. When needed, explain that OpenClaw can generate a repository-specific public key, send it to the parent through Lark/Feishu when available, and the parent should add it in GitHub repository Settings -> Deploy keys with write access.

Skill resources are relative to `{baseDir}`:

- `references/grading-diagnosis-rubric.md`: grading and diagnosis fields.
- `references/progress-tracking.md`: record templates and status values.
- `references/relapse-handling.md`: how to handle repeated mistakes after repair.
- `references/curriculum-alignment.md`: textbook, China grade/semester, and copyright-safe curriculum alignment.
- `references/school-calendar.md`: China school-year, semester, exam window, and holiday phase rules.
- `references/knowledge-point-explanations.md`: parent explanation card and student summary rules.
- `references/worksheet-strategies.md`: supported paper-generation strategies and confirmation questions.
- `references/worksheet-generation.md`: low-token worksheet workflow.
- `references/word-problem-variant-design.md`: how to design non-shallow word-problem variants.
- `references/complex-problem-generation.md`: complex word-problem and review safeguards.
- `references/geometry-generation.md`: deterministic SVG geometry rules.
- `references/automation-openclaw.md`: scheduled reminders, channels, and automation boundaries.
- `references/openclaw-quickstart.md`: first-use checklist, common prompts, Pages-ready checklist, and ruleset summary.
- `references/github-pages-publishing.md`: public child-facing PDF/HTML worksheet publishing rules.
- `references/github-sync-authorization.md`: GitHub SSH/token authorization, preflight checks, and sync boundaries.
- `references/worksheet-standards.md`: child-facing printable worksheet rules.
- `references/student-profile-template.md`: starter profile format.
- `scripts/generate_worksheet.py`: generate worksheet HTML, student-facing PDF, and answer key from JSON.
- `scripts/check_git_sync.py`: preflight whether the current machine can reach and push the personal GitHub repository.
- `scripts/prepare_github_deploy_key.py`: generate a repository-scoped SSH deploy key and public-key setup instructions for GitHub Deploy keys.
- `scripts/setup_github_pages_workflow.py`: create `.github/workflows/pages.yml` for publishing `site/` through GitHub Actions.
- `scripts/init_learning_workspace.py`: initialize a personal learning repository after the skill is installed.
- `scripts/validate_worksheet_spec.py`: validate worksheet JSON without writing outputs.
- `scripts/publish_html_site.py`: publish child-facing worksheet HTML/PDF into a GitHub Pages `site/` directory.
- `scripts/publish_and_wait_pages.py`: publish `site/`, commit/push public-safe files, wait for GitHub Actions Pages deployment, and print ready URLs.
- `assets/worksheet/question-types.json`: reusable worksheet item types.
- `assets/worksheet/a4-single.html`: printable HTML template.

## Before Grading

Read:

1. `memory/local-memory-rules.md`
2. `memory/long-term.md`
3. `memory/short-term.md`
4. `curriculum/school-calendar.md`
5. `curriculum/profile.md`
6. `curriculum/progress.md`
7. `references/grading-diagnosis-rubric.md`
8. `references/progress-tracking.md`
9. `references/relapse-handling.md`

Then create or update one diagnosis record under `records/`. Add every wrong or uncertain item to the correct mistake book. Keep school mistakes and system-generated worksheet mistakes separate.

## Before Explaining A Knowledge Point

Read the relevant `knowledge-points/<topic-slug>.md` when it exists. If it does not exist, create the explanation in the same structure and recommend saving it in the user's personal learning project:

1. Parent explanation script.
2. Student-facing short version.
3. Doing tips.
4. Common errors and quick checks.
5. Mastery evidence: can explain, can do same-structure items, can do variants, and can still solve after spacing.

Do not use long textbook excerpts. Use textbook scope and terminology, then explain in original words.

## Before Creating Practice

Read:

1. `memory/local-memory-rules.md`
2. `memory/long-term.md`
3. `memory/short-term.md`
4. `curriculum/school-calendar.md`
5. `curriculum/profile.md`
6. `curriculum/scope.md`
7. `curriculum/progress.md`
8. The relevant `weak-points/*.md`
9. The relevant `knowledge-points/*.md`
10. `references/worksheet-strategies.md`
11. `references/worksheet-standards.md`
12. `references/worksheet-generation.md`
13. `references/progress-tracking.md`

If the parent only says "出一张练习卷", confirm purpose, content range, length, and output format before generating. If they say "按最近情况出", use a mixed maintenance set weighted by recent mistakes, active weak points, and due spaced reviews.

For word problems, also read `references/word-problem-variant-design.md` and `references/complex-problem-generation.md`.

For geometry, also read `references/geometry-generation.md`; generate structured `geometry_spec` and deterministic SVG/HTML, not free-form AI images.

Prefer the low-token workflow:

```bash
python3 {baseDir}/scripts/validate_worksheet_spec.py \
  worksheets/YYYY-MM-DD-topic/worksheet-spec.json

python3 {baseDir}/scripts/generate_worksheet.py \
  worksheets/YYYY-MM-DD-topic/worksheet-spec.json
```

The generator writes `worksheet.html`, `worksheet.pdf` when Chrome/Chromium is available, and `answer-key.md`. Return or send `worksheet.pdf` as the primary worksheet artifact.

If the workspace has public Pages mode configured and the parent accepts public worksheet links, publish only the child-facing worksheet HTML/PDF and wait for deployment:

```bash
python3 {baseDir}/scripts/publish_and_wait_pages.py \
  worksheets/YYYY-MM-DD-topic \
  --workspace <personal-learning-workspace> \
  --base-url https://<github-user>.github.io/<repo>
```

If the parent wants a local-only preview or GitHub sync is not ready, publish local `site/` files without pushing:

```bash
python3 {baseDir}/scripts/publish_html_site.py \
  worksheets/YYYY-MM-DD-topic \
  --workspace <personal-learning-workspace> \
  --base-url https://<github-user>.github.io/<repo>
```

When Pages auto-publishing succeeds, reply with the PDF path/file, Pages index URL, and worksheet URL. Otherwise reply with file paths, item count, target weak point, and setup guidance for publishing. Do not paste full worksheet HTML or full answer keys unless asked.

## Teaching Defaults

- Use concise Chinese for parent-facing output.
- Start from meaning, drawing, counters, or place value before formulas when understanding is fragile.
- Ask the child to say the rule in plain language before writing the equation.
- Keep one main diagnostic target per short practice.
- If the student can answer correctly but slowly, diagnose fluency separately from understanding.
- Do not turn handwriting difficulty into a math test. Prefer circling, ticking, matching, or printed choices for classification.
- Use textbooks or curriculum references for scope, but create original targeted practice.
- When a parent says a repeated application model is already understood, switch to small mixed variants that test transfer.

## China School Calendar Defaults

Default semester rule:

- School year starts on September 1 and ends the next August.
- September 1 to January 31: first semester.
- February 1 to August 31: second semester.
- Winter break and summer break are local overrides, not fixed national dates.
- Midterm and final windows must be configurable per school.

If `school_entry_year: 2025`, the date `2026-05-18` is normally `一年级下学期`. Still check local overrides and actual school progress before deciding scope.

## Mistake Handling

Every wrong or uncertain item should include:

`date / school year / grade / semester / term phase / source type / source file / item number / question / student answer / correct answer / error type / likely cause / related knowledge point / related weak point / relapse judgment / re-practice status / follow-up`.

For review before midterms or finals, filter by semester first, then group by weak point, recurrence, and `re-practice status`.

## Relapse Handling

If a similar mistake appears after a weak point was marked `understood`, `consolidating`, or `mastered`, do not create a new isolated weak point. Decide whether it is:

- `relapse`: same cause failed again.
- `transfer-failure`: familiar form works, changed wording or mixed context fails.
- `spaced-forgetting`: the prior repair faded after a gap.
- `one-off-slip`: isolated error with nearby evidence of mastery.

Update the old weak-point record with the new evidence and choose practice based on the recurrence type.

## Worksheet Strategies

Supported strategies:

- `wrong_question_variant`: turn an existing wrong question into meaningful variants.
- `weak_point_drill`: focus one weak point.
- `exam_mistake_review`: midterm/final review weighted by real mistakes.
- `relapse_repair`: repair relapse, transfer failure, or spaced forgetting.
- `spaced_review`: small due review for old weak points.
- `transfer_check`: changed wording/scenario/condition order.
- `post_explanation_check`: 3 to 6 questions after explanation.
- `diagnostic_probe`: separate concept, reading, modeling, calculation, and checking causes.
- `mixed_maintenance`: current unit plus old weak points plus fluency.
- `fluency_speed`: facts and speed when understanding is already stable.
- `contrast_discrimination`: similar-looking items with different models.
- `geometry_drill`: deterministic geometry items from structured specs.

## Automation Boundary

Scheduled OpenClaw tasks should default to reminders and suggestions:

- Daily 20:30 Asia/Shanghai: due practice, pending uploads, stale short-term observations.
- Sunday 20:00 Asia/Shanghai: weekly progress review and next-week suggestions.
- End of semester: summary and holiday review pool.
- Winter/summer break: weekly review suggestions.

Do not let scheduled tasks automatically change weak-point status, memory, or generate new worksheets unless the parent explicitly asked for that behavior.

Feishu notifications should prefer GitHub Pages worksheet links when configured; keep answer keys and diagnosis records outside published `site/` output.

## Output Rules

When generating worksheets:

- Keep `worksheet.html` child-facing and answer-free.
- Generate and return `worksheet.pdf` first when available; it is the direct print/share artifact.
- Keep answers, grading labels, explanation notes, and reassessment rules in `answer-key.md`.
- Only child-facing `worksheet.html` and `worksheet.pdf` may be published to GitHub Pages. Do not publish answer keys, records, memories, weak-point histories, student photos, or textbook files.
- Use `worksheet-spec.json` as the source of truth.
- Add new stable item types to `assets/worksheet/question-types.json` and `scripts/generate_worksheet.py`.
- Include name/date/time/score fields and enough working space.
- Prefer clarity and targeted diagnosis over forcing exactly one A4 page.
- Complex word problems and geometry items must include answer details and review status.

When grading:

- Lead with confirmed mistakes and high-confidence causes.
- Separate reading, modeling, calculation, expression, and checking errors.
- Use `confidence: high / medium / low`.
- For low-confidence causes, give 1 to 2 quick verification questions.
- Group repeated errors by cause and teach the cause once.