Guide · Agent skill
How to use the Add Educational Comments agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Add Educational Comments skill is an agent skill from github/awesome-copilot that rewrites a source code file with extra comments explaining what the code does and why. It is built for students, teachers and developers learning an unfamiliar language or framework. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and which settings and limits to know before you run it on a file.
Add Educational Commentsgithub/awesome-copilot · MIT Download the skill Quick start
- 1Download the ZIP. Download the skill ZIP from this page, which contains SKILL.md.
- 2Unzip into a skills folder. Place the unzipped folder in ~/.claude/skills/ for personal use or in your project's .claude/skills/ folder.
- 3Or upload it in the Claude apps. In the Claude apps, go to Settings, then Capabilities, then Skills, and upload the skill.
- 4Attach your code file. Provide the target file as chat context or an attachment so the agent has something to comment.
- 5Ask for comments with your settings. Request educational comments and state the reader's level, plus any settings such as Comment Detail or Line Number Referencing.
- 6Review the changes. Compare the edited file with your original, then run tests or the program to confirm nothing broke.
What is an agent skill, and what does this one do?
An agent skill is a folder containing a SKILL.md file that gives an AI agent specific instructions for one task. This skill is named add-educational-comments and its description reads: add educational comments to the file specified, or prompt asking for file to comment if one is not provided.
When you point the agent at a code file, it edits that file in place and adds comments aimed at learners. The comments focus on lines and blocks that best illustrate language or platform concepts, and they explain the reasoning behind syntax, idioms and design choices. If no file is provided, the agent asks for one and offers a numbered list of close matches to choose from.
Install the skill from the ZIP download
Download the ZIP for this skill from the page. Unzip it into one of two places, depending on how you want to use it. For a personal setup, put the unzipped folder in ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder.
If you use the Claude apps instead, you can upload the skill under Settings, then Capabilities, then Skills.
The skill package contains one file, SKILL.md.
- Personal: ~/.claude/skills/
- Project: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
Check what you need before you start
The skill needs an AI agent that supports SKILL.md skills and a target code file given to the agent as chat context or an attachment. The skill does not run scripts and does not use the network, according to its own assessment.
Prepare the file first. The skill is designed for files of a few hundred to a thousand lines. Keep a copy or use version control so you can compare the result with the original.
Trigger the skill with a natural request
You can invoke the skill with the command form shown in its examples, or simply ask the agent in plain language to add educational comments to a file you have attached. Name the file and say what kind of reader the comments are for.
If you do not provide a file, the agent replies with a request for one and asks you to attach it or add it as a chat variable.
- Add educational comments to the attached file for a beginner who is new to Python.
- Comment this file so a new developer can follow how it works.
- Add learner-friendly notes to output_name.py, with less detail and no note numbers.
/add-educational-comments #file:output_name.py Comment Detail = 1, Repetitiveness = 1, Line Numer = noAdjust the settings to fit your reader
The skill has configurable settings. If you leave one out, the default is used. Comment Detail (1-3, default 2) sets how deep each explanation goes. Repetitiveness (1-3, default 2) sets how often similar concepts are revisited. User Knowledge (1-3, default 2) describes general CS or software engineering familiarity, and Educational Level (1-3, default 1) describes familiarity with the specific language or framework.
Line Number Referencing (default yes) prefixes each new comment with a note number such as Note 1. Nest Comments (default yes) controls whether comments are indented inside code blocks. Educational Nature defaults to Computer Science. A typo such as Line Numer is interpreted from context.
- Comment Detail: 1-3, default 2
- Repetitiveness: 1-3, default 2
- User Knowledge: 1-3, default 2
- Educational Level: 1-3, default 1
- Line Number Referencing: yes or no, default yes
- Nest Comments: yes or no, default yes
Understand the line limits and the 125% rule
By default the agent adds comment lines so the file reaches 125% of its original length. It never adds more than 400 educational comment lines. For files longer than 1,000 lines, it aims for no more than 300 added comment lines.
If a file has already been processed with this skill, the agent updates the existing notes instead of applying the 125% increase again.
Review the result before you keep it
The skill is instructed to keep the file's encoding, line endings (LF or CRLF), indentation and syntax intact, and to avoid emojis and special symbols. It also tells the agent to validate these points after editing. Still, the file is changed in place, so review the diff yourself and run the code or its tests before committing.
- Compare the new file with your original copy.
- Check that the code still runs or builds.
- Remove any comment that is wrong or unhelpful.
What people use it for
- Annotating an example script you are reading for a programming course.
- Preparing commented sample code for students or course materials.
- Onboarding onto an unfamiliar language or framework by reading annotated code from your own project's copy.
- Creating learner-friendly versions of small utility files for documentation.
Frequently asked questions
How do I install the add-educational-comments skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings, then Capabilities, then Skills. The skill needs an agent that supports SKILL.md skills.
Is the add-educational-comments skill free to use?
The skill is published on github/awesome-copilot under the MIT licence. This page does not state any price, so check the repository for the licence terms that apply to your use.
What do I need to run this skill?
You need an AI agent that supports SKILL.md skills and a target code file provided as chat context or an attachment. The skill does not run scripts and does not use the network.
Why does the agent say it needs a file?
The skill requires at least one target file. If you do not provide one, it replies that you should supply a file or files, preferably as a chat variable or attached context. If several files match, it lists them with numbers so you can choose.
Will the skill change my code or break it?
It edits the file in place and adds comment lines, and it is instructed to keep syntax, encoding, line endings and indentation intact. Because it can add many lines, you should review the changes and run your tests. It is not recommended for production files you cannot review.
Is this skill a good fit for large or generated files?
Not really. The line limits and rules are designed for files of a few hundred to a thousand lines, and comments on generated code add little value. For very large files the skill aims for no more than 300 added comment lines.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a student, teacher or developer who wants annotated versions of code you are reading or teaching, and you can review the edits. Pick something else if you need changes to production code without review, or if you are working with very large or generated files.
Download the skill