Write and audit Python code comments using antirez's 9-type taxonomy. Two modes - write (add/improve comments in code) and audit (classify and assess existing comments with structured report). Use when users request comment improvements, docstring additions, comment quality reviews, or documentation audits. Applies systematic comment classification with Python-specific mapping (docstrings, inline comments, type hints).
Writes or audits Python code comments using antirez's nine-type taxonomy to improve documentation quality and consistency.
/plugin marketplace add acaprino/alfio-claude-plugins/plugin install python-development@alfio-claude-pluginsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/docstring-styles.mdreferences/examples/audit-mode-examples.mdreferences/examples/write-mode-examples.mdreferences/taxonomy.mdTwo operational modes for Python code comments:
Core principle: comments explain why, code explains what. Type hints explain types.
Write mode triggers:
Audit mode triggers:
Nine comment types from antirez's "Writing system software: code comments". See references/taxonomy.md for full detail.
| Type | Name | Python Form | Purpose |
|---|---|---|---|
| 1 | Function | Docstring | What the function/class/module does |
| 2 | Design | Docstring or # | Architecture rationale, API design choices |
| 3 | Why | Inline # | Non-obvious reasoning behind code |
| 4 | Teacher | Inline # | Domain knowledge, algorithm explanation |
| 5 | Checklist | Inline # | Steps that must not be skipped or reordered |
| 6 | Guide | # section headers | Navigation aids in long modules |
| Type | Name | Detection | Fix |
|---|---|---|---|
| 7 | Trivial | Restates the code | Delete |
| 8 | Debt | TODO, FIXME, HACK | Resolve or create issue |
| 9 | Backup | Commented-out code | Delete (git preserves history) |
"""...""") - Types 1-2. Describe interface (what, args, returns, raises). Follow PEP 257.#) - Types 3-6. Describe implementation (why, how, context).# BAD: Comment duplicates type hint
def process(data: list[dict]) -> bool:
"""Process data.
Args:
data: A list of dictionaries # Redundant - type hint says this
"""
# GOOD: Docstring adds semantic meaning
def process(data: list[dict]) -> bool:
"""Process sensor readings and flag anomalies.
Args:
data: Sensor readings keyed by timestamp, each containing
'value', 'unit', and optional 'calibration_offset'
"""
"""Return the user's full name.""" (imperative mood, period)Execute in four phases.
Output: Inventory of existing documentation and code structure.
For each code element, determine what's missing:
Prioritize gaps by impact:
Output: Prioritized gap list with comment type needed for each.
Apply comments following these rules:
# for types 3-6references/docstring-styles.mdWriting rules per type:
references/docstring-styles.md# --- Section Name --- or # region/# endregionOutput: Commented code.
Output: Final commented code passing all checks.
Execute in four phases.
#, block #)Output: Comment inventory with locations.
For each comment, assign:
Quality criteria per type - see references/taxonomy.md for detail:
Output: Classified comment inventory with quality assessments.
Identify what's missing:
Severity levels:
Output: Gap analysis with severity ratings.
Generate structured audit report.
## Comment Audit Report
### Summary
- **Files analyzed:** N
- **Total comments:** N (docstrings: N, inline: N)
- **Comment density:** N comments per 100 LOC
- **Type distribution:** Type 1: N, Type 2: N, ... Type 9: N
- **Quality score:** N/10
### Critical Gaps
- [ ] {file}:{line} - {element} - Missing {type} comment - {impact}
### Issues Found
#### Negative Comments (fix or remove)
- {file}:{line} - Type {N} ({name}) - "{comment text}" - Action: {delete/resolve/rewrite}
#### Outdated Comments
- {file}:{line} - "{comment text}" - Mismatch: {description}
#### Quality Issues
- {file}:{line} - Type {N} - Issue: {description}
### Coverage Metrics
| Scope | With Docstring | Without | Coverage |
|-------|---------------|---------|----------|
| Modules | N | N | N% |
| Classes | N | N | N% |
| Public functions | N | N | N% |
| Public methods | N | N | N% |
### Recommendations
1. **Priority 1:** {action} - {N elements affected}
2. **Priority 2:** {action} - {N elements affected}
3. **Priority 3:** {action} - {N elements affected}
### Comment Style
- **Detected style:** {Google/NumPy/Sphinx/mixed}
- **Consistency:** {consistent/inconsistent}
- **Recommendation:** {standardize on X style}
See references/examples/audit-mode-examples.md for complete report examples.
x += 1, do not add # increment x"""Process data.""" on a complex function is worse than nothing__init__.py docstrings) follows type 1+2 patternsActivates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.