skills.rest
devemberx
devemberxCOMMUNITY
Explore all skills by this author →
GitHub

compress-code-comments

Compress verbose Python comments and developer docstrings into concise why-first notes.

12|3|Updated Feb 19, 2026
Search Tags:#python#code maintenance#mypy#ruff#docstrings#comment cleanup#ast validation
One-click install
npx skills add https://github.com/devemberx/mcp-server-polarion --skill compress-code-comments
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: compress-code-comments
Source: https://github.com/devemberx/mcp-server-polarion/tree/main/.claude/skills/compress-code-comments
Command: npx skills add https://github.com/devemberx/mcp-server-polarion --skill compress-code-comments

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill reduces noisy, over-explained Python comments and developer docstrings so code becomes easier to read, maintain, and review. It helps teams preserve rationale and constraints while removing redundant narration that merely repeats what the code already says.

Core Features & Use Cases

  • Comment compression with guardrails: Rewrites verbose comments into compact, why-first notes and deletes trivial what-comments.
  • Protected surfaces enforcement: Avoids changing @mcp.tool docstrings, Field(description=...) strings, and functional pseudo-comments such as noqa, type: ignore, pragma, formatter, shebang, and encoding directives.
  • AST-based safety gate: Uses a validation script to prove edits are comment-only and do not alter executable code or protected literals.
  • Use cases: Ideal for Python repositories that want cleaner internal documentation, more maintainable helper docstrings, and safer comment cleanup during refactors or style sweeps.

Quick Start

Ask the assistant to run compress-code-comments on a specific Python file or directory to tighten developer comments without changing behavior.

Frequently Asked Questions about compress-code-comments

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I clean up verbose Python comments without changing executable behavior?▼

You can compress Python docstrings without breaking tooling by protecting specific surfaces during cleanup. The process avoids rewriting @mcp.tool docstrings, Field(description=...) strings, and functional pseudo-comments like pragma or shebang directives.

Does comment cleanup affect mypy or ruff formatting directives?▼

An AST comparison script validates comment cleanup by proving edits are comment-only. It checks that the abstract syntax tree remains unchanged, ensuring no executable code or protected literals are altered during the compression process.

What is the best way to compress Python docstrings without breaking tooling?▼

You can compress Python docstrings without breaking tooling by protecting specific surfaces during cleanup. The process avoids rewriting @mcp.tool docstrings, Field(description=...) strings, and functional pseudo-comments like pragma or shebang directives.

How does AST validation ensure comment-only edits during Python refactoring?▼

An AST comparison script validates comment cleanup by proving edits are comment-only. It checks that the abstract syntax tree remains unchanged, ensuring no executable code or protected literals are altered during the compression process.

Can I run a comment style sweep across Python tests and helper modules?▼

You can run a comment style sweep across Python tests, scripts, evals, and helper modules. The compression applies to repository cleanup tasks across these source directories while leaving executable behavior untouched.

Related Skills

Explore More Software Engineering Skills→
morodomimorodomi
8

python-quality

Run pytest, mypy, Black, isort, and ruff quality checks on Python projects.

Community
Intermediate
matteocervellimatteocervelli
25

python-quality-checker

Validate Python code formatting, typing, linting, and security issues.

Community
Advanced
sunLeeesunLeee

check-python-style

Validate Python code style, type hints, and Google-style docstrings.

Community
Intermediate
tadokoro-ryusuketadokoro-ryusuke

strategic-compact

Manage and compress context to preserve token budgets and task continuity.

Community
Advanced