| name | explaining-concepts |
| description | Explains a programming or Claude Code concept using your project as context, adapted to your experience level. Use when encountering an unfamiliar term, wanting to understand an architecture pattern, learning how a Claude Code feature works, or when you'd say 'what does X mean' or 'how does Y work.' |
| user-invocable | false |
Explaining Concepts
Overview
Concepts stick when they connect to something you already know. This skill explains programming and Claude Code concepts using YOUR codebase as the teaching aid — not textbook examples. It adapts to your experience level, so a data scientist gets different analogies than a systems engineer.
When to Invoke
- User types
/explain [topic]
- User asks "what is X?" or "how does Y work?" or "what does Z mean?"
- When the user encounters an unfamiliar term in documentation or error messages
- When the user wants to understand an architecture pattern in context
How It Works
Step 1: Identify the Topic
Parse the user's argument or question. The topic might be:
- A specific term: "closure", "middleware", "webhook"
- A pattern: "dependency injection", "pub/sub", "CQRS"
- A Claude Code feature: "hooks", "worktrees", "skills", "MCP"
- A question: "how does the event loop work?"
If no topic is provided or it's ambiguous, ask for clarification. Don't guess.
Step 2: Categorize and Source
| Category | Source | Approach |
|---|
| Claude Code concept | claude-docs-skill (if installed) | Read official docs, explain with accuracy. Mention specific hook events, frontmatter fields, commands. |
| Programming concept | General knowledge + project code | Explain the concept, then find an example in the user's codebase that demonstrates it. |
| Architecture pattern | General knowledge + project structure | Explain the pattern, then show how it applies (or could apply) to the current project. |
| Language-specific feature | General knowledge + project code | Explain with examples from the project's language and codebase. |
For Claude Code concepts: check if claude-docs-skill is installed. If yes, read the relevant documentation to ensure accuracy. If no, explain from general knowledge but note that claude-docs-skill would provide more detailed, current information.
Step 3: Adapt to User Level
Check auto-memory for the user's experience profile:
- What programming languages are they comfortable with?
- What's their role (data scientist, frontend dev, systems engineer)?
- What terms have they already learned (from teaching-terms)?
Use this to calibrate:
- Beginner: Use analogies to everyday concepts. Explain prerequisites.
- Intermediate: Use analogies to concepts they know. Skip basics.
- Expert in adjacent field: Map to their domain ("hooks are like database triggers", "skills are like Ansible playbooks").
If no user profile exists, default to intermediate level and adjust based on the conversation.
Step 4: Output
Concept: <1-2 paragraph explanation, adapted to user level>
In your project: <concrete example from the codebase or current work that demonstrates this concept. If nothing in the project directly demonstrates it, explain how it COULD apply.>
Related: <2-3 adjacent concepts worth exploring, as a bulleted list>
Vocabulary: <if introducing new terms within the explanation, note them briefly>
Guidelines
What Makes a Good Explanation
- Project-grounded. The "In your project" section is the key differentiator. Use actual file paths, function names, or patterns from the user's codebase.
- Analogies over definitions. "A closure is like a backpack that a function carries with it" is better than "a closure is a function bundled with its lexical scope."
- One level of depth. Explain the concept, not every related concept. The "Related" section lets the user go deeper on their own.
- Honest about limits. If you don't know how a concept applies to the project, say so rather than forcing a connection.
What to Avoid
- Textbook dumps. Don't reproduce Wikipedia or documentation verbatim.
- Condescension. Don't say "simply" or "just" or "as you probably know."
- Overloading. One concept per invocation. If the topic is broad ("explain hooks"), focus on the core concept and mention subtopics in "Related."
Edge Cases
- Topic not provided: Ask "What would you like me to explain?" with 2-3 suggestions based on what's been discussed in the session.
- Topic too broad: Narrow it. "Hooks is a big topic — would you like me to explain hook events, hook types, or how to write your first hook?"
- Topic already well-understood: If the user clearly knows the concept (they've used it correctly throughout the session), acknowledge that and offer a deeper dive into an advanced aspect.
- Topic is a Claude Code feature that doesn't exist: Correct the misconception gently. If the user confused feature names, suggest the right one.
