agentsclimarketplace
Sign in

Refactor safely

Skill contextosai/skills/skills/refactor-safely

Restructure existing code while preserving externally observable behavior through explicit invariants, characterization evidence, small reversible steps, and continuous verification. Use when the user asks to refactor, simplify, extract, reorganize, modularize, deduplicate, split a component, improve architecture, or pay down technical debt without intentionally changing product behavior. Distinguish refactoring from feature work and stop scope drift from hiding inside structural edits.From its SKILL.md

Install
npx -y skills add contextosai/skills --skill refactor-safely

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.6 KB, 409 tokens by cl100k_base, as published. Nobody here has run it

Refactor Safely

Change structure while keeping the behavior contract stable.

Protocol

  1. Define the refactor boundary and list observable behavior that must not change: API, side effects, ordering, errors, timing-sensitive semantics, persistence, telemetry, and extension points.
  2. Trace callers and consumers across the boundary. Include reflection, registration, configuration, serialization, and framework conventions that symbol search may miss.
  3. Assess existing proof. If behavior is weakly specified, add the smallest characterization tests around high-risk invariants before restructuring. Do not encode accidental behavior without evaluating whether callers rely on it.
  4. Choose a seam that permits incremental movement. Prefer mechanical moves, then semantic cleanup; do not combine both when the diff would obscure behavior changes.
  5. Execute one reversible transformation at a time. Keep old and new paths from diverging during transition; use adapters or delegation briefly when needed.
  6. Verify after each meaningful step with focused checks, then run boundary and broader tests proportional to risk.
  7. Compare before/after public surface, generated artifacts, state transitions, error behavior, and performance where relevant.
  8. Remove transitional code only after all callers migrate and proof covers the new path. Search for stale imports, registrations, flags, and documentation.

Guardrails

  • Do not sneak bug fixes or feature changes into a behavior-preserving claim. Split and label intentional behavior changes.
  • Do not equate compilation with behavioral equivalence.
  • Do not introduce an abstraction before identifying at least one stable invariant it owns.
  • Avoid wrappers that merely relocate complexity or duplicate sources of truth.
  • Preserve user edits and repository conventions; prefer the smallest reviewable sequence over a sweeping rewrite.

Output

For planning-only requests, use references/refactor-ledger.md. For implementation requests, maintain the ledger while editing and report preserved invariants, intentional deviations, checks run, and residual risks.

What ships with it: 2 files

1.3 KB alongside SKILL.md

agents/

references/

Gives 0 of the 12 instructions most refactoring skills give in 409 tokens

Counted across 545 of the 587 authors here whose files we hold, read 2026-09-06

  • Run tests after each changein 61 of 545, across 59 files
  • Run tests before refactoringin 42 of 545
  • Revert immediately if tests failin 31 of 545, across 28 files
  • Perform refactoring in small stepsin 30 of 545, across 29 files
  • Write characterization tests for untested codein 21 of 545, across 19 files
  • Remove dead code and unused importsin 20 of 545
  • Identify code smellsin 20 of 545
  • Perform one refactoring at a timein 19 of 545
  • Commit after each successful refactoringin 17 of 545, across 15 files
  • Verify all tests pass after refactoringin 17 of 545
  • Keep refactoring separate from behavior changesin 16 of 545, across 14 files
  • Run the full test suitein 16 of 545

Said here and by no other author read

  • List observable behavior to preserve
  • Trace all callers and consumers
  • Add characterization tests for high-risk invariants
  • Execute one reversible transformation at a time
  • Compare public surface before and after
  • Remove transitional code after migration

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.