{"id":18122,"plugin_id":"plugins_6a85a87df50c8191bd7f010bb7b17794","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:14:38.073Z","digest":"f6a33d778067a45601490dbf0cfbedcc6b2229da27da744833f8e895046829fe","against":null,"payload":{"description":"Explain a codebase, subsystem, feature, change, or technical idea so the user actually understands it. Use for 'teach me this', 'help me understand X', 'explain this change', 'walk me through this', or when the user wants more than a reference answer.","included_files":[],"name":"teach","skill_md_contents":"---\nname: teach\ndescription: \"Explain a codebase, subsystem, feature, change, or technical idea so the user actually understands it. Use for 'teach me this', 'help me understand X', 'explain this change', 'walk me through this', or when the user wants more than a reference answer.\"\n---\n# Teach\n\nExplain the thing so the user understands it well enough to work with it.\n\nDo not produce a reference manual, dump implementation details, or list every symbol involved.\n\nTeach what it is, how it works, and why it is built that way.\n\nUse this skill for questions like:\n\n- \"Teach me how this works.\"\n- \"Help me understand this subsystem.\"\n- \"Explain this PR to me.\"\n- \"Walk me through this architecture.\"\n- \"I need to understand this before I change it.\"\n- \"Explain this like I'm new to the codebase.\"\n\n## Start with what the user needs\n\nWork out why they are asking.\n\nThey may be:\n\n- about to change the code\n- reviewing a PR\n- debugging a problem\n- onboarding to a project\n- comparing designs\n- trying to understand a technical concept\n\nUse the conversation to judge what they already know.\n\nDo not quiz them before explaining something you can explain directly.\n\nSkip concepts they clearly understand. Spend time on the part their question is actually about.\n\n## Get the facts first\n\nIf the explanation depends on a codebase, PR, issue, file, or other technical artifact, inspect the available source before teaching it.\n\nUse the `how` skill to understand what the system does and how the parts fit together.\n\nUse the `why` skill when the explanation depends on design history, intent, constraints, or tradeoffs.\n\nDo not invent a simple story to make the explanation easier.\n\nA clear explanation still has to be true.\n\n## Give the smallest complete explanation first\n\nStart with one or two paragraphs that answer:\n\n- What is this?\n- What job does it do?\n\nThat first explanation should be enough for the user to decide whether they need more detail.\n\nDo not open with a table of contents, roadmap, or \"here is what we are going to cover.\"\n\nStart explaining.\n\n## Build from concrete behavior\n\nAfter the short definition, explain what actually happens.\n\nFor software, follow the path through the system.\n\nFor example:\n\n```text\nuser action\n-> request\n-> validation\n-> domain logic\n-> database write\n-> response\n\n```\n\nExplain what each step does and why it exists.\n\nDo not replace an explanation with function names.\n\nBad:\n\n```text\nCreateOrder calls OrderService, then OrderRepository.\n\n```\n\nBetter:\n\n```text\nThe request handler turns the incoming JSON into an order command. The domain service checks whether the order is allowed, then the repository stores the accepted order.\n\n```\n\nName the actual functions and files when they help the user find the code, but explain the mechanism first.\n\n## Introduce concepts when they become necessary\n\nDo not front-load ten definitions.\n\nIntroduce a concept when the explanation reaches the point where the user needs it.\n\nIf a queue matters only halfway through the flow, explain the queue halfway through the flow.\n\nIf a type exists only to prevent an invalid state, explain it when that invalid state becomes relevant.\n\nThis keeps the explanation attached to something concrete.\n\n## Explain why the shape matters\n\nWhen there is evidence for the design reason, connect the mechanism to that reason.\n\nFor example:\n\n```text\nThe payment state lives on the session rather than the exit event because payment can happen before the camera sees the vehicle leave.\n\n```\n\nIf the reason comes from historical evidence, use the `why` skill and preserve its confidence.\n\nIf you only know what the code does, do not turn that into a claim about why the team chose it.\n\nSay:\n\n```text\nThe code is structured this way. I could not verify whether that was the original reason for the design.\n\n```\n\nwhen that distinction matters.\n\n## Use examples that match the real system\n\nA good example should make the actual mechanism easier to see.\n\nPrefer:\n\n- a real request\n- a real entity\n- a real event\n- a real state transition\n- a small concrete input and output\n\nAvoid generic examples when the source gives you a better one.\n\nIf the system manages parking sessions, explain it with a parking session.\n\nIf it processes fuel orders, explain it with a fuel order.\n\nDo not switch domains just to create an analogy.\n\n## Draw when the relationships are hard to hold in prose\n\nUse a small text diagram when several parts interact.\n\nKeep it simple.\n\nStart with the main path:\n\n```text\nBrowser -> API -> Service -> Database\n\n```\n\nThen add another part only if it matters:\n\n```text\nBrowser -> API -> Service -> Database\n                   |\n                   v\n                Event bus\n\n```\n\nDo not create one giant diagram containing every component in the system.\n\nA diagram should reduce the amount the user has to remember, not create another thing they need explained.\n\n## Teach flows in order\n\nWhen the thing has a lifecycle, walk through it in the order it happens.\n\nFor example:\n\n```text\n1. Vehicle enters.\n2. The camera emits an ANPR event.\n3. Parking Edge creates a session.\n4. The teller marks the session paid.\n5. The vehicle reaches the exit.\n6. Parking Edge checks the payment and grace period.\n7. The gate may open.\n\n```\n\nThen explain the important decisions inside that flow.\n\nChronological explanations are usually easier to understand than explanations grouped by source file.\n\n## Show boundaries\n\nFor architecture, explain who owns what.\n\nThe user should be able to answer questions like:\n\n- Where does this behavior start?\n- Which component owns the rule?\n- Where is the state stored?\n- Which component is allowed to change it?\n- What crosses the network?\n- What happens asynchronously?\n- What can fail independently?\n\nIf they cannot answer those after the explanation, the architecture probably has not been explained yet.\n\n## Call out the surprising part\n\nMost systems have one or two things that a newcomer will assume incorrectly.\n\nName them.\n\nExamples:\n\n- the API does not actually perform the work synchronously\n- the displayed value is calculated rather than stored\n- an exit event does not close a session unless payment is valid\n- two modules use different representations of the same entity\n- a retry can cause the same message to arrive twice\n\nThese details are often more useful than another page of normal behavior.\n\nOnly include surprises supported by the source.\n\n## Match the depth to the conversation\n\nDo not give the full subsystem lecture when the user asks about one function.\n\nDo not stop at a two-sentence summary when they asked for a deep walkthrough.\n\nStart small. Go deeper as the question requires.\n\nIf the user asks a follow-up about one part, stay on that part instead of restarting the whole explanation.\n\n## Do not hide complexity\n\nMake the explanation easy to follow, but do not pretend the system is simpler than it is.\n\nIf two mechanisms interact, explain both.\n\nIf the evidence is incomplete, say so.\n\nIf the architecture has an awkward exception, include it when the exception changes the user's mental model.\n\nClarity means removing unnecessary difficulty, not removing facts.\n\n## Writing\n\nApply the `unslop` skill to every response.\n\nUse plain technical English.\n\nUse one name for each concept and keep using it.\n\nPrefer short paragraphs.\n\nMix sentence lengths naturally.\n\nAvoid filler, motivational framing, and teaching theatre.\n\nDo not say:\n\n- \"The key thing to remember is...\"\n- \"Here's where it gets interesting...\"\n- \"Let's break this down...\"\n- \"Don't worry, this is simpler than it looks.\"\n- \"At its core...\"\n\nJust explain the thing.\n\nDo not end with a generic summary that repeats what you already said.\n\nReply with the explanation itself."},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}