@rfxlamia/skillkit 1.0.0 → 1.2.0

package/skills/skills/baby-education/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: baby-education
+description: Makes agent explain concepts with extreme clarity for beginners learning new topics or projects. Uses analogies-first approach, visual mental models, and ELI5 style to transform complex technical explanations into accessible learning experiences. Trigger when user is new to a technology, starting a project, or explicitly requests simple explanations.
+category: engineering
+---
+
+# Baby Education
+
+## Overview
+
+This skill transforms your explanations into beginner-friendly learning experiences. Instead of diving into technical jargon, you'll explain concepts using everyday analogies, build visual mental models step-by-step, and maintain a conversational storytelling tone that makes complex ideas accessible.
+
+**When to use this skill:**
+- User is learning a new programming language, framework, or technology
+- Starting a new project type they haven't worked with before
+- User explicitly asks for "simple explanation", "ELI5", or mentions being a beginner
+- Explaining architecture, design patterns, or abstract concepts
+- Debugging errors for someone new to the codebase
+
+## Core Principles
+
+### 1. Analogies-First Approach
+
+Always start with a concrete analogy from everyday life before introducing technical concepts.
+
+**Bad (technical-first):**
+```
+A REST API uses HTTP methods like GET, POST, PUT, DELETE to perform
+CRUD operations on resources identified by URIs.
+```
+
+**Good (analogies-first):**
+```
+Think of a REST API like a restaurant:
+- The menu (API documentation) lists what you can order
+- You tell the waiter your order (send a request)
+- The kitchen (server) prepares it
+- The waiter brings your food (returns a response)
+
+Now mapping to technical terms:
+- GET = "Show me the menu" (reading data)
+- POST = "Place a new order" (creating data)
+- PUT = "Change my order" (updating data)
+- DELETE = "Cancel my order" (deleting data)
+```
+
+### 2. Build Visual Mental Models
+
+Help users visualize abstract concepts by describing them spatially or structurally.
+
+**Example for explaining async/await:**
+```
+Imagine you're cooking dinner:
+
+WITHOUT async/await (blocking):
+1. Put rice in cooker → wait 20 min standing there doing nothing ⏰
+2. Then chop vegetables → wait 10 min ⏰
+3. Then cook vegetables → wait 15 min ⏰
+Total: 45 minutes
+
+WITH async/await (non-blocking):
+1. Put rice in cooker (start it, walk away)
+2. While rice cooks, chop vegetables
+3. While rice still cooks, start cooking vegetables
+4. When rice beeps, it's ready - combine everything
+Total: 20 minutes
+
+The keyword `await` is like checking "is the rice done?" before serving.
+You can do other things, but when you NEED the rice, you wait for it.
+```
+
+### 3. Progressive Complexity
+
+Start simple, then gradually introduce technical details.
+
+**Structure:**
+1. **Opening analogy** - relate to familiar experience
+2. **Basic concept** - simple version without edge cases
+3. **Technical vocabulary** - introduce terms with context
+4. **Real implementation** - show actual code/solution
+5. **Recap** - tie analogy back to technical reality
+
+**Example:**
+```
+1. Analogy: "Git branches are like parallel universes where you can
+   try different versions of your story."
+
+2. Basic: "You create a branch to test a new feature without breaking
+   your main code. If it works, you merge it back."
+
+3. Technical: "A branch is a pointer to a commit in the Git tree.
+   'main' is just the default branch name."
+
+4. Implementation:
+   git checkout -b new-feature
+   # make changes
+   git commit -m "add feature"
+   git checkout main
+   git merge new-feature
+
+5. Recap: "So those 'parallel universes' are actually just pointers
+   in a commit graph, letting you work on multiple versions safely."
+```
+
+### 4. Jargon Handling Rules
+
+**Rule 1: Avoid jargon when possible**
+- Instead of "instantiate an object" → "create a copy of the blueprint"
+- Instead of "dependency injection" → "passing tools into a function instead of creating them inside"
+
+**Rule 2: When unavoidable, define with examples**
+```
+Bad: "You need to serialize the data before sending it over the network."
+
+Good: "You need to convert your data into a format that can travel through
+the internet - like packing your items into a shipping box. This process
+is called 'serialization'. JSON is one common packing format."
+```
+
+**Rule 3: Use "In other words..." bridges**
+```
+"The function is idempotent. In other words, calling it 5 times gives
+the same result as calling it once - like pressing an elevator button
+multiple times doesn't make it arrive faster."
+```
+
+### 5. Conversational Storytelling Tone
+
+Write like you're explaining to a friend over coffee, not presenting at a conference.
+
+**Characteristics:**
+- Use "you" and "we" (not passive voice)
+- Ask rhetorical questions: "Why does this matter?"
+- Acknowledge confusion: "This part trips up everyone at first..."
+- Celebrate small wins: "See? That wasn't so scary!"
+- Use casual connectors: "Now here's the cool part...", "But wait...", "The trick is..."
+
+**Example:**
+```
+Formal: "One must configure the environment variables prior to application
+initialization to ensure proper authentication credentials are available."
+
+Conversational: "Before you run your app, we need to set up environment
+variables - think of them as secret notes you leave for your code. This is
+where you'll tell it things like API keys and passwords, without hardcoding
+them into your files (which would be like writing your PIN on your credit card!)."
+```
+
+## Common Patterns
+
+### Pattern: Explaining Errors
+
+**Structure:**
+1. "Here's what happened..." (translate error message)
+2. "Why this happened..." (root cause in simple terms)
+3. "How to fix it..." (concrete steps)
+4. "How to avoid it..." (prevention tip)
+
+**Example:**
+```
+Error: `TypeError: Cannot read property 'length' of undefined`
+
+Here's what happened:
+Your code tried to check how long something is (.length), but that "something"
+doesn't exist yet (undefined). It's like trying to measure the length of a box
+that hasn't been delivered yet.
+
+Why this happened:
+The variable might not have been assigned a value, or it came back empty from
+a function that didn't return what you expected.
+
+How to fix it:
+Add a safety check before using .length:
+if (myArray && myArray.length > 0) {
+  // safe to use myArray now
+}
+
+How to avoid it:
+Always check if data exists before using it, especially when it comes from
+external sources (APIs, user input, databases).
+```
+
+### Pattern: Comparing Options
+
+Use tables or clear comparisons when showing multiple approaches:
+
+```
+"Should I use forEach or map?"
+
+Think of them like this:
+
+forEach = walking through a museum, just looking
+- You see each painting
+- You don't create anything new
+- Just doing something with each item
+
+map = walking through a museum with a camera
+- You see each painting
+- You create a new photo collection
+- Returns a new array with transformed items
+
+When to use:
+- forEach: "Do something with each item" (logging, updating UI)
+- map: "Transform each item into something new" (formatting data)
+```
+
+## Integration Tips
+
+### With Code Examples
+
+Always provide code with comments that explain WHY, not just WHAT:
+
+```javascript
+// Bad comments (what)
+// Create a new array
+const numbers = [1, 2, 3];
+
+// Good comments (why)
+// We'll use map to create a new array instead of modifying the original
+// (keeping original data unchanged is safer for debugging)
+const doubled = numbers.map(n => n * 2);
+```
+
+### With Documentation References
+
+Bridge the gap between your explanation and official docs:
+
+```
+"Now that you understand the restaurant analogy, the official docs will
+make more sense. When they say 'RESTful endpoints', they mean the different
+menu items. When they mention 'HTTP verbs', those are the GET/POST/PUT/DELETE
+actions we talked about."
+
+[Link to official docs]
+```
+
+## Quick Reference
+
+**Before explaining, ask yourself:**
+1. ✅ Did I start with an analogy from everyday life?
+2. ✅ Can someone visualize this concept spatially/structurally?
+3. ✅ Did I avoid jargon, or define it with examples?
+4. ✅ Does my tone sound like talking to a friend?
+5. ✅ Would a complete beginner understand each step?
+
+**Tone checklist:**
+- ✅ Use "you" and "we"
+- ✅ Ask rhetorical questions
+- ✅ Acknowledge common struggles
+- ✅ Celebrate small wins
+- ❌ No passive voice
+- ❌ No unexplained acronyms
+- ❌ No assuming prior knowledge
+
+## Resources
+
+This skill includes reference materials with advanced techniques and examples:
+
+- `references/advanced-techniques.md` - Visual mental models, scaffolding patterns, handling difficult topics
+- `references/transformations.md` - Before/after examples of technical explanations transformed into beginner-friendly versions

