SkillAgentSearch skills...

oma-refactor

Restructure existing code while preserving observable behavior. Use

Install / Use

npx skills add first-fluke/oh-my-agent --skill oma-refactor

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

87/100

Supported Platforms

Universal

Our assessment of oma-refactor

oma-refactor scores 87/100 on our quality scale, 2050th of 4,700 Development & Engineering skills we index (top 44%).

Its SKILL.md is 12 KB long, well organised into 25 sections with 1 code example: a thorough specification that gives an agent plenty to work with.

With 1,324 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
17/20
Description
12/15
Adoption
13/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so oma-refactor is actively maintained.
  • Our last check on 2026-11-01 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-10-01. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

oma-refactor compared with similar skills

All 4 of these similar skills score higher than oma-refactor; compare them before choosing.

SkillScoreStarsUpdatedFormat
oma-refactor (this skill)by first-fluke871.3k54d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md
lobehubby lobehub10085.6ktodayMCP Server

Frequently asked questions

How do I install oma-refactor?
Run npx skills add first-fluke/oh-my-agent --skill oma-refactor. The install tabs above show the steps for each supported agent.
Which AI agents does oma-refactor work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is oma-refactor safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is oma-refactor still maintained?
The repository was last updated about 2 months ago, so oma-refactor is actively maintained.

name: oma-refactor description: Restructure existing code while preserving observable behavior. Use for targeted technical debt or hotspot work with characterization tests.

Refactor Agent - Behavior-Preserving Restructuring Specialist

Scheduling

Goal

Improve internal code structure - readability first - without changing observable behavior, through small verified transformations, each gated by a safety net (tests / tooling / types) and committed separately from any behavior change.

Intent signature

  • User asks to refactor, clean up, restructure, modernize, de-duplicate, or "make this code maintainable/readable".
  • User mentions code smells, technical debt, legacy code, long methods/files, god classes, hotspots, characterization tests, or extract/move/rename transformations.
  • User asks "where should we refactor first?" or wants a refactoring plan/priority for a codebase.

When to use

  • Executing a refactoring on specific files/modules (extract, move, rename, decompose, pattern/idiom alignment)
  • Preparatory refactoring before a feature ("make the change easy, then make the easy change")
  • Legacy (brownfield) rescue: seam discovery + characterization tests, then restructuring
  • Refactoring target selection and prioritization (smells + SATD + hotspot = churn x complexity)
  • Auditing whether code is safe to refactor now (coverage breadth x mutation strength x flakiness)

When NOT to use

  • Fixing a reported bug or failing behavior -> use oma-debug (refactoring must not change behavior)
  • Security/performance/accessibility review or quality audit -> use oma-qa
  • System design, module boundary decisions, ADRs, convention changes -> use oma-architecture (a convention/pattern change is an architecture decision, not a local refactoring)
  • DB schema design or migration mechanics -> use oma-db (this skill only plans the expand-contract sequence)
  • Commit splitting / staging mechanics -> use oma-scm
  • Performance optimization as a goal -> out of scope by definition (tuning is a side effect, never the objective)

Expected inputs

  • target: file/module/path, smell report, SATD marker, or the feature request motivating preparatory refactoring
  • verification: project test command(s) per the tool registry; coverage/mutation tooling if available
  • constraints: coding guide / conventions, regulated-environment flags, merge-window concerns
  • Optional: prior metric reports, hotspot data, ADRs touching the target area

Expected outputs

  • Refactored code as a sequence of atomic, refactor-only commits (no test changes mixed in)
  • Safety-net additions when missing (characterization / golden-master tests) as separate commits
  • Before/after report: metric delta (cyclomatic/cognitive complexity, size, coupling) + readability verdict
outputs:
  - name: report
    description: refactoring plan or before/after report
    artifact: ".agents/results/refactor/*.md"
    required: false

Standalone runs write plan / before-after reports under .agents/results/refactor/; orchestrated runs (via the refactor-engineer agent) write .agents/results/result-refactor[-{sessionId}].md per the agent execution protocol.

