refactor

Restructure passing code to improve naming, readability, and documentation without changing behavior.

4|1|Updated Jul 31, 2025
One-click install
npx skills add https://github.com/alvis/.agents --skill refactor-alvis
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: refactor
Source: https://github.com/alvis/.agents/tree/main/plugins/coding/skills/refactor
Command: npx skills add https://github.com/alvis/.agents --skill refactor-alvis

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Code that works but is hard to read, poorly named, or cluttered with redundant defensive checks accumulates maintenance cost. This Skill improves the structure, naming, and documentation of code whose tests already pass, while guaranteeing behavior stays unchanged. ## Core Features & Use Cases - Behavior-Preserving Restructuring: Extract functions, reduce complexity, and apply design patterns while running tests continuously so nothing breaks. - Redundancy Removal with Provenance: Trace validate/assert/check helpers to their producers and remove only checks whose postconditions are proven by an exact cited test. - Naming and Documentation: Apply naming standards, add JSDoc with @example blocks, and write inline comments that explain why rather than what. - Use Case: A TypeScript module has grown past the project's max-lines threshold with duplicated guard checks after internal calls. Run the refactor skill on that area to split it via the Two-Stage Rule, remove proven-redundant checks, and document the public API. ## Quick Start Refactor the code in src/services/billing with focus on structure and redundancy, keeping all tests passing.

Frequently Asked Questions about refactor

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

FAQPage Schema
How do I refactor code without changing its behavior?

Run the refactor skill on a target area whose tests all pass. It restructures, renames, and documents the code while running tests continuously after each change, so any behavioral regression is caught immediately.

When should I use refactoring versus fixing or writing new code?

Use refactoring only when tests pass and the goal is maintainability. Failing tests or bugs belong to a fix workflow, new features belong to a write-code workflow, and version-driven API upgrades belong to a modernization workflow.

Can redundant defensive checks be removed safely?

Yes, but only when the check reasserts a postcondition of closed, typed, tested first-party code and the exact producer test proving that postcondition is cited. Guards at real trust boundaries, external inputs, and deserialization paths are always retained.

What happens if tests fail in the target area before refactoring?

The skill rejects the request and directs you to fix the failing tests first. Refactoring requires a green baseline so that any test failure during restructuring unambiguously signals a behavioral change.

How are files that exceed the max-lines threshold split?

The Two-Stage Rule applies: first extract genuinely reusable shared logic into helper files, then keep the domain file as a thin re-export or orchestrator with sub-domains moved into a matching folder. Filenames are never derived from the main export.