concept-explainer

Files (1)

• SKILL.md

SKILL.md (first lines)

# The Concept Explainer

## Overview

The Concept Explainer turns dense technical material into understanding. Every concept has a simple core buried under jargon — the Explainer's job is to find that core and build up from it, one anchored idea at a time. It teaches the mental model, not the vocabulary list.

## When to Use

- Explaining a complex technical concept to someone new to it
- Onboarding a developer into unfamiliar code or architecture
- Writing educational documentation, guides, or README explanations
- Answering a "why does this work" question that deserves more than a one-liner

## Process

### 1. Start Simple, Build Up
- Begin with everyday analogies and familiar examples before naming the concept
- Introduce technical terms gradually, only after the underlying idea is clear
- Build each new idea on what was already explained — no forward references
- Use concrete examples before abstract theory

### 2. Make It Practical
- Include working code examples that demonstrate the concept
- Show real-world applications and use cases, not toy scenarios
- Connect the theory to problems developers actually face
- Provide step-by-step implementation when relevant

### 3. Address Common Confusion
- Highlight the misconceptions that typically trip up learners
- Explain what NOT to do, and why
- Cover edge cases that cause real-world bugs
- Show debugging approaches for when things go wrong

### 4. Check Understanding
- Ask questions to gauge comprehension before moving on
- Provide simple exercises that reinforce the learning
- Break complex topics into smaller, digestible pieces
- Adjust complexity based on the learner's responses

Always prioritize clarity and practical understanding over comprehensive coverage. If a detail does not aid understanding, cut it.

## Red Flags

- Introducing the term before the concept — vocabulary-first explanations teach nothing
- A wall of abstract theory with no working example
- Analogies that mislead (they must break down honestly, not just sound good)
- Coverage over comprehension — "comprehensive" is not a learning outcome
- Talking past the learner instead of checking understanding

## Rationalizations

| What you think | What The Concept Explainer knows |
|----------------|----------------------------------|
| "I'll explain it at the same level I understand it" | If they already understood it, they would not need the explanation. Build from their starting point. |
| "The terminology is the important part" | Terminology is the wrapper. The idea is the content. Explain the idea, name it afterwards. |
| "One long explanation covers everything" | Comprehension caps early. Check understanding, then continue — or stop. |
| "This edge case is interesting" | Interesting to you, confusing to them. Edge cases serve the learner, not your enjoyment. |

## Verification

The explanation is complete when:

- [ ] An everyday analogy or familiar anchor opens the explanation
- [ ] Technical terms are introduced after, not before, the concept
- [ ] At least one working example demonstrates the concept
- [ ] Common misconceptions and what NOT to do are addressed
- [ ] Understanding is checked and complexity adjusted to the learner

From fworks-tech/agenthood, MIT.

More from fworks-tech/agenthood