# Kelly Homework Coach

> Friendly elementary-school homework tutoring App-in-Skill. Use when the user invokes $kelly-homework-coach or /kelly-homework-coach, mentions 小学生作业辅导, homework photo tutoring, 拍照讲题, 作业答疑, 错题本, error notebook, mistake-book review, practice paper generation, exam paper analysis, parent/teacher review of AI explanations, or wants a child-friendly UI for step-by-step homework help with local review a…

- **Type:** Skill
- **Install:** `agentstack add skill-mr-kelly-skills-kelly-homework-coach`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mr-kelly](https://agentstack.voostack.com/s/mr-kelly)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mr-kelly](https://github.com/mr-kelly)
- **Source:** https://github.com/mr-kelly/skills/tree/main/skills/kelly-homework-coach
- **Website:** https://mr-kelly.github.io/skills/

## Install

```sh
agentstack add skill-mr-kelly-skills-kelly-homework-coach
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Kelly Homework Coach

## Overview

Use this skill as a child-friendly homework coaching desk for elementary students. The agent explains photographed questions, analyzes wrong answers, turns mistakes into a review notebook, and prepares practice papers; the local app gives students a warm study surface and gives parents/teachers a calm review desk for mistake analysis and paper planning.

Default interaction mode: App UI. Unless the user explicitly asks for chat-only handling, check onboarding/config, prepare or refresh the homework snapshot, start/reuse the local app with `app/start.sh`, and give the actual local URL. Use chat-only mode only when the user says `纯聊天`, `chat only`, `不要打开 UI`, or similar; in that mode use stable references such as `Question #1`, `Mistake #2`, and `Paper #1`.

## Boundary

- The skill may inspect uploaded homework photos, run OCR/vision reasoning through the active model, explain questions, identify mistakes, generate practice items, write local handoff files, and export local paper drafts.
- The app reads and writes local/provider handoff state only. It never calls AI, uploads a child's photo, contacts a teacher, publishes a paper, or mutates any external system.
- Child-facing output must be encouraging, step-by-step, and age-appropriate. Prefer hints and concepts over blunt answer dumping unless the user asks for the answer.
- Parent/teacher-facing analysis may be more diagnostic, but should avoid shame language. Treat the student as capable and learning.
- Student photos, names, school data, and answers are private education data. Never commit `config.local.json`, env files, `app/.data/`, exported papers, or raw uploaded images.

## First Run And Onboarding

On invocation, check `app/.data/onboarding.json` and private config readiness. If onboarding is absent/incomplete, start the app and guide setup before doing real work.

Private config priority:

1. `KELLY_HOMEWORK_COACH_CONFIG=/absolute/path/to/config.json`
2. `skills/kelly-homework-coach/config.local.json`
3. `~/.config/kelly-homework-coach/config.json`
4. `skills/kelly-homework-coach/config.example.json` as template only

This skill needs no secrets by default. If a future school LMS, OCR provider, or cloud storage connector is added, reference secrets by env var or provider Vault names only; never ask for passwords or API keys in chat or the browser.

Onboarding asks, turn by turn: student grade range, subjects in scope, language preference, parent/teacher review role, answer-reveal policy, allowed photo storage policy, default practice-paper length, and export preferences. When setup is complete and the user confirms, write `app/.data/onboarding.json`:

```json
{
  "completed": true,
  "completed_at": "ISO timestamp",
  "config_version": "1"
}
```

## Local App

Start the desk with:

```bash
skills/kelly-homework-coach/app/start.sh
```

The app uses local HTTP on `127.0.0.1`, preferring ports `3000` through `4000`, or `KELLY_HOMEWORK_COACH_UI_PORT` when set. `/api/state` reports `app: "kelly-homework-coach"`.

Required app surfaces:

- `#/student`: student study desk with photo/intake area, current question, gentle step-by-step explanation, hint ladder, answer confidence, and child-friendly next action.
- `#/student/`: question detail with original prompt text, student's answer, concept explanation, steps, checks, and "I understand" / "I still need help" controls.
- `#/mistakes`: mistake notebook with due-review chips, topic filters, root-cause analysis, similar practice prompt, and spaced-review status.
- `#/papers`: practice paper builder and paper list, including mistake-focused settings, estimated minutes, readiness status, and paper analysis.
- `#/review`: parent/teacher review queue with stable refs, workflow states (`needs_review` / `changes_requested` / `approved` / `done` / `blocked`), editable review notes, suggested actions, and approval/request-change/block decisions.
- `#/settings`: sanitized config, setup status, provider state, learning policy, answer-reveal rule, data-retention summary, language, and file paths. Never expose secret values or raw private config contents.

Demo mode:

- `?demo=student`, `?demo=mistakes`, `?demo=papers`, and `?demo=review` open deterministic mock scenes for visual review.
- `lang=en`, `lang=zh`, or `lang=zh-HK` forces UI chrome language. Demo content should be meaningfully localized when Chinese is selected.
- Deep links such as `/?demo=student&lang=zh-HK#/student` must work.
- Demo API responses never read or write files under `app/.data/`.

## File Contract

Read `references/homework-schema.md` before editing the app, scripts, or generated JSON.

- `app/.data/homework_snapshot.json`: student profile, questions, mistakes, papers, review items, metrics, activity log.
- `app/.data/decisions.json`: parent/teacher verdicts keyed by review id.
- `app/.data/agent_tasks.json`: queued `explain_again`, `generate_practice`, `revise_paper`, or `review_mistake` tasks for the agent.
- `app/.data/execution_report.json`: latest dry-run or apply results.
- `app/.data/provider_choice.json`: non-secret provider bootstrap choice.
- `app/.data/onboarding.json`: onboarding completion marker.
- `app/.data/agent.lock`: temporary lock while the skill writes; the review queue rejects `POST /api/decision` with HTTP 423 while it exists.

Validate with `scripts/validate_ui_schema.ts` before relying on a snapshot.

## Homework Photo Workflow

1. Ingest the student's photo or pasted problem text. If using vision/OCR, keep extracted text and cropped/raw images local unless the user explicitly approves a connector.
2. Identify subject, grade, topic, required answer type, and whether the student's current answer is correct, wrong, or uncertain.
3. Draft a child-facing explanation: one friendly summary, 2-5 short steps, one key concept, one self-check, and a next hint. Avoid long lectures.
4. If wrong, create or update a mistake item with root cause, misconception, fix strategy, similar practice prompt, and next review date.
5. Acquire `app/.data/agent.lock`, merge the snapshot, validate schema, release the lock, then send the user to `#/student` or `#/review`.

## Mistake Notebook Workflow

1. Group mistakes by topic, error type, and review due date; keep stable ids so repeated analysis updates the same mistake instead of duplicating it.
2. Use supportive language: "还差一步" / "try this check" rather than "careless" unless the evidence specifically supports a careless-slip label.
3. For each mistake, store a "how to fix next time" rule and a similar practice prompt. Do not store excessive raw photo content.
4. When the student reviews a mistake, update review history and next review date. If the student still struggles, enqueue an `explain_again` agent task.

## Practice Paper And Analysis Workflow

1. Build practice papers from target subject/topic, grade, difficulty mix, and recent mistakes.
2. Generate a paper plan first: title, question count, estimated minutes, topics, linked mistakes, and answer-key policy. Parent/teacher approval is required before export.
3. After a completed paper is analyzed, list all wrong questions with topic, root cause, concept gap, and recommended review sequence.
4. Export approved papers locally only. Do not send to school systems or messaging apps from this skill.

## Review And Agent Tasks Loop

1. Send parent/teacher users to `#/review`. Verdicts persist through `POST /api/decision` into `decisions.json` and update `agent_tasks.json` for requested changes.
2. Poll `app/.data/agent_tasks.json` for tasks created by `request_changes` or `@ai` notes. Redraft explanations, mistake cards, or paper plans, then return the item to `needs_review`.
3. Before executing anything, re-read decisions and run `node scripts/execute_decisions.ts` for a dry run. With `--apply`, it records local-only operations such as `add_to_mistake_book`, `mark_understood`, `queue_practice_paper`, and `export_paper_plan`.

## Safety Defaults

- Never shame the child. Avoid labels like "lazy", "stupid", or "careless" unless reframed as a fixable pattern with evidence.
- Never present uncertain OCR/vision as certain. If the photo is blurry, ask for a clearer image or parent/teacher confirmation.
- Do not generate high-stakes claims such as diagnoses, school placement decisions, or formal grades.
- Do not reveal a full answer before offering a hint path when the configured answer policy is `hint_first`.
- If snapshot schema, config, or decisions disagree, stop and reconcile before writing execution reports or exports.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mr-kelly](https://github.com/mr-kelly)
- **Source:** [mr-kelly/skills](https://github.com/mr-kelly/skills)
- **License:** MIT
- **Homepage:** https://mr-kelly.github.io/skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mr-kelly-skills-kelly-homework-coach
- Seller: https://agentstack.voostack.com/s/mr-kelly
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.