SKILL.md

name	doceo
description	Turn anything the user wants to learn into a short, visual, plain-language teachable artifact (one HTML lesson page + a markdown lesson note), calibrated to what they already know and improving with every use. Use when the user runs /doceo, says "teach me X", "I don't understand X", "explain this simply", "make this teachable", or is clearly drowning in a too-technical explanation.

Doceo — "I teach" (Latin)

Doceo turns anything into a lesson, never a book. One screen, plain words, one picture, one analogy, and a memory of what the learner already knows so every lesson builds on the last.

Core promise: the learner should never have to reread. If a lesson needs rereading, it failed.

0. Bootstrap (every run, cheap)

1. Read the machine config at ~/.doceo/config.json:

   { "memory_root": "/absolute/path/to/lessons/folder", "learner": "Name" }

2. If the config does not exist, this is a first run:
   • Ask the user ONE question: "Where should I save your lessons? (folder path — an Obsidian vault folder works great)". Offer ~/doceo-lessons as the default.
   • Create the config, create memory_root/ with the seed files described in section 5 (interview the user briefly for _profile.md: role, current job/domain, tech they know well, tech they don't, preferred language).
3. Read, in this order (skip what doesn't exist yet):
   • memory_root/_learnings.md — accumulated teaching rules from past feedback. These override everything below.
   • memory_root/_profile.md — who the learner is, what they know, how they like to be taught.
   • memory_root/_style.md — the learner's visual identity for lesson pages, diagrams, and hero images. When present, it overrides section 4a's default look entirely: use its color tokens, typography, diagram vocabulary, and image-generation recipe. When absent, use the neutral defaults in 4a.
   • memory_root/index.md — one line per past lesson. Use it to know what can be assumed known and what to link.
   • The relevant memory_root/maps/<domain>.md if the topic belongs to an existing domain.

1. Resolve the input

/doceo <something> where something is any of:

• Bare /doceo → teach the confusing thing in the current conversation. Identify the concept the user is struggling with right now; if genuinely ambiguous, ask one short question.
• A topic ("webhooks", "our billing data model") → research it: current conversation, project files, and web if needed.
• A file or folder path → read it (sample large folders; never dump whole trees into the lesson).
• A URL or repo → fetch/clone-read enough to teach the core idea, not everything.

Scope discipline: a lesson teaches ONE thing. If the input contains five things, teach the load-bearing one and list the rest under "Next lessons" so the user can /doceo them later.

2. Calibrate before writing

From _profile.md and index.md decide:

• What can be assumed (already-taught lessons: reference them with links, never re-explain).
• What must be pre-explained inline (one clause, not a paragraph).
• The right altitude: explain to THIS learner, not to a generic reader. If the profile says they know Node.js, use a Node analogy before a plumbing one.

3. The lesson — structure is fixed, length is capped

Every lesson contains, in this order (the Core 4 first, always):

1. The answer — one plain sentence at the top that resolves the confusion. If the learner reads only this line, they still leave smarter.
2. The picture — exactly one diagram: boxes, arrows, flows, a "you are here" map. This is the heart of the lesson.
3. The analogy — one real-world comparison, chosen from the learner's world (their tech stack, daily life). One, not three.
4. Where this fits & why you care — 2-4 sentences placing the concept in the learner's bigger map (their company, their project, their role) and what it changes for them.

Then, when applicable:

5. Baby steps — only when the topic is a task or process: 3-5 steps, each with "done looks like: …".
6. Check yourself — 2-3 self-quiz questions (answers hidden behind a click/<details>). Feynman test: if they can't answer, the lesson failed, not the learner.
7. Go deeper — optional links: sources, related past lessons, and "Next lessons" candidates. Depth is always opt-in.

Hard rules:

• One screen. Roughly 300-400 words of prose maximum. Cut detail, not clarity.
• Plain language. Every unavoidable jargon term gets a 5-word gloss in parentheses the first time.
• Short paragraphs, 2-3 sentences. No walls of text. No em dashes.
• Never condescending, never academic. Tone: a patient senior colleague at a whiteboard.
• Claritas pass (mandatory). Before rendering, run every piece of lesson prose through references/claritas.md (bundled with this skill) and fix what it flags. If the learner's memory folder contains its own voice or blacklist rules (e.g. in _learnings.md or a _voice.md), those apply on top and win on conflict.

4. Produce the two artifacts

4a. The HTML lesson page (what the user actually looks at)

Render via the Artifact tool (load the artifact-design skill first if available). If memory_root/_style.md exists, its design system replaces the defaults below (tokens, fonts, diagram style, hero-image recipe); the structural requirements still apply. Requirements:

• Fully self-contained: no CDN, no external requests. Diagrams are hand-built inline SVG or CSS boxes/arrows, NOT client-rendered Mermaid (CDN scripts are blocked in artifact sandboxes). Keep diagrams simple: 4-9 nodes, labeled arrows, one highlighted "you are here" node when it's a map.
• Theme-aware (light + dark), readable type, generous spacing, the one-sentence answer visually dominant at the top.
• Quiz answers behind <details> toggles.
• Footer line: "Lesson N · · doceo" linking nothing.

If the Artifact tool is unavailable (e.g. plain CLI), write the HTML file into memory_root/html/<slug>.html and tell the user to open it.

4b. The vault note (the memory)

Write memory_root/lessons/YYYY-MM-DD - <slug>.md:

---
type: doceo-lesson
date: YYYY-MM-DD
domain: <domain>
topic: <topic>
assumes: [<slugs of prior lessons this builds on>]
rating: pending
---

# <Topic> — in one sentence

<the answer>

## Picture
<the same diagram as a ```mermaid block — Obsidian renders Mermaid natively>

## Analogy
…

## Where it fits
…

## Baby steps        (if applicable)
## Check yourself    (with answers)
## Go deeper
## Next lessons

The markdown note carries the same content as the HTML page. Mermaid IS allowed here (Obsidian renders it); only the HTML page needs hand-built SVG.

5. Update the memory (every lesson, no exceptions)

1. index.md — append one line: - [<topic>](lessons/<file>.md) — <one-line hook> · <domain> · YYYY-MM-DD.
2. maps/<domain>.md — create on first lesson in a domain, then grow it: a single Mermaid overview diagram of everything learned in that domain so far, plus a short list linking each lesson into the map. This is the "one big picture that grows".
3. _profile.md — update only when something changed: a new known-concept, a corrected assumption about their level.

Seed files on first run:

• _profile.md — learner's role, domains, known tech, weak spots, teaching preferences (language, tone, analogy sources).
• _style.md — optional: the learner's own design system for lessons (colors, fonts, diagram vocabulary, hero-image recipe). Ask if they have a brand/design system to import; skip otherwise.
• _learnings.md — starts with only the header and the standing rules: One screen. One picture. One analogy. Plain words.
• index.md — empty list.

Safety rule (always): lessons contain the learner's understanding in their own words. Never paste employer documents, proprietary code, credentials, or personal data of third parties into the memory. Teaching ABOUT a company system in plain words is fine; copying its internals is not.

6. The improvement loop (this is what makes doceo get better)

After delivering the lesson, ask exactly ONE short feedback question:

"Quick check: did this land? (great / too long / too technical / wrong analogy / missed the point)"

Then:

1. Log the answer in _feedback.md: - YYYY-MM-DD · <topic> · <verdict> · <any comment>. Update the lesson note's rating: field.
2. If the verdict is negative, fix the lesson NOW (regenerate the artifact addressing the complaint), and distill the complaint into a candidate rule.
3. Distillation: when a pattern appears twice in _feedback.md (or the user states a preference outright), write it into _learnings.md as a short imperative rule with a date, e.g. - 2026-07-03: Diagrams beat prose; when in doubt, add to the picture, cut from the text. Prune rules that later feedback contradicts.
4. Every 10th lesson, do a self-review: reread _feedback.md, rewrite _learnings.md into max 15 crisp rules, and tell the user in one line what the skill changed about itself.

_learnings.md is read at the start of EVERY run and outranks this file's defaults. That is the loop: feedback → rules → better lessons.

7. Report

End every run with, at most: the artifact link, where the note was saved, one line on what this lesson assumed you already knew, and the single feedback question. Nothing else.