CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

oma-refactor

Restructure existing code while preserving observable behavior. Use for targeted technical debt or hotspot work with characterization tests.

Quality

77%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/oma-refactor/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a strong, expert-oriented skill body: a sequenced workflow with real validation checkpoints and feedback loops, concrete tooling and path guidance, and disciplined routing to adjacent skills. The few gaps are cosmetic — slight reinforcement redundancy of the two-hats rule, deferred commands in reference files that are not part of this bundle, and a broken bullet list in the References section.

DimensionReasoningScore

Conciseness

The body is dense and expert-level, assuming competence (Mikado method, Hyurn-aware contracts, Rule of Three, SATD, expand-contract are invoked without explanation) and wasting no tokens teaching known concepts. It stays below anchor 5 only because the two-hats rule ("never mix behavior changes") is restated in the Goal, When NOT to use, workflow steps 1 and 9, and Guardrail 5 — reinforcement that could be trimmed.

4 / 5

Actionability

As an instruction-only skill the guidance is concrete: named tools (lizard, radon, jscodeshift, OpenRewrite, ast-grep, comby), concrete paths (`.agents/results/refactor/*.md`, `.git-blame-ignore-revs`), an output contract, and a decision procedure per workflow step. It misses anchor 5 mainly because executable commands (e.g., the git forensics commands) are deferred to `resources/measurement.md`, which is not present in this bundle.

4 / 5

Workflow Clarity

The canonical workflow is a clearly sequenced 9-step path with explicit validation (re-run existing tests unchanged after each single transformation, commit separately), an explicit feedback loop (Mikado: record prerequisite, undo only that transformation, recurse), a failure/recovery table covering seven failure modes, and explicit exit criteria. This matches anchor 5's "clear sequence with explicit validation steps; feedback loops for error recovery".

5 / 5

Progressive Disclosure

The body is well structured with clear sections and a References list that signals each external resource with a one-line description, all one level deep (e.g., "Invariant definition (5 properties, boundaries, destination, naming roles...): `resources/definition.md`"). It falls short of anchor 5 because the referenced files (`resources/*.md`, `../_shared/core/*.md`) do not resolve within this bundle, and a stray blank line between the first and second reference bullets breaks the list rendering.

4 / 5

Total

17

/

20

Passed

Description

62%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is concise, honest, and clearly scoped to behavior-preserving restructuring with an explicit use-when clause. Its main weaknesses are the absence of the word "refactor" (and common synonyms) as a trigger term and a what-clause that stays at the level of one general action rather than naming the concrete transformations the skill performs.

Suggestions

Include the words "refactor"/"refactoring" and common synonyms like "clean up" or "modernize" so the description triggers on the phrasing users most naturally use.

List 2-3 concrete transformation types (e.g., extract method, move/rename, split long methods or god classes) to raise specificity from one general action to several concrete ones.

Broaden the "Use when" clause beyond targeted technical debt or hotspot work to also cover general "make this code more readable/maintainable" requests.

DimensionReasoningScore

Specificity

"Restructure existing code while preserving observable behavior" plus "characterization tests" names the domain and 1-2 concrete actions, but the description never lists the specific transformations the skill actually handles (extract, move, rename, decompose). It falls short of anchor 4's "lists several specific actions; minor gaps in coverage".

3 / 5

Completeness

Both parts are explicit: the what ("Restructure existing code while preserving observable behavior") and the when ("Use for targeted technical debt or hotspot work with characterization tests"). The when-clause is present and explicit but narrow — it names debt/hotspot scenarios yet misses everyday "refactor this" requests, so it does not reach anchor 5's comprehensive concrete trigger phrases.

4 / 5

Trigger Term Quality

Terms like "restructure", "technical debt", "hotspot", and "characterization tests" are relevant, but the single most natural user phrasing — "refactor" — is absent, along with synonyms like "clean up" or "modernize". This matches anchor 3 ("some relevant keywords but missing common variations or synonyms") rather than anchor 4's good coverage.

3 / 5

Distinctiveness Conflict Risk

"Preserving observable behavior" carves a clear niche distinct from bug-fixing, implementation, and optimization skills, and "characterization tests" is a distinctive trigger. Minor overlap risk remains with general code-editing/cleanup skills because the common term "refactor" is not claimed, keeping it below anchor 5.

4 / 5

Total

14

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

first-fluke/oh-my-agent

Path

.agents/skills/oma-refactor/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.