Dependencies

  • resources/definition.md (invariant definition: 5 properties, boundaries, destination principle, naming roles, inline evidence)
  • resources/measurement.md (4-layer measurement + git forensics commands)
  • resources/governance.md (org parameters: budget floor, 500-line gate, tool registry)
  • Configured code-intelligence symbol/reference tools or native inspection; project test runners per registry (vitest / pytest / flutter_test)
  • Git history for churn/ownership/hotspot analysis

Control-flow features

  • Branches by safety-net state (greenfield vs brownfield), statefulness (code-only vs expand-contract), and verification outcome (pass vs Mikado revert)
  • Reads code/history/metrics; writes code, tests (in separate commits), and reports
  • Stops and routes to oma-architecture when the change requires a convention/boundary decision

Structural Flow

Entry

  1. Establish what motivates the refactoring (smell, SATD, hotspot, or upcoming feature) and the target scope.
  2. Diagnose the safety net for that scope: coverage of changed lines, test determinism (flakiness), mutation strength if measurable.
  3. Identify the destination form: the language idiom and codebase convention the result must match.

Scenes

  1. PREPARE: Classify greenfield (safety net exists) vs brownfield (build net first); check size gates and hotspot rank; confirm two-hats scope (no feature/bug work mixed in).
  2. ACQUIRE: Read target code via symbol tools; collect metrics (complexity, size, coupling) and git signals (churn, ownership); read the coding guide for conventions.
  3. REASON: Decompose the goal into a sequence of named atomic transformations; for stateful targets plan expand-contract; verify each step is independently verifiable and revertible.
  4. ACT: Apply ONE transformation; prefer deterministic engines (IDE rename, codemod, ast-grep) over freehand edits. When one feature spans several files after a split, consider G-5's optional header map if it helps navigation.
  5. VERIFY: Re-run existing tests unchanged. Pass -> commit (refactor-only) -> next transformation. Repeated failure -> Mikado: record the broken prerequisite, revert fully, recurse on the prerequisite first.
  6. FINALIZE: Before/after metric delta + readability judgment (metric improvement alone is not success); report follow-ups discovered but deliberately not done.

Transitions

  • If the safety net is missing or weak (low diff coverage, flaky, no assertions), write characterization / golden-master tests FIRST, committed separately, before touching production code.
  • If verification fails repeatedly, switch to the Mikado method: never carry a half-broken tree forward.
  • If the right fix is a convention or pattern change (new dialect), stop and route to oma-architecture for an ADR + ratchet plan.
  • If the target involves persisted state or external consumers, plan expand-contract (parallel change) with feature flags; deployment, not commit, becomes the unit of incrementality.
  • If a behavior bug is discovered mid-refactoring, record it and route to oma-debug; do not fix it in the refactor commit.
  • If the work is large enough to collide with teammates' branches, recommend announcement + short merge window; register bulk mechanical commits in .git-blame-ignore-revs.

Failure and recovery

| Failure | Recovery | |---------|----------| | Tests fail after a transformation | Mikado: record prerequisite, revert all, attack prerequisite first | | No tests and code is untestable | Find a seam; apply only minimal mechanical changes to inject test access, then characterize | | Tests are flaky | Fix or quarantine flaky tests before refactoring - an unreliable net is no net | | Metric improves but readability worsens | Reject the transformation; readability is the success criterion, metrics are proxies | | Scope keeps growing | Stop; report the boundary issue and split into a Mikado graph or route to architecture | | Refactoring engine/codemod produces wrong output | Engines are not infallible - tests re-run is mandatory; fall back to manual atomic edits |

Exit

  • Success: behavior verified unchanged, structure measurably improved, readability confirmed, refactor-only commits, follow-ups reported.
  • Partial success: safety net built but restructuring deferred; or prerequisites mapped (Mikado graph) with explicit blockers.
  • Failure: blocking ambiguity (no verification path, regulated freeze, convention decision needed) reported with the recommended route.

Logical Operations

Actions

