Optimize resource

Optimize Resource Skill

This skill helps a teacher make a specific resource better for students, based on evidence of how it actually played out: where students got confused, which quizzes they failed, what wrong answers they gave, and what feedback they left. It produces concrete, evidence-backed content suggestions — and only changes the resource if the teacher explicitly says so.

Scope — read this carefully:

• ✅ In scope: the resource's content — wording/clarity of sections, quiz questions/answers/hints, images and visuals, ordering, missing context, length/pacing of a step.
• ❌ Out of scope: the prompt template, model, voice, or turn-detection settings. Those are platform-level and a teacher can't change them. If a problem is clearly about delivery (e.g. the bot was slow to respond), say so and note it's not something a content edit fixes.
• 🚫 Never auto-edit. Always present suggestions first. Only call writing tools after the teacher explicitly approves a specific change.

Instructions for Claude

0. Preflight

Verify the MCP server is connected by calling list_resources(pageSize: 1). If it errors, tell the user the Beau MCP server isn't connected and stop.

1. Pick the resource

Ask which resource to optimize (name, or let them pick from list_resources). Resolve to a resourceId.

2. Gather the evidence

• get_resource(resourceId) — the current content (markdown, quizzes, media). You need this to ground every suggestion in what's actually there.
• get_resource_insights(resourceId) — aggregate signals across all attempts:
  • completion + score (avg/median),
  • per-quiz first-attempt pass rate, ever-correct rate, avg attempts, and most common wrong answers,
  • feedback themes (👍/👎, issue tags, comments),
  • attemptsToReview: progress ids (lowest scores first), each with the resourceVersion it ran on,
  • currentVersionId: the resource's latest version — compare to each attempt's resourceVersion to spot evidence from since-edited content.
• get_resource_version(resourceId, versionId) — read-only: the exact content a run used. Use it when an attempt's resourceVersion ≠ currentVersionId to see what actually ran vs the current resource.
• get_transcript(progressId) on a few of the lowest-scoring attemptsToReview (e.g. 3–5) — read the qualitative story: where students hesitated, asked "what?", said they couldn't see something, or went off track. The transcript is a timestamped, interleaved log of bot/student messages, «MEDIA shown», «QUIZ shown», and answers — so you can see when confusion happened relative to a media/quiz.
  • Prefer real attempts for learning signals; test attempts are fine for spotting broken content (a confusing quiz is confusing regardless).

3. Diagnose (tie every finding to evidence)

Look for, and cite the signal for, each:

Signal	Likely content problem
Quiz with low first-attempt pass rate + a clustered common wrong answer	Ambiguous question wording, a misleading/duplicate option, or a wrong/over-strict expected answer; weak or missing hint.
Students reference something they "can't see" / confusion right after a section	A concept needs an image/visual, or the explanation before it is unclear.
Repeated "I don't get it" / re-asking on the same step	That section needs rewording, a concrete example, or splitting into smaller steps.
👎 feedback + issue tags / comments	Read them literally; they often name the problem.
Long section with drop-off / low completion	Trim or split; front-load the point.

4. Reconcile against the CURRENT resource (critical)

The teacher edits the current resource, but your evidence comes from past runs that may have used older content. Don't suggest a fix they've already made.

• For each finding, check the attempt's resourceVersion against currentVersionId.
  • Same → the evidence reflects current content; suggest directly.
  • Different (content edited since) → read what actually ran with get_resource_version(resourceId, resourceVersion) and compare to the current resource (get_resource). Only suggest a change if the problem still exists in the current content. If the relevant section/quiz has already changed, drop the suggestion or flag it: "this confused students on v5, but you've since edited that section — confirm it still applies."
• Prefer current-version evidence; treat older-version signals as weaker and always re-validate against current content before proposing an edit.
• Note: per-quiz stats pool attempts across versions (a quiz id is stable even if reworded), so a pass-rate that spans an edit is muddy — say so rather than over-trusting it.

5. Suggest (always first)

Present a short, prioritized list. For each: what to change, where (section/quiz id), why (the evidence — a pass rate, a wrong-answer cluster, a transcript quote, and which version it came from), and the proposed new text/answer/hint or media. Be specific enough that the teacher can say yes/no.

6. Offer to apply — only on explicit approval

Ask which suggestions to apply. For each approved one, use the authoring tools:

• Content/markdown → update_resource.
• Quiz wording/answers/hint → update_quiz.
• New illustration → create_visual / create_image / generate_image, then reference it in the content. Apply only what was approved; never bundle in unapproved changes. After applying, summarize exactly what changed and suggest the teacher re-test the resource.

Boundaries

• Suggest-then-apply, never auto-apply.
• Don't invent signals — if there are too few attempts (attempts.total is small), say the evidence is thin and suggest cautiously.
• Keep delivery/prompt/model concerns out; redirect those to a platform admin.