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-33description: 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<!-- Generated from harness/github-copilot/plugins/repo-documentation/skills/comment-code-generate-a-tutorial/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# Comment code generate a tutorial910Refactor 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.1112## When to invoke1314- "Turn this Python script into a tutorial."15- "Add beginner-friendly comments to this script."16- "Refactor this Python code and write a README."17- "Make this script easier for beginners to understand."18- "Generate a project tutorial from this Python file."1920## Python refactoring rules2122| Area | Apply | Avoid |23| --- | --- | --- |24| 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. |25| Names | Rename unclear variables and functions when it improves clarity. | Renaming public APIs, CLI flags, files, or serialized fields without preserving compatibility. |26| 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. |27| Safety | Keep behavior equivalent unless the user asks for functional changes. | Silently changing algorithms, file paths, network behavior, or output formats. |28| Entry point | Prefer a `main()` function and `if __name__ == "__main__": main()` for runnable scripts. | Running side effects at import time. |2930## Instructional comment rules3132- Use a beginner-friendly, instructional tone.33- Explain what each important part of the code is doing and why it matters.34- Focus on logic, reasoning, data flow, and decisions, not just syntax.35- Avoid redundant or superficial comments such as `# increment i` above `i += 1`.36- Comment non-obvious trade-offs, assumptions, input formats, error handling, and external calls.37- Prefer clear names over comments when a rename can make the explanation unnecessary.3839## README tutorial requirements4041Generate or update `README.md` with these sections:4243| Section | Required content |44| --- | --- |45| `Project Overview` | What the script does and why it is useful. |46| `Setup Instructions` | Prerequisites, dependencies, environment setup, and how to run the script. |47| `How It Works` | A breakdown of the code logic based on the instructional comments. |48| `Example Usage` | A command or code snippet showing how to use it. |49| `Sample Output` | Include when the script returns visible results or a representative output can be shown confidently. |5051Use clear, readable Markdown formatting. Keep commands copy-pasteable and avoid inventing dependencies that are not present in the script or project files.5253## Gotchas5455- **Do not comment every line**: beginners learn more from comments around intent and flow than from syntax narration.56- **Do not change behavior while teaching**: preserve inputs, outputs, and side effects unless the user asks for improvements.57- **Do not fabricate sample output**: if output depends on unavailable data or services, show the command and explain what kind of output to expect.58- **Do not hide prerequisites**: if the script imports third-party packages, mention installation steps or the existing dependency file.5960## Output template6162```markdown63## Python tutorial project result6465**Status:** complete | partial | blocked66**Script:** `<path/to/script.py>`67**Tutorial:** `README.md`6869| Area | Changes made | Notes |70| --- | --- | --- |71| Refactor | `<functions/names/structure>` | `<behavior preserved or changed>` |72| Comments | `<instructional comments added>` | `<focus areas>` |73| README | `<sections generated>` | `<sample output included or omitted>` |7475### Validation76- Syntax check: `<command and result>`77- Run command: `<command and result, or not run with reason>`78```7980## Quality gate8182- [ ] Refactoring follows Python best practices and PEP 8 without unnecessary behavior changes.83- [ ] Unclear variables or functions are renamed only when compatibility is preserved or the user requested it.84- [ ] Comments explain logic and reasoning, not obvious syntax.85- [ ] `README.md` includes Project Overview, Setup Instructions, How It Works, Example Usage, and Sample Output when applicable.86- [ ] Dependency and run instructions are based on the actual script or project files.87- [ ] Validation includes a syntax check or a clear reason it could not be run.
paulasilvatech