| Action | SSL primitive | Evidence | |--------|---------------|----------| | Diagnose safety net | VALIDATE | Coverage/flakiness/mutation state of target scope | | Collect signals | READ | Metrics, git churn/ownership, smells, SATD | | Rank targets | COMPARE | Hotspot = complexity x churn | | Plan atomic sequence | INFER | Named transformations, Mikado graph | | Write characterization tests | WRITE | Golden-master/snapshot tests (separate commit) | | Apply transformation | WRITE / CALL_TOOL | One atomic refactor, engine-first | | Verify preservation | VALIDATE | Existing tests re-run unchanged | | Commit separately | UPDATE_STATE | refactor:-typed commits only | | Report delta | NOTIFY | Metric + readability before/after |

Tools and instruments

  • Configured code intelligence for symbol/reference/pattern impact analysis; an available semantic rename engine for renames. Native inspection remains valid, but do not replace a semantic rename with blind text replacement
  • Deterministic transformers: IDE refactoring actions, codemods (jscodeshift / OpenRewrite / ast-grep / comby)
  • Metrics: lizard / radon (complexity) — both are PyPI packages, run via uvx lizard / uvx radon so no pre-install is required; per-language linters with max-lines gates
  • Test stack per registry: vitest + StrykerJS / pytest + mutmut / flutter_test (see resources/governance.md)
  • Git forensics one-liners (see resources/measurement.md)

Canonical workflow path

  1. Diagnose: run coverage on the target scope and check test determinism; classify green/brownfield.
  2. If brownfield: find a seam, write characterization (golden-master) tests for CURRENT behavior, commit.
  3. Select targets by hotspot rank (complexity x churn), not by smell aesthetics alone.
  4. Plan a sequence of named atomic transformations toward the language-idiomatic, convention-conforming form.
  5. Loop per transformation: apply (engine-first) -> re-run tests UNCHANGED -> commit refactor: only. On repeated failure: record prerequisite, revert fully, recurse (Mikado).
  6. Finish: metric delta + readability verdict; list discovered-but-deferred work; never mix in behavior changes.

Resource scope

| Scope | Resource target | |-------|-----------------| | CODEBASE | Target source, tests, coding guide, lint configs | | LOCAL_FS | Reports under .agents/results/refactor/, .git-blame-ignore-revs | | PROCESS | Test runners, coverage/mutation tools, codemod engines, git log analysis | | MEMORY | Mikado prerequisite graph, deferred follow-ups, metric baselines |

Preconditions

  • A verification path exists or can be built (tests/types/tooling); otherwise the first deliverable is the safety net, not restructuring.
  • The target's conventions are known (coding guide read) or explicitly absent.

Effects and side effects

  • Mutates production code (structure only) and adds tests in separate commits.
  • Runs test/coverage/mutation commands; reads git history.
  • May write reports under .agents/results/refactor/ and entries to .git-blame-ignore-revs.
  • Never alters observable behavior, public contracts, or persisted data without an expand-contract plan.

Guardrails

  1. Behavior-preserving: the consumer contract (Hyrum-aware) is inviolable; tuning is a side effect, never a goal.
  2. Verifiable: never restructure without a net; during production refactoring tests are frozen, during test refactoring production is frozen - one side at a time.
  3. Incremental: one named transformation per commit; revert is a navigation tool (Mikado), not an accident.
  4. Economic: readability is the objective function's dominant term; do not refactor code slated for deletion or cold low-churn code.
  5. Separated (two hats): never mix behavior changes into refactor commits; tangled changes are a measured quality risk.
  6. Destination = f(language idiom, code layer, codebase convention); convention deviation requires the ADR route, not a local edit.
  7. Abstraction timing follows the Rule of Three; speculative generality is itself a smell.
  8. All metrics are proxies (Goodhart): a 499-line mechanical split, assertion-free coverage, or pattern-count gains are failures, not win

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars1.3k
CategoryDevelopment
Updated1mo ago
Forks151

Languages

TypeScript

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions