refactor
- Use it when:
- You want a PR, branch, file or function made as good as it can be, not just working.
- It does:
- Rates every file, function and piece of logic from 0 to 10 with a reason, then refactors for simplicity, clean abstractions and readability.
- You get:
- One commit per refactor, old => new ratings linked to the commits, the whole diff, and a list of opportunities beyond what you asked.
- Unlike improve-codebase-architecture:
- That one scans a whole codebase for modules worth restructuring and talks one through with you; this one works through the code you name until every part rates high.
- Runs:
- When you ask for a refactor, on the code you name or, by default, on what the agent is working on; it doesn't stop for your approval.
TL;DR
You point it at code, such as a PR, a function or a file; by default it takes what the agent is working on, and asks when that's unclear. Before changing anything, the agent lists everything in scope and rates each item from 0 to 10 with a reason, skipping nothing. Then it refactors on three fronts. Simplify: remove duplicated logic, boilerplate, needless indirection and tests that only restate the code, and treat comments that justify a design as claims to check, not rules to follow. Clean abstractions: make each file and function a sensible unit, and check that each responsibility sits on the right side of each function boundary. Readability: read each top-level function as prose, and push low-level details, such as flags or error plumbing, down into the functions it calls. It keeps going on its own until the code is exceptionally good, with a separate commit for each refactor, and ends with the ratings before and after, a link or git command for the whole diff, and the opportunities it saw beyond your request.
Summarizes the skill at 5f3a481.
npx skills add https://github.com/brillout/skills --skill refactor skills.sh pageSource on GitHubAll skills from brillout/skills
- Total Downloads
- 1 on skills.sh, Nov 9, 2026
- First seen
- Oct 30, 2026 on skills.sh
Weekly values
| Week to | Installs |
|---|---|
| Sep 21 | 0 |
| Sep 28 | 0 |
| Oct 5 | 0 |
| Oct 12 | 0 |
| Oct 19 | 0 |
| Oct 26 | 0 |
| Nov 2 | 1 |
| Nov 9 | 0 |
| Category |
Test-first work, implementation from specs, git hygiene and scope control. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills. |
|---|---|
| Type |
A multi-step process the agent follows: interview, debug, run a TDD loop, review. |
| Effect |
Its own steps create or change files, git state or local tools. |
| Needs |
Instructions only. Works in any agent that supports skills. |
| Publisher |
Everyone else. Unverified vendor claims default to community. |
| Topics |
SKILL.md
From brillout/skills at 5f3a481. Checked daily, last changed Nov 9, 2026.
Frontmatter
name: refactor
description: "Refactor code until it's exceptionally good (simplification, readability, ...) — use when the user asks to refactor code."
argument-hint: "What should be refactored? Default: what the agent currently works on."Refactor
Refactor what the user told you (e.g. PR, function, or file). By default, refactor what you're currently working on. If it isn't clear, ask the user.
Simplify
- Do you see logic implemented twice? Is everything DRY?
- Can logic be simplified?
- Question & first-principle thinking: break everything down to ground truth — any previous assumptions might be false
- Don't rubber-stamp what's already there
- Code comments that justify a design ("X lives here rather than Y so that…") are claims to audit, not constraints to respect. For each, construct the alternative it argues against and compare — don't assume the documented choice is optimal.
- Can boilerplate be removed? Do you see frivolous indirections?
- Can frivolous tests be removed? Tests should verify behavior that isn't obvious from reading the code, not just reproduce its logic.
Clean abstractions
- Pinnacle architectural split
- Does each file and each function represent a sensible abstraction that is easy to understand?
- Rate the seams, not just the boxes: for each call site, ask whether the responsibility sits on the right side of the boundary — should a caller's wrapper move down into the callee (or vice versa)? A function can be perfect in isolation yet still be in the wrong place.
Readability
- Put yourself in the shoes of a human reader who reads everything in a linear fashion
- Altitude pass: for each entry-point / orchestration function, read it top-to-bottom as prose. Flag any line that drops the reader into lower-level mechanism (a flag, a thunk, a log verb, error plumbing) in the middle of what should be a high-level narrative. For each, ask: can that mechanism move down into the callee so the caller reads at one consistent altitude? Prioritize the reading path of the functions a reader hits first.
Workflow
- Before starting to work: list everything (e.g. all logic, files, functions), rate it all (0: bad — 10: perfect) and give a reason for your rating
- Don't skip anything (100% coverage)
- Show summary of what you did:
- Show lists with old rating => new rating with link to commits
- Show entire diff (all commits), e.g. as a GitHub URL or if no URL then a git command
- Separate commit for each refactor
- Work until it's exceptionally good — autonomously strive for quality
- If you stumble upon refactor opportunities beyond the current scope then list them, e.g.
## Beyond this PR