Comment code generate a tutorial
Refactor a Python script for readability, add useful beginner-friendly comments that explain reasoning, and generate a tutorial-style README.md that teaches setup, usage, internals, and expected output.
When to invoke
- "Turn this Python script into a tutorial."
- "Add beginner-friendly comments to this script."
- "Refactor this Python code and write a README."
- "Make this script easier for beginners to understand."
- "Generate a project tutorial from this Python file."
Python refactoring rules
| Area |
Apply |
Avoid |
| Style |
Apply standard Python best practices and PEP 8 naming, spacing, imports, and line length conventions. |
Reformatting in a way that conflicts with the repository's formatter. |
| Names |
Rename unclear variables and functions when it improves clarity. |
Renaming public APIs, CLI flags, files, or serialized fields without preserving compatibility. |
| Structure |
Extract small functions for distinct steps such as loading input, processing data, and presenting output. |
Over-engineering a short teaching script with unnecessary classes. |
| Safety |
Keep behavior equivalent unless the user asks for functional changes. |
Silently changing algorithms, file paths, network behavior, or output formats. |
| Entry point |
Prefer a main() function and if __name__ == "__main__": main() for runnable scripts. |
Running side effects at import time. |
Instructional comment rules
- Use a beginner-friendly, instructional tone.
- Explain what each important part of the code is doing and why it matters.
- Focus on logic, reasoning, data flow, and decisions, not just syntax.
- Avoid redundant or superficial comments such as
# increment i above i += 1.
- Comment non-obvious trade-offs, assumptions, input formats, error handling, and external calls.
- Prefer clear names over comments when a rename can make the explanation unnecessary.
README tutorial requirements
Generate or update README.md with these sections:
| Section |
Required content |
Project Overview |
What the script does and why it is useful. |
Setup Instructions |
Prerequisites, dependencies, environment setup, and how to run the script. |
How It Works |
A breakdown of the code logic based on the instructional comments. |
Example Usage |
A command or code snippet showing how to use it. |
Sample Output |
Include when the script returns visible results or a representative output can be shown confidently. |
Use clear, readable Markdown formatting. Keep commands copy-pasteable and avoid inventing dependencies that are not present in the script or project files.
Gotchas
- Do not comment every line: beginners learn more from comments around intent and flow than from syntax narration.
- Do not change behavior while teaching: preserve inputs, outputs, and side effects unless the user asks for improvements.
- Do not fabricate sample output: if output depends on unavailable data or services, show the command and explain what kind of output to expect.
- Do not hide prerequisites: if the script imports third-party packages, mention installation steps or the existing dependency file.
Output template
## Python tutorial project result
**Status:** complete | partial | blocked
**Script:** `<path/to/script.py>`
**Tutorial:** `README.md`
| Area | Changes made | Notes |
| --- | --- | --- |
| Refactor | `<functions/names/structure>` | `<behavior preserved or changed>` |
| Comments | `<instructional comments added>` | `<focus areas>` |
| README | `<sections generated>` | `<sample output included or omitted>` |
### Validation
- Syntax check: `<command and result>`
- Run command: `<command and result, or not run with reason>`
Quality gate
1---2name: comment-code-generate-a-tutorial-23description: Transform a Python script into a polished beginner-friendly project by refactoring code, adding instructional comments, and generating a complete README.md tutorial. Use this skill when asked to explain, comment, clean up, teach, or turn a Python script into a tutorial project.4---56# Comment code generate a tutorial78Refactor a Python script for readability, add useful beginner-friendly comments that explain reasoning, and generate a tutorial-style `README.md` that teaches setup, usage, internals, and expected output.910## When to invoke1112- "Turn this Python script into a tutorial."13- "Add beginner-friendly comments to this script."14- "Refactor this Python code and write a README."15- "Make this script easier for beginners to understand."16- "Generate a project tutorial from this Python file."1718## Python refactoring rules1920| Area | Apply | Avoid |21| --- | --- | --- |22| Style | Apply standard Python best practices and PEP 8 naming, spacing, imports, and line length conventions. | Reformatting in a way that conflicts with the repository's formatter. |23| Names | Rename unclear variables and functions when it improves clarity. | Renaming public APIs, CLI flags, files, or serialized fields without preserving compatibility. |24| Structure | Extract small functions for distinct steps such as loading input, processing data, and presenting output. | Over-engineering a short teaching script with unnecessary classes. |25| Safety | Keep behavior equivalent unless the user asks for functional changes. | Silently changing algorithms, file paths, network behavior, or output formats. |26| Entry point | Prefer a `main()` function and `if __name__ == "__main__": main()` for runnable scripts. | Running side effects at import time. |2728## Instructional comment rules2930- Use a beginner-friendly, instructional tone.31- Explain what each important part of the code is doing and why it matters.32- Focus on logic, reasoning, data flow, and decisions, not just syntax.33- Avoid redundant or superficial comments such as `# increment i` above `i += 1`.34- Comment non-obvious trade-offs, assumptions, input formats, error handling, and external calls.35- Prefer clear names over comments when a rename can make the explanation unnecessary.3637## README tutorial requirements3839Generate or update `README.md` with these sections:4041| Section | Required content |42| --- | --- |43| `Project Overview` | What the script does and why it is useful. |44| `Setup Instructions` | Prerequisites, dependencies, environment setup, and how to run the script. |45| `How It Works` | A breakdown of the code logic based on the instructional comments. |46| `Example Usage` | A command or code snippet showing how to use it. |47| `Sample Output` | Include when the script returns visible results or a representative output can be shown confidently. |4849Use clear, readable Markdown formatting. Keep commands copy-pasteable and avoid inventing dependencies that are not present in the script or project files.5051## Gotchas5253- **Do not comment every line**: beginners learn more from comments around intent and flow than from syntax narration.54- **Do not change behavior while teaching**: preserve inputs, outputs, and side effects unless the user asks for improvements.55- **Do not fabricate sample output**: if output depends on unavailable data or services, show the command and explain what kind of output to expect.56- **Do not hide prerequisites**: if the script imports third-party packages, mention installation steps or the existing dependency file.5758## Output template5960```markdown61## Python tutorial project result6263**Status:** complete | partial | blocked64**Script:** `<path/to/script.py>`65**Tutorial:** `README.md`6667| Area | Changes made | Notes |68| --- | --- | --- |69| Refactor | `<functions/names/structure>` | `<behavior preserved or changed>` |70| Comments | `<instructional comments added>` | `<focus areas>` |71| README | `<sections generated>` | `<sample output included or omitted>` |7273### Validation74- Syntax check: `<command and result>`75- Run command: `<command and result, or not run with reason>`76```7778## Quality gate7980- [ ] Refactoring follows Python best practices and PEP 8 without unnecessary behavior changes.81- [ ] Unclear variables or functions are renamed only when compatibility is preserved or the user requested it.82- [ ] Comments explain logic and reasoning, not obvious syntax.83- [ ] `README.md` includes Project Overview, Setup Instructions, How It Works, Example Usage, and Sample Output when applicable.84- [ ] Dependency and run instructions are based on the actual script or project files.85- [ ] Validation includes a syntax check or a clear reason it could not be run.
paulasilvatech