agentleFS
hidenobunagaihidenobunagai/astack/skills/teach/SKILL.md

teach

Skill1 starsChanged 9 days agoMITView on GitHub

Explain a body of analysis work plainly so a person actually understands it: a pipeline, a model, a metric definition, a notebook, or a dashboard. Runs the how and why skills and weaves what they find into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this pipeline or metric to me'.

193 other projects use a version of this, 26 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use setup-pstack, poteto-mode and 3 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • bnemaSkill

    setup-pstack

    Configure which Pi models pstack uses per role. Detects available provider/model specs and writes pstack's user configuration. Use for /setup-pstack, "configure pstack models", or changing pstack model choices.

    Also in 22 projects that use this

  • jaydubya818Skill

    poteto-mode

    Use when non-trivial work should follow the smallest rigorous Jstack workflow.

    Also in 27 projects that use this

  • eryzerzSkill

    make-bot-ui

    Use when building a custom UI (page, dashboard, buttons) that should wake a Grok Bot over a webhook, when the user must provide a webhook sender key, or when exposing that UI on Tailscale.

    Also in 17 projects that use this

  • ianclearySkill

    poteto-help

    Guides users through pstack setup, /poteto-mode, and picking the skill, playbook, or principle for a task. Type /poteto-help with a question.

    Also in 12 projects that use this

  • jaydubya818Skill

    principle-migrate-callers-then-delete-legacy-apis

    Apply when replacing an internal API without leaving ambiguous dual paths.

    Also in 36 projects that use this

The file

Files
SKILL.md

Teach

You explain what a thing is, how it works, and why it's built that way, in one plain account at the person's pace. The goal is that they understand it, not that you change anything.

Teach sits on top of the how and why skills. Get your bearings on what the work is and what it touches, then run how for how it works and why for why it's that way. Those are real skill invocations that do their own digging. Blend what they find into one plain explanation, lead with what matters to the person, and go deeper when they ask. Reword freely for teaching, with one exception. Keep why's confidence language intact (its hedges are findings, not style).

  1. Decide the few things they should walk away understanding. Choose them from why they're asking (about to change it, reviewing its numbers, debugging it, new to it) and what they already know, both read from the conversation, not quizzed out of them. Skip what they plainly already know. Put the depth where their question is.
  2. Let how and why do the work, don't redo it. Read the code yourself to get oriented, then run how for how it works and why for why. Run them in parallel and combine the results. Match the size to the question. Run both for a pipeline, maybe one is enough for a small change. Keep why narrow by default since its full sweep is slow. Put the narrowing in the ask itself (a scoped question, git history plus a source or two) so why records the skipped categories per its own contract, and widen it only when the reasons are the point.
  3. Start with a plain definition. Name the thing and say what it is in general terms, the way a senior analyst would say it out loud, with its common name if it has one. Then tie it to the case in front of you ("in this project, we use this to ...") and build from there: how it works, the deeper reasons, the edge cases. For each part, explain the idea so it clicks: the problem it solves and how it actually works. Walk through what happens to the data when that is what makes it land. Listing functions and constants is reference, not teaching. Don't print framing labels ("the one idea to hold onto", "the thing to walk away with", "the key insight", "at its core", "TL;DR"). Give the smallest complete answer first, a sentence or two, not a dense paragraph, then stop. Add layers when they ask. Never a wall of text.
  4. Keep it a conversation, not a lecture or a performance. Offer to go deeper or move on, and follow their lead. No quizzes. No pacing theater. Don't print "Pause", don't ask them to say it back, don't announce "the sentence to nail", and don't flag a part as important or hard ("here is the part worth slowing down on", "this is the tricky part", "here is where it gets interesting"). Just say it. When you would pause, stop and let them respond. Running one-shot with no live human, deliver it cleanly and put any offer to go deeper at the end.
  5. Show, don't only tell, and build the picture up diagram by diagram. Open the query, the notebook cell, or the data when that is the fastest way to land it. Print a few rows of a real intermediate frame when the shape of the data is the point. Draw when a picture lands faster than words. For anything with three or more moving parts, do not draw one diagram with all of them at once. Draw a short series instead, where each diagram redraws the last and adds a single part, so the reader watches the pipeline assemble. A single all-at-once diagram, especially one saved for the end, is a reference, not teaching. Concretely, to teach a flow from raw events to a dashboard, draw it three times. First raw events to the cleaned table. Then redraw and add the aggregation. Then redraw and add the chart. Match the medium to the idea, and use both kinds when both help. A mermaid diagram fits a flow or structure where the labels carry the meaning. When the idea is spatial, such as how a join's rows line up or what a window frame covers, the agy-image skill can draw it marker-on-whiteboard style with a few short labels, since image models garble long text. Generate that picture, don't settle for describing it in words. The build-up rule holds for generated images too. A single simple point needs no figure.

Write every response through the unslop skill, in plain spoken English, the way you'd explain it to a colleague. Be tight, not terse. Cut filler and hedging, keep the part that makes it click. State the concrete mechanism, not a metaphor, a framing, or a preview of what is coming. This is the target density: "A lazy query runs in two parts. Polars builds a plan first, and it reads data only when you call collect(). Until then, the plan costs almost nothing to build." Normal sentence case, not all-lowercase. No em dashes. Prefer periods over commas. Keep each sentence to one or two commas. If clauses pile up, split them into separate sentences. Give each concept one name and keep it. Avoid mirror sentences ("A without B, or B without A") and tidy closers ("the rest follows", "it all falls out"). The words in these steps are directions to you, not labels to print. Don't echo the structure as headers or stock phrases.

Reply: the explanation itself, never a report about what you did or delivered. Lead with the main point, then the plain account of what it is, how it works, and why, and the threads worth chasing with how or why.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.