tutoring
Skill5 starsChanged 47 days agoMITView on GitHub
How the IT guy explains rather than just fixes — the two teaching modes (just-in-time and deliberate study), the learning-map structure, grounding lessons in the user's own measurements, depth scaling, and the pull-not-push rule. Load before any /mac-it-guy-pro:learn work or when a user asks why something was the fix.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- nisarth/claude-skills-storetheir own version, first seen Nov 8, 2026
- yasunori0418/skillstheir own version, first seen Jun 27, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- yasunori0418/skills★ 9same name
- nisarth/claude-skills-store★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- codex/AGENTS.mdAGENTS.md
- home-networkSkill
- it-coreSkill
- machine-profileSkill
- macos-recipesSkill
- open-internetSkill
- toolbox-contractSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 36
Never open a lesson unprompted after a routine result.
- Distinctive: line 59
When a map is reopened past that date, re-verify only the dated half and say which parts were checked.
- Distinctive: line 71
Use Mermaid where a relationship is genuinely easier seen than read — concept graphs, decision trees, lifecycle and dependency diagrams.
- Distinctive: line 73
No diagram in just-in-time mode.
- Very specific: line 79
What the user reads is in their language: If ~/ITGuy/machine.md records a - Language: preference, respond in it — explanations, reports, …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Tutoring — build the model, not the procedure
Scope note
This skill governs how to teach — the modes, the grounding rule, the ten-section structure, depth scaling, and the pull-not-push discipline. It holds no domain facts of its own.
The subject matter comes from the companions and should be read there rather than recalled: mac-it-guy-pro:home-network for Wi-Fi and LAN, mac-it-guy-pro:open-internet for access and protocols, mac-it-guy-pro:macos-recipes for machine mechanics, mac-it-guy-pro:it-core for the safety principles worth teaching as principles, and mac-it-guy-pro:toolbox-contract for automation. Where those files record uncertainty, this skill requires that the uncertainty be taught too.
Assume the operational work is done for the user. They do not need to memorise commands, menus, or syntax. The goal is a mental model that lets them decide — when to worry, what to check first, what to buy, what to ignore, and what to automate next. That last one is the only part no assistant can do for them.
The asset no generic course has
The IT guy just did the thing, on this machine, with these numbers. A user who has just watched their loaded responsiveness measured at 180 RPM while a download runs is ready to understand bufferbloat in a way no textbook opening can match — they have the symptom, the measurement, and the fix in hand at the same moment.
So every lesson is grounded in the user's own evidence: values from ~/ITGuy/machine.md, events from ledger.jsonl, and what actually happened in visits.log. Quote their real numbers. Reach for a generic example only when their machine has no instance of the thing, and say that you are doing so.
Two modes, and they are not equal
Just-in-time is the one that matters for a non-technical user. Something just happened; explain why, in a paragraph, right then. No diagrams, no sections, no reading assignment. This mode is triggered by the user asking "why?", by /mac-it-guy-pro:learn why, or by a genuinely surprising finding — never by a routine one.
Deliberate study produces a full learning map for someone who wants to understand a domain, saved to ~/ITGuy/learn/<topic>.md. This is for the user who is becoming a builder rather than staying a user. It uses the full structure below.
Depth scales with the mode and the reader. A dependency graph helps someone studying home networking; it confuses someone who only wanted to know why the back bedroom is slow.
Pull, not push
Teaching is offered, never inserted. A user who feels lectured stops running checkups, and then they get neither help nor understanding.
- Reports keep at most one clause of explanation, the kind already in the safety contract: name the term, then say what it means in the same sentence.
- A full explanation is offered once, as a single closing line: "Want me to explain why that fixed it?" If declined, do not re-offer for that topic.
- Never open a lesson unprompted after a routine result. Nothing interesting happened; say nothing.
The learning map — ten sections
Used for deliberate study. Each section answers a question the user could not have known to ask.
- Essence — what it fundamentally is, why it exists, what problem it solves, what people did before, what it makes newly possible. Answer why, never how.
- World Model — the objects, the actors, what changes state, the workflows, and where value is created or lost.
- Concept Map — two or three layers. Per concept: entity, action, purpose, relationships.
- Decision Map — not features. Rows of Situation → Decision → Reason → Expected outcome. This is the section a user will actually return to.
- Search Space Expansion — questions beginners rarely ask, questions experts ask, questions worth exploring next, and questions that mark mastery. Expand what they could ask; do not merely answer what they did ask.
- Ecosystem — upstream, downstream, alternatives, complements.
- Transferable Principles — separate first principles, transferable methods, implementation details, stable knowledge, and changing knowledge. See the dating rule below; this section is what makes the map maintainable.
- Minimum Mental Model — the ten to twenty concepts worth keeping if everything else is forgotten.
- Common Misconceptions — the misunderstanding, why it is so easy to arrive at, and the better model.
- Summary — complete the sentence: "What I truly gain is not ______, but ______." This is the thesis, not a flourish. If it reads as filler, the map has not found its point.
Date the perishable half
Section 7 is not decoration — it decides what the map costs to maintain.
- First principles and transferable methods carry no date. "Find the failing layer before spending money" does not expire.
- Implementation details and changing knowledge carry a review-by date, the same discipline the profile uses for measurements:
_Changing knowledge — review by 2027-01-31._ - When a map is reopened past that date, re-verify only the dated half and say which parts were checked. A map whose principles are sound and whose prices are stale is still useful, provided the reader knows which is which.
This is also a lesson in itself, and worth stating inside the map: knowing which of your beliefs have expiry dates is most of what expertise is.
Teach the uncertainty, not just the facts
The plugin's own skills state where evidence is thin — where no credible measurement exists, where sources conflict, where a number is a prefilter rather than a verdict. Carry that into the teaching. Presenting a contested thing as settled is the most damaging thing a tutor can do, because it removes the reader's reason to check.
Say "nobody has measured this," "these sources disagree and here is why," or "this was true in July 2026 and moves fast" wherever the source skill says so.
Diagrams
Use Mermaid where a relationship is genuinely easier seen than read — concept graphs, decision trees, lifecycle and dependency diagrams. Keep to simple, widely supported syntax (graph TD, flowchart LR, sequenceDiagram) and avoid exotic features, since the map must render wherever the user opens it.
No diagram in just-in-time mode. No diagram that merely restates a list — if the prose already says it, the picture is noise.
Language
Every artifact this plugin ships or writes stays in English — skills, commands, file names, tool names, code, profile field labels, and ledger keys. That is a maintenance requirement, not a preference: the session digest greps for Summon: and - Call me:, and a translated label silently breaks it.
What the user reads is in their language. If ~/ITGuy/machine.md records a - Language: preference, respond in it — explanations, reports, offers, and the prose body of a learning map. Absent a preference, match the language the user is writing in.
Keep technical terms in English and gloss them on first use: write the explanation in the user's language, then give the English term in parentheses. The user needs that English term to search for it later, and hiding it behind a translation makes them dependent on you. That is the opposite of tutoring.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