package/skills/skills/baby-education/references/advanced-techniques.md

@@ -0,0 +1,323 @@
+# Advanced Techniques for Baby Education
+
+## Visual Mental Models Deep Dive
+
+### Technique 1: Layered Diagrams (Text-Based)
+
+For complex systems, build diagrams incrementally using ASCII art or structured text:
+
+```
+Explaining: How does a web request work?
+
+Layer 1 (Simplified):
+You (Browser) → Internet → Server → Database
+                  ↓
+         Server sends back webpage
+
+Layer 2 (Add Detail):
+Browser           Internet Cloud         Server Farm
+  |                    |                      |
+  |--[HTTP Request]--->|---[Route to IP]----->|
+  |                    |                      |--[Query DB]
+  |                    |                      |    ↓
+  |<--[HTML/CSS/JS]----| <-[Package Response]-|<-[Data]
+
+Layer 3 (Technical):
+Now map to real terms:
+- "HTTP Request" = GET/POST with headers
+- "Route to IP" = DNS lookup + TCP connection
+- "Query DB" = SQL SELECT statement
+- "Package Response" = JSON/HTML serialization
+```
+
+### Technique 2: State Transition Stories
+
+Explain state changes as a story progression:
+
+```
+Topic: React Component Lifecycle
+
+Tell it like a day in someone's life:
+
+1. Born (Constructor/Initial State)
+   "You wake up with your default settings - maybe grumpy, maybe energetic"
+
+2. Getting Ready (componentDidMount)
+   "You check your phone, load today's schedule from the calendar"
+
+3. Living (Render + Updates)
+   "Throughout the day, things happen that change your mood or plans"
+   "Each time something changes, you react and update what you're doing"
+
+4. Going to Sleep (componentWillUnmount)
+   "Before bed, you clean up - close apps, set alarm, turn off lights"
+
+Then map: "In React, your component does the same thing with data instead of daily tasks"
+```
+
+### Technique 3: Zoom In/Zoom Out Pattern
+
+Start macro, then zoom to micro details:
+
+```
+Explaining: Database Indexing
+
+Zoom Level 1 (Bird's Eye):
+"A database index is like a book's table of contents - helps you find stuff faster"
+
+Zoom Level 2 (Ground Level):
+"Instead of reading every page to find 'Chapter on Dogs', you check the index:
+ Dogs............Page 47
+ Now jump directly there"
+
+Zoom Level 3 (Microscope):
+"Technically, it's a B-tree data structure that stores:
+ - Keys (sorted values you're searching for)
+ - Pointers (memory addresses to actual data rows)
+
+ Search time: O(log n) instead of O(n)"
+
+Zoom Back Out:
+"So when you query WHERE name='John', the database checks its 'index book' instead of scanning every row"
+```
+
+## Scaffolding Patterns for Complex Topics
+
+### Pattern 1: Prerequisite Ladder
+
+Build understanding step-by-step with explicit dependencies:
+
+```
+Topic: Understanding Promises in JavaScript
+
+Rung 1: "First, understand callbacks"
+→ "A callback is just passing a function to be called later"
+→ Example: setTimeout(() => console.log("done"), 1000)
+
+Rung 2: "Callbacks get messy (callback hell)"
+→ Show nested callbacks example
+→ "This becomes unreadable fast"
+
+Rung 3: "Promises solve this by chaining"
+→ Same logic, but with .then() instead of nesting
+→ "Much cleaner to read"
+
+Rung 4: "async/await makes it even better"
+→ "Now it looks like normal sequential code"
+```
+
+### Pattern 2: Contrast with Known Concepts
+
+Use "You already know X, this is similar but..." framework:
+
+```
+"You know how Excel formulas work?
+- You type =SUM(A1:A10)
+- Excel calculates it
+- The cell shows the result
+- If A1 changes, result updates automatically
+
+React hooks work the same way:
+- You define a formula (function component)
+- React calculates what to display
+- The DOM shows the result
+- If state changes, React recalculates and updates
+
+The syntax looks different, but the concept is identical: automatic recalculation when inputs change"
+```
+
+## Handling Edge Cases
+
+### Case 1: Topics That Don't Analogy Well
+
+Some concepts (like monads, category theory) resist simple analogies.
+
+**Strategy: Build from simple → abstract**
+
+```
+Don't say: "A monad is just a monoid in the category of endofunctors"
+
+Instead:
+1. Show concrete examples first:
+   - Maybe<T> handles null safely
+   - Array<T> handles multiple values
+   - Promise<T> handles async values
+
+2. Notice the pattern:
+   "They all wrap a value and let you chain operations"
+
+3. Optional: "That wrapping + chaining pattern is what makes it a monad"
+   (But don't insist on the term if it's not needed)
+```
+
+### Case 2: Balance Between Simplicity and Accuracy
+
+Sometimes analogies break down. Address this explicitly:
+
+```
+"Earlier I said 'Git branches are like parallel universes.' That works for understanding the basics, but let me refine it:
+
+More accurately, they're lightweight pointers to commits. All branches exist in the same universe (your .git folder), and you can see all of them simultaneously. The 'parallel universe' idea helps you understand isolation, but technically they're just different paths through the same commit graph.
+
+For everyday use, think parallel universes. When debugging merge conflicts, remember it's one graph with multiple pointers."
+```
+
+### Case 3: Unavoidable Jargon
+
+When technical terms must be used (e.g., in error messages):
+
+**Three-Step Approach:**
+1. Provide everyday version
+2. Introduce technical term
+3. Connect them
+
+```
+Error: "Segmentation fault (core dumped)"
+
+1. Everyday: "Your program tried to access memory it's not allowed to touch - like trying to open your neighbor's mailbox"
+
+2. Technical: "This is called a 'segmentation fault' or 'segfault'"
+
+3. Connection: "The 'segments' are different areas of memory. Your program stepped into the wrong segment - hence 'segmentation' fault. 'Core dumped' means it saved a snapshot of memory for debugging"
+```
+
+## Different Audience Levels
+
+### Complete Beginner (Zero Assumed Knowledge)
+
+- Define EVERYTHING, even "obvious" terms
+- Use analogies from daily life (cooking, driving, shopping)
+- Avoid compound sentences with multiple concepts
+- Check understanding every 2-3 concepts
+
+**Example:**
+```
+"We'll install Node.js. Think of it like this: JavaScript normally runs in your browser (like Chrome or Firefox). Node.js lets JavaScript run directly on your computer, outside the browser. It's like taking a fish out of water and giving it a special tank - different environment, same fish."
+```
+
+### Some Background (Familiar with basics)
+
+- Reference foundational concepts quickly
+- Use programming-adjacent analogies (Excel formulas, Photoshop layers)
+- Introduce multiple concepts per explanation
+- Focus analogies on the NEW part
+
+**Example:**
+```
+"You know how variables store values? Pointers are similar, but instead of storing the value itself, they store the address where the value lives in memory. Like a hotel room key card - the card isn't the room, it just points to where the room is."
+```
+
+### Struggling with Specific Concept (Mid-level learner)
+
+- Don't restart from zero
+- Pinpoint the conceptual gap
+- Use precise analogies for that one concept
+- Connect to what they already implemented
+
+**Example:**
+```
+"I see you're confused about async/await vs .then() - you've used both, but not sure when to use which. They do the same thing, just different syntax:
+
+.then() = explicit chaining (you see each step)
+async/await = looks synchronous (hidden chaining)
+
+Use .then() when: multiple parallel async operations
+Use async/await when: sequential operations where you need the previous result
+
+In your code on line 23, you need the user data before fetching their posts - perfect for async/await"
+```
+
+## Integration with Code Examples
+
+### Technique: Annotated Code Stories
+
+```javascript
+// Story: We're building a shopping cart
+
+// 1. Start with an empty cart (initial state)
+let cart = [];
+
+// 2. Customer adds an item (state update)
+function addItem(item) {
+  // Like putting item in a real shopping cart
+  cart.push(item);
+
+  // Update the total (derived state)
+  updateTotal();
+}
+
+// 3. Calculate total (computed value)
+function updateTotal() {
+  // Similar to cashier scanning items
+  const total = cart.reduce((sum, item) => sum + item.price, 0);
+
+  // Show it to customer (update UI)
+  displayTotal(total);
+}
+
+// The pattern: Action → State Change → UI Update
+// React components work exactly like this shopping cart
+```
+
+### Technique: Before/After Debugging
+
+```javascript
+// ❌ Before (confusing for beginners)
+const data = await fetch(url).then(r => r.json());
+
+// ✅ After (step-by-step clarity)
+// Step 1: Ask server for data (like ordering food)
+const response = await fetch(url);
+
+// Step 2: Unpack the response (like opening the delivery bag)
+const data = await response.json();
+
+// Why two steps? Because fetch gives you the "box" (response),
+// .json() opens the box and gives you the actual "food" (data)
+```
+
+## Combining with Other Skills
+
+### Baby Education + Code Review
+
+When reviewing code for a beginner:
+
+```
+"Your code works, but let's make it more maintainable. See this part:
+
+if (user && user.age && user.age > 18) { ... }
+
+This is called 'defensive coding' - checking everything exists before using it. Good! But there's a cleaner pattern called 'optional chaining':
+
+if (user?.age > 18) { ... }
+
+The ?. means 'only keep going if the thing before exists.' Like a safety gate on stairs - only proceed if it's safe.
+
+Both work, but ?. is easier to read once you know the pattern."
+```
+
+### Baby Education + Debugging
+
+When helping fix an error:
+
+```
+"The error says 'Cannot find module'. Let's translate this:
+
+Your code is like a recipe that says 'add the imported chocolate chips.' But when Node looks in your pantry (node_modules folder), there's no chocolate chips package.
+
+Fix: npm install chocolate-chips
+
+Technically: npm installs the module into node_modules, so when your code does 'import X from Y', Node can find Y in that folder."
+```
+
+## Quick Reference Patterns
+
+| Situation | Pattern | Example |
+|-----------|---------|---------|
+| Abstract concept | Concrete analogy first | "Redux is like a bank vault - one central place for all your money (state)" |
+| Multiple options | Comparison table | forEach vs map vs filter |
+| Sequential process | Numbered steps with checkpoints | "First...then...finally" |
+| Error explanation | 4-step: What/Why/Fix/Prevent | TypeError breakdown |
+| Terminology | Sandwich: Analogy → Term → Connection | "Segmentation fault" explanation |
+| Complex system | Zoom levels | Macro → Micro → Zoom out |
+| State changes | Story progression | Component lifecycle as "day in life" |