py-refactor
Orchestrate comprehensive Python refactoring - coordinates security, complexity, testing, code health, and modernization skills to systematically improve code quality.
How do I install this agent skill?
npx skills add https://github.com/l-mb/python-refactoring-skills --skill py-refactorIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The py-refactor skill provides a safe and well-structured workflow for Python code refactoring by orchestrating standard, reputable quality analysis and testing tools.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1/3 files flagged
What does this agent skill do?
Python Refactoring Orchestrator
Comprehensive refactoring workflow coordinating specialized skills to improve Python code quality.
Overview
This skill orchestrates multiple focused skills to perform systematic refactoring:
| Skill | Purpose | Status |
|---|---|---|
py-security | Vulnerability detection and remediation | stable |
py-code-health | Dead code and duplication removal | stable |
py-complexity | Reduce cyclomatic/cognitive complexity | stable |
py-test-quality | Coverage analysis and mutation testing | stable |
py-modernize | Upgrade tooling and syntax | stable |
py-quality-setup | Configure linters and type checkers | stable |
py-git-hooks | Set up pre-commit hooks | stable |
Refactoring Priorities
Follow this impact-based prioritization:
- Critical: Security vulnerabilities (use
py-security) - High: Code duplication, untested code (<80% coverage)
- Medium: Complexity reduction, dead code removal
- Low: Syntax modernization, style improvements
Standard Refactoring Workflow
Phase 1: Setup (if needed)
1. If quality tools not configured (pyproject.toml):
→ Invoke: py-quality-setup
(also configures .claude/settings.local.json permissions for all tools)
2. Add analysis tools to [dependency-groups] dev in pyproject.toml:
"radon", "vulture", "pylint", "bandit", "lizard",
"pytest-cov", "mutmut", "wily", "ruff", "mypy", "basedpyright"
3. Install and activate:
uv sync && source .venv/bin/activate
Phase 2: Comprehensive Analysis
Run all automated scanners to get baseline:
mkdir -p reports
# Security
ruff check . --select S > reports/security.txt
bandit -r . -f json -o reports/security.json
# Code health
vulture . --min-confidence 80 > reports/dead_code.txt
pylint --disable=all --enable=duplicate-code --recursive=y . > reports/duplication.txt
# Complexity
radon cc . -n C -s > reports/complexity.txt
lizard -l python -w > reports/cognitive_complexity.txt
radon mi . -n B > reports/maintainability.txt
# Test quality
pytest --cov=. --cov-report=html --cov-report=term > reports/coverage.txt
# Initialize complexity tracking
wily build .
Phase 3: Prioritized Remediation
Step 1: Security (Critical)
If security.txt shows issues:
→ Invoke: py-security
- Fix SQL injection, hardcoded secrets, weak crypto
- Verify: ruff check . --select S (clean)
- Run tests to ensure no regressions
Step 2: Test Quality (High - enables safe refactoring)
If coverage < 80%:
→ Invoke: py-test-quality
- Write tests for untested code
- Run mutation testing to verify test quality
- Target: ≥80% coverage, ≥75% mutation score
Step 3: Code Health (High)
If duplication.txt or dead_code.txt show issues:
→ Invoke: py-code-health
- Remove dead code (vulture findings)
- Consolidate duplicates (pylint findings)
- Verify: Tests still pass, coverage maintained
Step 4: Complexity Reduction (Medium)
If complexity.txt shows C+ functions or maintainability < 65:
→ Invoke: py-complexity
- Extract functions, simplify conditionals
- Use guard clauses, lookup tables
- Track improvement with wily
- Verify: radon cc . -n C (clean)
Step 5: Modernization (Optional)
If project uses old patterns or pip:
→ Invoke: py-modernize
- Migrate pip → uv
- Upgrade syntax to Python 3.13+
- Consolidate to pyproject.toml
- Verify: Tests pass, type checking works
Phase 4: Automation
Set up git hooks to prevent regressions:
→ Invoke: py-git-hooks
- Pre-commit hooks run ruff, mypy, basedpyright
- Optionally add security checks (bandit)
- Test hook works correctly
Phase 5: Final Validation
# Run complete validation suite
ruff check .
mypy . && basedpyright .
ruff check . --select S
radon cc . -n C
vulture . --min-confidence 80
pytest --cov=. --cov-fail-under=80
# Track overall improvement
wily diff HEAD~1
wily report .
When NOT to Use This Skill
Don't use orchestrated refactoring when:
- Single focused task: Use specific skill directly (e.g., just py-security for CVE fix)
- No tests exist: Write tests first (py-test-quality), then refactor
- Active development: Coordinate with team to avoid merge conflicts
- Production incident: Fix incident first, refactor later
Additional Resources
- WORKFLOWS.md: Quick workflows for specific scenarios (security sweep, complexity sprint, legacy modernization)
- METRICS.md: Success metrics, tool reference, Engineering Charter alignment
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/l-mb/python-refactoring-skills/py-refactor">View py-refactor on skillZs</a>