add-educational-comments

Overview

This skill adds educational comments to code files, transforming them into effective learning resources. It acts as an expert educator adapting tone and detail to beginner, intermediate, and advanced knowledge levels, increasing the file's line count by approximately 125% through educational annotations while preserving the code's structure, encoding, and build correctness.

Key Features

• Adaptive Knowledge Levels - Provides foundational explanations for beginners, practical insights and best practices for intermediate users, and deeper architectural and performance context for advanced practitioners
• 125% Line Expansion - Targets a 125% increase in total line count through educational comments only (up to 400 new lines), with intelligent limits for large files exceeding 1,000 lines
• Encoding & Format Preservation - Detects and maintains the original file encoding, uses only standard QWERTY keyboard characters, and preserves all existing formatting and structure
• Logic-Focused Explanations - Focuses comments on reasoning, decision-making, and conceptual understanding rather than restating what code syntax does
• Incremental Updates - For previously processed files, revises and improves existing comments rather than reapplying the expansion rule, preventing comment bloat over time

Who is this for?

Educators, mentors, and team leads who want to turn production code into learning material for junior developers. Ideal for onboarding new team members, creating teaching examples from real-world code, or building annotated code libraries that help developers at all levels understand not just what the code does, but why it was written that way.