Skip to content
Skills Library
Programming · Building & coding

refactor

/refactor

Restructure or clean up code with no behavior change, proved by before-and-after checks. Use when: asked to clean up, extract, dedupe or simplify, even one function.

Repository
agentops ↗
Licence
Apache-2.0
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Restructure or clean up code with no behavior change, proved by before-and-after checks. Use when: asked to clean up, extract, dedupe or simplify, even one function.

Original author description

Restructure or clean up code with no behavior change, proved by before-and-after checks. Use when: asked to clean up, extract, dedupe or simplify, even one function.

How it works

  1. What counts as behavior
  2. Procedure
  3. Responsibility and interface cost
  4. Neutrality gates
  5. References
Original SKILL.md headings · 127 lines, 1,032 words
SKILL.md preview
---
name: refactor
description: 'Restructure or clean up code with no behavior change, proved by before-and-after checks. Use when: asked to clean up, extract, dedupe or simplify, even one function.'
practices:
- refactoring
- legacy-code-seams
- design-patterns
hexagonal_role: supporting
consumes:
- repo-context
produces:
- code-changes
context_rel: []
skill_api_version: 1
user-invocable: true
context:
  window: fork
  intent:
    mode: task
  sections:
    exclude:
    - HISTORY
metadata:
  capabilities: [refactor]
  effects: [modify_source_files]
  canonical_status: canonical
  disposition: keep_specialist
  tier: execution
  dependencies: []
output_contract: code changes with regression evidence
---
# Refactor — one structural experiment

Refactor changes structure while preserving observable behavior. It performs one
caller-selected transformation and reports the result. "Behavior-preserving" is
a claim to prove with before/after checks, never to assert.

## What counts as behavior

Unless the caller explicitly excluded a surface, all of these must survive:

- **Messages and exit codes.** Error and output text compares byte-for-byte;
  exit codes, error types and which input raises which error stay the same.
  Scripts and callers parse them. Preserve an inconsistent message and report
  it; normalizing it is a behavior change.
- **Differences between near-duplicates.** When merging duplicated branches,
  carry every difference (constants, comparisons, messages, extra steps) as a
  parameter or a branch. Do not unify a difference the caller has not declared
  accidental.
- **Interfaces.** Public signatures, defaults, return types, persisted field
  names, protocol values and CLI flags. Renaming one is a compatibility change
  unless the accepted scope provides for it.
- **Order and coverage.** Branch priority, default handling, evaluation count,
  side-effect order, and the set of tests that run. A pre-existing red that
  vanishes, or a test that stops running, is a behavior change.
- **Protective checks.** Trust-boundary validation, data-loss guards, security
  controls and accessibility affordances stay, even when another layer,
  upstream or downstream, duplicates one or no test reaches it. The neutrality gates cannot see their
  removal, so looking redundant is no reason to delete one.

## Procedure

1. Name the preserved behavior, the focused acceptance surface and the concrete
   structural problem for its callers, in the caller's domain terms.
2. Run the focused check and the smallest regression check the changed surface
   justifies, and record that honest baseline, including reproducible ambient
   failures. For an evaluation comparing executable behavior, pin the starting
   source, build its baseline before edits and keep that binary and the
   comparison inputs.
