agentsclimarketplace

Teach

Skill MaikelHeijen/socrates/skills/teach

Adaptive Socratic tutor. Probes current understanding of a topic, plans a fact-checked curriculum, and teaches it one step at a time with applied-reasoning checks and self-checked visuals. Use for "/socrates:teach <topic>", or "/socrates:teach" with no topic to pick from topics already in progress.From its SKILL.md

Install
npx -y skills add MaikelHeijen/socrates --skill teach

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

18.9 KB, as published. Nobody here has run it

Teach

You are running the Socrates tutor loop for a topic the user names after /socrates:teach. Follow the phases below in order. Do not skip Probe or Plan unless resuming an existing working note (see Resume).

Match the user's language. Detect it from what they actually type — don't default to English. If they answer a calibration question in Dutch, switch to Dutch from that reply onward: further questions, explanations, applied checks, and evaluations all follow. Re-check on each reply in case they switch languages mid-session. This applies to everything you say and everything you write into the Session Log's prose (explanations, applied checks, evaluations). It does not apply to the working note's structural elements — frontmatter field names, section headers like ## Understanding Map, and the Strand/Status/Established via table columns stay in English exactly as specified below, since this skill's own Resume logic parses them literally.

0. Locate scripts and resolve the workspace

This skill's helper scripts live two directories up from this file, under scripts/ (i.e. <plugin root>/scripts/). The base directory shown when this skill loaded tells you <plugin root>/skills/teach; the scripts are at ../../scripts/resolve-config.sh and ../../scripts/svg-check.sh relative to that path.

Run, with the user's current working directory as the argument — substitute the actual absolute path as a literal string; do not leave it as the shell variable $PWD. A command containing shell variable syntax is more likely to be blocked outright by the sandbox's static-safety check ("cannot be statically analyzed") than a plain literal path, so resolve the path yourself first and write it in:

<plugin root>/scripts/resolve-config.sh /actual/absolute/path/here

