clean-code_skill

Overview

This skill analyzes and improves code quality, readability, and maintainability across multiple languages with an emphasis on Python. It scores code, reports concrete issues, computes simple metrics, and provides prioritized improvement suggestions based on naming, function structure, comments, and formatting. The goal is actionable, idempotent feedback that fits into CI pipelines or developer tools.

How this skill works

The analyzer parses submitted code, computes metrics (lines, function lengths, params, cyclomatic complexity, naming and comment ratios), and applies rule sets for naming and function design. It produces a quality_score (0–100), a categorized list of issues with severity and suggested fixes, and targeted recommendations tuned by optional focus, style guide, and strictness. Results are deterministic and safe to run repeatedly.

When to use it

• During code reviews to surface maintainability regressions and quick wins.
• In CI pipelines to enforce a minimum quality score before merge.
• When refactoring legacy modules to prioritize high-impact improvements.
• While onboarding new developers to align code with team conventions.
• To audit third-party snippets before integrating them into production.

Best practices

• Provide the full file or function being analyzed to get accurate metrics and locations.
• Set focus filters (naming, functions, comments, formatting) to prioritize feedback during incremental cleanup.
• Choose a style_guide (PEP8, Google, Airbnb) and strictness level to match team expectations.
• Treat the quality_score as a guide, not an absolute blocker—review high-severity issues first.
• Integrate analysis results into existing linting and refactoring workflows to automate fixes.

Example use cases

• Scan a Python module before a release to ensure max function length and complexity targets are met.
• Detect vague variable and function names in a pull request and suggest descriptive replacements.
• Measure comment coverage and identify functions lacking explanatory comments or docstrings.
• Prioritize large, complex functions for decomposition by highlighting cyclomatic complexity and length.
• Enforce parameter count limits and warn when functions exceed recommended arity.