3. Apply one bounded transformation: extract, rename, inline, simplify,
   encapsulate, move, substitute existing code, or delete dead code; the
   [refactoring catalog](references/behavior-preserving-simplification.md#refactoring-catalog)
   holds per-pattern safety checks. Judge it by what callers must
   understand and where a domain rule must change, not by file size.
4. A bug or suspicious inconsistency found on the way is reported separately
   (location, why it looks wrong) and left unfixed. Fixing it inside the
   refactor hides a behavior change the caller did not authorize.
5. Rerun the same focused check and the smallest justified regression check
   over the same inputs, including error paths.
6. Report, then stop. A red result is evidence for the caller; this skill does
   not revert, narrow, retry, commit, validate, or route subsequent work.

When nothing can be executed (no runtime, no tests, code supplied in a
message), neutrality is unproven: give the exact before/after commands and
inputs the caller must run, error paths included, and list every surface under
behavior not checked.

```text
transformation: <the one change>
preserved:      <behavior and surfaces from step 1>
checks:         <command>: before -> <result>; after -> <result>   (or "not run")
outputs:        <before/after hashes when the surface produces output>
diff:           <files touched>; only those the transformation names
suspected bugs: <file:line, why>; reported, not fixed
not checked:    <surfaces no check covered>; present even when empty
```

## Responsibility and interface cost

Before adding an interface or splitting a module, inspect representative callers.
Count the concepts they must coordinate: required setup, ordering, states, error
handling and repeated domain rules. A useful boundary puts a cohesive rule under
one owner and lets callers request an outcome without reproducing that rule.
Reject a wrapper that only adds another name or pushes the same coordination
into its callers. Existing boundaries are sufficient when no concrete caller
problem warrants changing them.

When choosing a target, prefer friction in the caller-selected area: repeated
changes to the same rule, repeated caller setup, or defects spread across
cooperating files. Recent history can locate that friction when the caller has
not named it; churn alone does not justify a refactor. State the expected
saving in concrete work, such as changing one rule in one place, against the
caller migration and regression cost. Leave a stable, cheap boundary alone.

Check a proposed extraction by imagining its removal: would callers have to
rebuild a cohesive rule, or would only a forwarding step disappear? Keep
internal test seams private when callers need no substitution. Exercise the
preserved behavior through the caller-facing boundary; retain existing tests
until equivalent coverage of their distinct cases is demonstrated. Moving a
test is not permission to delete the behavior it protected.

Use the caller's vocabulary for extracted operations and types. A naming
ambiguity that changes behavior belongs with the existing domain definition;
consult [Domain](../domain/SKILL.md) only when that distinction needs work.

When the transformation needs a seam — an extraction boundary, interface, or
module split — and more than one candidate seam exists, probe before you cut.
Run the probe in disposable isolation (a scratch branch, worktree, or copied
tree the caller's policy allows): rough in the seam, see what it forces —
signature churn, import cycles, test rewrites — then discard the probe and
keep only the knowledge. Stop condition: at most two probes; if the second
candidate seam also fights back, report both findings to the caller instead of
trying a third. Cutting the first imaginable seam directly into the working
tree is the **premature seam** failure mode: the wrong boundary calcifies
because reverting it now costs more than living with it.

## Neutrality gates

Gate the transformation on behavior-identical proof:

- The focused check and the package-level regression check pass both before
  and after, with the same set of pre-existing failures: no new red and no
  vanished red.
- For output-producing surfaces (generators, serializers, formatters, reports),
  capture output hashes over identical inputs before the change and compare
  byte-for-byte after. A mismatch is a behavior diff to surface and explain,
  never to shrug at; the caller decides whether to keep, narrow, or reverse it.

A neutrality gate that was skipped or narrowed after the fact is the
**post-hoc neutrality** failure mode — the diff decides what got tested. Name
any surface the gates did not cover under behavior not checked.

## References

- [Behavior-preserving simplification](references/behavior-preserving-simplification.md) — refactoring catalog and per-pattern safety checks
- [Behavior scenarios](references/refactor.feature)
- [Upstream capability reference](https://github.com/mattpocock/skills/blob/main/skills/engineering/codebase-design/SKILL.md) — Matt Pocock; original AgentOps adaptation.
Files in this package (3)
  • SKILL.md 8 KB
  • references/behavior-preserving-simplification.md 7 KB
  • references/refactor.feature 3 KB

Versions

RepositoryScoreLicence
This page · boshu2/agentops100Apache-2.0
froglet-studio/cosmic-shore100MIT
mgiovani/cc-arsenal100MIT
jongio/skills100MIT
y-miyazaki/terraform-aws-base100Apache-2.0
mickeyyaya/evolve-loop100Apache-2.0
j0hanz/j0hanz-marketplace100MIT
kriscard/kriscard-claude-plugins100MIT
kriscard/Skills100MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 1fc67d74a42e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100dev-refactor
    Use when changing structure without changing behavior: restructure, extract, rename, dedupe or split code.
  • 95simplify
    Use when the user wants to simplify or clean up code without changing behavior. Accepts standalone scope or user-selected findings from /refactor.
  • 100refactor-plan
    Code-level refactoring analysis and roadmap. Detects duplication and complexity. Triggers on: refactor, tech debt, simplify, clean up, modularize, DRY, restructure.
  • 100refactor-code
    Use this skill whenever the user wants to actually refactor, rewrite, modernize, or transform existing code. Triggers include: "refactor this", "rewrite this code", "convert to hooks", "modernize this", "extract utilities", "clean up this code", "apply the refactor plan",…
  • 100refactor-clean
    Use when code has grown complex, duplicated, or cluttered — clean up structure and remove dead code without changing observable behavior
  • 100how-to-refactor
    When the user asks to refactor, restructure, extract, rename, simplify, or clean up code without changing behavior, consult this skill to decide whether to delegate to the refactor subagent and how to craft the prompt.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.