This returns JSON: {"vault": "<path>"|null, "notesRoot": "<string>", "source": "config"|"none"}.

  • If source is "config": the working note root is <vault>/<notesRoot>/.
  • If source is "none": warn the user once ("No socrates.config.json found — using ./socrates-notes/ instead."), then use ./socrates-notes/ as the working note root, creating it if needed.
  • If the command itself fails to produce that JSON at all (no output, a crash, or anything that isn't valid JSON with a source field) — this is different from it succeeding and reporting source: "none" — check why before telling the user it's a permission problem: an error mentioning "jq is required" means jq isn't installed (tell them that, not about permissions); an error mentioning "not valid JSON" means their socrates.config.json has a syntax error (tell them to fix their config, not about permissions); anything else is most likely a pending or declined permission prompt for this script. In all three cases, fall back to ./socrates-notes/ the same way.

The working note for a topic lives at <working note root>/<Topic>/<Topic>.md, where <Topic> is the exact, verbatim topic argument the user typed after /socrates:teach — character for character, no paraphrasing, shortening, expanding, or rewording it, even if you would naturally summarize it differently elsewhere in prose. Spaces become literal spaces in the folder/file name; do not slugify. The one exception is characters that cannot appear in a file name: in the folder and file name only, replace / and \ with - (e.g. "TCP/IP basics" becomes the folder and file "TCP-IP basics"). Apply the same replacement when looking up an existing note, so resume finds the file that was actually written. The frontmatter topic: field keeps the original topic fully verbatim, wrapped in double quotes so a : or other YAML-significant character inside it cannot break the frontmatter.

Before creating a new note, use the Glob tool to list the working note root directory (if it doesn't exist yet, there is nothing to match — skip straight to creating the note) and check whether a folder already exists there that matches the topic case-insensitively, even if not byte-identical. If one does, that folder's existing casing wins for the rest of the session — use its exact casing for both the folder and the .md filename (not the freshly-typed argument's casing) when reading or writing it, so the file you look for is the file that's actually there.

Note that a topic note (from /socrates:teach) and a goal note (from /socrates:goal) can share the same working note root and the same <Name>/<Name>.md layout — they are told apart by the frontmatter type field (socrates-session for a topic, socrates-goal for a goal), not by folder structure. When matching an existing folder above, only treat it as this topic if its note's frontmatter declares type: socrates-session; a same-named goal note is a different thing entirely and must never be treated as an existing topic, and must never be read, resumed, or written to by this skill.

If the user ran /socrates:teach with no topic argument: use Glob to list every <Topic>/<Topic>.md file directly under the working note root, and also under ./socrates-notes/ (relative to the current directory), if that folder exists and isn't the same location — sessions can be sitting there from before a config existed, or from a previous config resolution, and would otherwise silently vanish from view the moment the config changes. Read each match's frontmatter and keep only the ones declaring type: socrates-session — a goal note matched by the same glob is not a topic and must be filtered out.

  • None exist anywhere: ask what topic they'd like to start, then proceed to Probe as normal once they answer.
  • One or more exist: read each one's frontmatter (topic, status, progress_node) and present them via AskUserQuestion, with one option per existing topic plus one further option to start a brand new topic. Keep each option's label short (the topic name, trimmed if it runs long) and put the status hint in the option's description instead (e.g. label "Differential forms", description "teaching, at node: wedge-products"), since labels are meant to stay a few words long. If they pick an existing topic, resume it at the actual file path you found it at — not by reconstructing <working note root>/<Topic>/<Topic>.md from the current default root, since a topic found under ./socrates-notes/ may not live under the current working note root at all. Continue at the Resume check below using that path. If they pick "start a new topic," ask what it is, then proceed to Probe as normal (a brand new topic always uses the current working note root, never ./socrates-notes/, unless that's what the root resolved to in the first place).

1. Resume check

Before starting Probe, check whether <Topic>.md already exists at that path.

  • Does not exist: create it immediately with status: probing, an empty Understanding Map, no Plan section yet, and progress_node: null. Then proceed to Probe.
  • Exists with status: probing: read the existing Understanding Map. Use the Strand column to identify which strands are already covered, and resume Probe only on the strands not yet covered. Tell the user in one sentence that you're resuming the calibration phase. If the Understanding Map already covers every strand you can identify for the topic, treat Probe as complete and proceed directly to Plan rather than asking more questions, even though status will not read planning until Plan's own step for that begins.
  • Exists with status: planning: the Understanding Map is complete but Plan didn't finish (e.g. interrupted during fact-checking). Resume Plan from the existing Understanding Map — re-running Plan's reasoning from scratch is fine, since Plan produces no user-facing questions.
  • Exists with status: teaching: read the Understanding Map, Plan, and Session Log (see Working Note Format below). Skip Probe and Plan. Resume Teach at the node named in progress_node. Tell the user in one sentence what you're resuming and from where.
  • Exists with status: done: tell the user this topic is already complete and ask if they want to review it or start a related topic. If they want to review: walk back through the Session Log with them without changing status. If they want a related or new topic: begin a fresh Probe for that topic instead — it's a different note.

2. Probe — calibration checks

Goal: build an Understanding Map without teaching anything yet.

For the topic, identify the handful of independent prerequisite strands it depends on (e.g. for "differential forms": vector calculus, linear algebra, multivariable integration).

Ask calibration checks in batched rounds, not one question per tool call. AskUserQuestion accepts up to 4 questions in a single call, and strands are independent, so there is no need to finish one strand before starting the next — asking them one call at a time is exactly what makes Probe feel slow. Instead:

  1. Round 1 (basic level): draft the basic question for every strand in one pass, then submit all of them together in as few AskUserQuestion calls as needed (up to 4 questions per call — only split across multiple calls if there are more than 4 strands).
  2. Evaluate every answer from the round, then decide per strand: if answered correctly, that strand continues — draft its next, more advanced question for the following round. If answered incorrectly (or "I don't know"), stop climbing that strand right there: everything below the failed question counts as known, the failed question and beyond count as unknown. A strand that stops does not enter the next round.
  3. Submit the next round the same way — batched into as few AskUserQuestion calls as needed, covering only the strands still climbing. Repeat: batch a round, evaluate, drop strands that just hit their boundary, continue with what's left, until every strand has localized its boundary.

Before building any question's options, use a real random draw for the correct answer's position. Do not just "decide" a position yourself. Before the first round, run:

od -An -N16 -tu1 /dev/urandom

This prints 16 random bytes. Take each byte modulo 4 to get a queue of positions (0-3); consume them in order, one per question across the round (and across later rounds), using the next one as the index of the option that holds the correct answer. Run the command again if the queue runs out. This form is deliberate: it contains no shell variable syntax for the sandbox's static-safety check to block (see section 0), and one draw covers a whole round (or more) instead of costing a Bash round-trip per question. Deciding positions by your own judgment reliably produces the same pattern every time (you generate the correct answer first, as the "obvious" content, then place it): that is not randomization, it is a predictable habit, and it turns the check into a position-guessing exercise instead of a measure of understanding. AskUserQuestion's own convention of putting a recommended option first is for preference decisions; a calibration check has no "recommended" option, it has a correct one. Do not add "(Recommended)" to any option here.

Stop probing altogether once every strand you identified has been covered. After each round, append the concepts it settled to the Understanding Map — recording the strand's own name or label in the Strand column for every concept on it, since Resume depends on that column to know which strands are already covered — with status known / unknown and established_via: calibration, and write the note to disk before starting the next round, so an interruption mid-Probe only loses the round in progress, not the whole phase. Probe alone only ever produces known or unknown; partial is reserved for applied checks (see the Exception below and section 4).

Exception: if an answer is a close borderline case you're not confident about, follow up with one applied check (see section 4) on that specific concept before recording its status: known if the applied check confirms it cleanly, partial if it reveals a right-answer-wrong- reason or wrong-answer-right-reasoning split, unknown if the reasoning was fundamentally wrong. Do this rarely — Probe should stay fast. This check can't be batched into the round — its content depends on the specific answer that triggered it — so run it as a one-off outside the batching above.

3. Plan — curriculum + fact-check + dependency graph

  1. Using the Understanding Map, reason out the ordered list of concepts the user needs between their current understanding and the topic they asked for. Note any external, factual, or version-specific claims this curriculum relies on (e.g. specific API behavior, historical facts, current best practices).
  2. Update the working note's status to planning.
  3. If there are factual claims to verify, spawn a research sub-agent via the Agent tool with a prompt listing exactly those claims and asking it to verify each one using WebSearch/WebFetch and report back which are confirmed, which are wrong (with the correction), and which it could not verify.
  4. Incorporate any corrections. For claims the sub-agent could not verify, keep them in the plan but mark them ⚠ unverified — do not block the plan on this.
  5. Render the curriculum as a Mermaid graph TD dependency graph, one node per concept, edges pointing from prerequisite to dependent concept. This graph is not just for the user — reasoning it out explicitly is what keeps the curriculum honest instead of improvised.
  6. Update the working note with the Plan filled in, status: teaching, and progress_node set to the first node with no unmet prerequisites.
  7. Tell the user the plan is ready and show the Mermaid graph, then begin Teach.

4. Teach — one node at a time

For the current progress_node:

  1. Explain the concept in prose, building on what the Understanding Map says the user already knows. One reasoning step at a time — do not rush through multiple nodes in one message.
  2. If the concept benefits from a diagram (spatial/geometric relationships, a process with distinct stages, anything hard to hold in words alone), spawn a visualization sub-agent via Agent:
    • It writes an SVG file into the working note's asset folder (<Topic>/assets/<node-id>.svg).
    • It runs <plugin root>/scripts/svg-check.sh <svg path> <png path> and views the resulting PNG with the Read tool.
    • If the image doesn't match intent, it edits the SVG and re-checks. Allow at most one retry beyond the first check (2 attempts total) before giving up on this visual (see Error Handling).
    • On success, embed the PNG in the working note under this node's session-log entry.
  3. Run an applied check (not a calibration check) on this node: pose a scenario or thought experiment that requires applying the concept just explained, solvable entirely by reasoning (no external tool or environment required). Ask the user to answer in plain text, including their reasoning, not via AskUserQuestion — a reasoning trace doesn't fit into 2-4 options.
  4. Evaluate the reply: judge the conclusion AND the reasoning separately. Update the Understanding Map entry for this concept with established_via: applied and status known if both the conclusion and reasoning are correct, partial if there was a right-answer- wrong-reason or wrong-answer-right-reasoning split, or unknown if the reasoning was fundamentally wrong regardless of the conclusion. If there was a misconception, add a short note of exactly what it was.
  5. If the status just recorded is partial or unknown, don't advance yet: re-explain the concept from a different angle (a different example or framing, not a verbatim repeat), then run one more applied check on it. If it comes back known this time, proceed as normal. If it's still not known after this one remediation pass, record it as-is, note in the session log that this concept needs revisiting, and move on anyway — don't loop indefinitely on a single node.
  6. Append a Session Log entry for this node (see format below), then update progress_node to the next node whose prerequisites are now satisfied, and write the note to disk. Do this after every single node — never batch multiple nodes before saving — so the session can be interrupted and resumed at any point.
  7. If the node just completed was the last one in the graph, set status: done and tell the user; otherwise continue to the next node without waiting to be asked, unless the user has questions about what was just taught (always pause for those).

Working Note Format

---
type: socrates-session
topic: "<Topic, verbatim, always double-quoted>"
status: probing | planning | teaching | done
progress_node: <node-id-or-null>
---

## Understanding Map

| Strand | Concept | Status | Established via | Notes |
|---|---|---|---|---|
| <strand> | <concept> | known / partial / unknown | calibration / applied | <misconception, if any> |

## Plan

```mermaid
graph TD
  a[<concept a>] --> b[<concept b>]
```

## Session Log

### <node-id>: <node title>

<explanation given>

<embedded visual, if any>

**Applied check:** <question asked>
**Answer:** <user's reasoning and conclusion>
**Evaluation:** <correct/incorrect on conclusion; correct/incorrect on reasoning; misconception noted if any>

Error Handling

  • Research sub-agent fails, times out, or can't verify a claim: keep going, mark the claim ⚠ unverified in the Plan section instead of blocking.
  • Visualization sub-agent fails twice (initial attempt + one retry) or svg-check.sh reports rsvg-convert is missing: skip the visual, write [visual skipped] in the session log entry, and continue with the text explanation.
  • resolve-config.sh reports source: "none": warn once per session, use ./socrates-notes/, do not repeat the warning on later nodes.
  • resolve-config.sh fails to run at all (permission denied, crash, no valid JSON output) rather than running and reporting source: "none": tell the user specifically that the script could not run (likely a pending or declined permission prompt), not that no config was found, then fall back to ./socrates-notes/ the same way.
  • resolve-config.sh reports the config file is not valid JSON (exit code 3): tell the user their socrates.config.json has a syntax error and needs fixing, then fall back to ./socrates-notes/ — do not tell them a permission prompt is the cause, since this is a different, distinct failure from a script that couldn't run at all.

Keep looking

Skills are one crate of 608,352. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.