technical-translation-ai-agent-skills

Choose an analogy domain (the "home lens") that fits what this specific user already knows deeply, persist it so it survives across new chats (not just the current session), keep the mapping consistent so they build a stable mental model, and say out loud where the analogy breaks down — because a confident wrong analogy is worse than jargon. Also handles switching the lens when another domain fits a concept far better, recalling a saved lens, and turning translation off. Use when first establishing how to explain things to a user, when they say "explain it like X"/"I know Y well"/"use a Z analogy", when an analogy is getting strained, when saving or recalling a lens across sessions, or when the user wants to change or disable translation ("stop translating", "/set-lens off"). Do NOT use when no lens should be set (the user is technical and wants straight talk), or when they want a one-off metaphor and not a persistent teaching frame.

Translate how a whole system fits together — its architecture, the pieces and how they connect, the data flow, the moving parts — into a single sustained analogy in the user's home lens, so a non-technical owner can hold a mental map of their own project and make architectural decisions instead of approving pieces they can't place. Use when the user asks "how does this all work", "what are the pieces", "draw me the architecture", "I don't understand how it fits together", "explain the system", when onboarding someone to a codebase they own but didn't write, or before a decision that only makes sense against the whole structure. Do NOT use when the user only needs one task or term explained (use translate-the-work), when they're technical and read architecture diagrams fine, or when the system is trivial enough that a map is overkill.

Before asking a user to approve, choose, or confirm something, translate what is actually at stake — what it does, what it costs (money, time, or compute — say which), and what can't be undone — into their home lens AND in literal terms, so they make an informed choice instead of reflexively clicking "yes" or the recommended option. Use whenever the agent is about to present a permission prompt, a "recommended" default, or any consequential or irreversible action — deleting, overwriting, force-pushing, deploying, spending money, granting access, exposing secrets, sharing user data or logs, enabling telemetry, or making a repo public. Even when the user has said to stop explaining or pre-authorized a class of action, still surface a one-line permanence/cost/access warning for anything irreversible, expensive, or access-granting. Do NOT use when the user clearly understands this specific choice, or the action is trivial and fully reversible.

Translate a completed technical task into the user's home lens — an analogy domain they already understand deeply (basketball, cooking, music theory, gardening) — so they understand what changed and why it matters, instead of skimming a jargon-filled status report and clicking the recommended option. Use at the end of a technical task for a non-technical or learning user, or when the user says "what did you just do", "explain that", "I don't understand", "translate this", "what does that mean", "in plain English", or "ELI5". Do NOT use when the user is technical and reads the raw output fine, has said "just do it"/"skip the explanation"/"I trust you", the action was trivial, or they explicitly asked for the raw technical detail.