add-educational-comments_skill

Overview

This skill adds educational comments to source files to turn code into clear learning resources. It requests a target file if none is provided, preserves encoding and formatting, and follows configurable detail, repetitiveness, and line-numbering rules. The goal is to increase readability and teach language- and architecture-level concepts without altering program behavior.

How this skill works

The skill inspects the provided file to determine language, encoding, and line endings, then plans comment locations that best illustrate concepts for the configured knowledge level. It inserts only single-line comments with preserved indentation, optional note numbering, and a target increase in lines (default: 125%) while enforcing line limits and syntax safety. If no file is supplied, it prompts for one and can present a numbered list of close matches for quick selection.

When to use it

• You want to convert production or sample code into a self-explanatory tutorial.
• Preparing code samples for classrooms, documentation, or onboarding materials.
• When learners need step-by-step explanations tied to specific lines or blocks.
• Reviewing legacy code to surface design intent and language idioms.
• Creating annotated examples for interviews, blog posts, or study guides.

Best practices

• Provide the exact file(s) and desired knowledge level so comments match learner needs.
• Keep test/build pipelines available to validate no runtime or syntax changes occurred.
• Prefer smaller targeted files when aiming for the 125% expansion rule to maintain focus.
• Use Line Number Referencing = yes for lessons that require cross-reference; disable for lighter commentary.
• Supply a brief config (Comment Detail, Repetitiveness, User Knowledge) to control depth and repetition.

Example use cases

• Annotate a Python module so beginners learn idiomatic patterns and why certain choices were made.
• Add architecture and performance notes to a backend service file for intermediate and advanced engineers.
• Convert a utility script into a teachable walkthrough for a workshop, including numbered explanatory notes.
• Refine existing comments in a file that was previously processed, improving clarity without reapplying line-count rules.
• Prepare code snippets for a tutorial, keeping formatting and encoding untouched while adding nested contextual notes.