dqz00116/skill-lib/layered-first-principles-teaching

Layered First Principles Teaching

Overview

Transform complex concepts into progressive, first-principles explanations that build understanding layer by layer.

When to Use

Use when:

• You need to explain a complex concept to someone with less domain knowledge
• You're designing training materials, tutorials, or educational content
• You're preparing a technical presentation and need progressive disclosure
• A topic has multiple abstraction layers that require cognitive scaffolding
• You need to bridge the gap between intuitive understanding and technical depth

Don't use when:

• The concept is simple and doesn't benefit from layered decomposition
• You need quick reference documentation or a terse answer
• The audience already has deep expertise and only needs edge cases or implementation details

Quick Start

# Explain a concept progressively
kimi layered-first-principles-teaching "Explain blockchain"
 
# Target specific audience
kimi layered-first-principles-teaching "Explain transformers" --audience beginner
 
# Output to file
kimi layered-first-principles-teaching "Explain consensus algorithms" --output ./tutorial.md

Output Structure

Generated explanations contain 6 standard sections:

Audience Levels

Teaching Patterns

This skill uses progressive disclosure patterns from prompts/:

1. First Principles Analysis (first_principles.txt): Strip away abstractions, find root causes
2. Layered Decomposition (layered_decomposition.txt): Break into 3-4 cognitive layers
3. Analogy Generation (analogy_generation.txt): Find relatable comparisons
4. Visualization Design (visualization_design.txt): Create mental models and diagrams

Templates

Output templates in templates/ provide structure for:

• concept.md: General concept explanation
• algorithm.md: Algorithm walkthrough
• system.md: System architecture explanation

Examples

See examples/ for completed explanations:

• blockchain_explained.md: From "digital ledger" to Byzantine fault tolerance
• transformers_explained.md: From "pattern matching" to attention mechanisms

Workflow

When explaining a concept:

1. Load first principles prompt → Identify core problem and breakthrough insight
2. Load layered decomposition prompt → Structure into 3-4 cognitive layers
3. Load analogy generation prompt → Find 2-3 cross-domain analogies
4. Load visualization design prompt → Create ASCII diagrams and mental models
5. Apply appropriate template → Generate final explanation

Constraints

• Maximum 4 layers to avoid cognitive overload
• Each layer must build on previous without introducing new prerequisites
• Analogies must be familiar to target audience
• Visualizations should work in plain text (ASCII)