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.
1---2name: optimize-resource3description: Help a teacher improve a RESOURCE by analyzing how students actually experienced it — transcripts, quiz pass rates, common wrong answers, and feedback — then suggesting concrete content edits. Suggests first; only applies changes the teacher explicitly approves. Does not touch prompts or model config.4---56# Optimize Resource Skill78This 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.910**Scope — read this carefully:**11- ✅ 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.12- ❌ 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.13- 🚫 **Never auto-edit.** Always present suggestions first. Only call writing tools after the teacher explicitly approves a specific change.1415## Instructions for Claude1617### 0. Preflight18Verify 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.1920### 1. Pick the resource21Ask which resource to optimize (name, or let them pick from `list_resources`). Resolve to a `resourceId`.2223### 2. Gather the evidence24- **`get_resource(resourceId)`** — the current content (markdown, quizzes, media). You need this to ground every suggestion in what's actually there.25- **`get_resource_insights(resourceId)`** — aggregate signals across all attempts:26 - completion + score (avg/median),27 - per-quiz **first-attempt pass rate**, **ever-correct rate**, **avg attempts**, and **most common wrong answers**,28 - feedback themes (👍/👎, issue tags, comments),29 - `attemptsToReview`: progress ids (lowest scores first), each with the **`resourceVersion`** it ran on,30 - **`currentVersionId`**: the resource's latest version — compare to each attempt's `resourceVersion` to spot evidence from since-edited content.31- **`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.32- **`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.33 - Prefer **real** attempts for learning signals; test attempts are fine for spotting broken content (a confusing quiz is confusing regardless).3435### 3. Diagnose (tie every finding to evidence)36Look for, and cite the signal for, each:37| Signal | Likely content problem |38|--------|------------------------|39| 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. |40| 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. |41| Repeated "I don't get it" / re-asking on the same step | That section needs rewording, a concrete example, or splitting into smaller steps. |42| 👎 feedback + issue tags / comments | Read them literally; they often name the problem. |43| Long section with drop-off / low completion | Trim or split; front-load the point. |4445### 4. Reconcile against the CURRENT resource (critical)46The 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.47- For each finding, check the attempt's **`resourceVersion`** against **`currentVersionId`**.48 - **Same** → the evidence reflects current content; suggest directly.49 - **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."50- Prefer current-version evidence; treat older-version signals as weaker and always re-validate against current content before proposing an edit.51- 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.5253### 5. Suggest (always first)54Present 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.5556### 6. Offer to apply — only on explicit approval57Ask which suggestions to apply. For each approved one, use the authoring tools:58- Content/markdown → **`update_resource`**.59- Quiz wording/answers/hint → **`update_quiz`**.60- New illustration → **`create_visual`** / **`create_image`** / **`generate_image`**, then reference it in the content.61Apply **only** what was approved; never bundle in unapproved changes. After applying, summarize exactly what changed and suggest the teacher re-test the resource.6263## Boundaries64- Suggest-then-apply, **never auto-apply**.65- Don't invent signals — if there are too few attempts (`attempts.total` is small), say the evidence is thin and suggest cautiously.66- Keep delivery/prompt/model concerns out; redirect those to a platform admin.
beau-education