Tessl • The management layer for AI agent skills

SkillPublic

refactor

Refactoring process with test safety. Invoke immediately when user or document mentions refactoring, or proactively when code gets too complex or messy.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

82%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.

The body is a tight, highly actionable process document with explicit test checkpoints, commit conventions, and a summary template. Its few gaps are the redundant 'Stages' TOC, the missing failure-recovery loop when a refactor breaks tests, and an unlinked bundle file.

Suggestions

Add an explicit recovery step to the Main Refactoring loop, e.g., "If tests fail after a change, revert the commit (`git revert HEAD`) or restore the file and try a smaller refactoring" — this supplies the error feedback loop the top workflow anchor requires.

Remove the 'Stages' section (or fold it into the intro line) since it restates the four numbered section headers that immediately follow, trimming duplicate tokens.

Link the attribution file from the body (e.g., a 'Credits' line pointing to references/credits.md) so the bundle file is discoverable rather than orphaned.

Dimension	Reasoning	Score
Conciseness	The body is lean and imperative with no re-teaching of concepts Claude already knows, but the 'Stages' list duplicates the four numbered section headers that follow — a small redundancy that keeps it below the 'every token earns its place' anchor.	4 / 5
Actionability	Guidance is fully executable: verbatim REFACTORING_SUMMARY.md templates, the exact commit message format "- r <refactoring>", a concrete test-change-test-commit loop, and specific code-style directives — copy-paste ready with the common cases covered.	5 / 5
Workflow Clarity	The four-stage sequence is clear with test checkpoints before and after every change, but there is no error-recovery step for when a post-change test fails (no revert-and-retry guidance), which the anchor for 5 requires as an explicit feedback loop.	4 / 5
Progressive Disclosure	Sections are well organized and the process content is appropriately kept inline for a single-file skill, but the provided bundle file references/credits.md is never referenced from the body — a minor navigation gap rather than the clean one-level-deep structure of the top anchor.	4 / 5
	Total	17 / 20 Passed

Description

78%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 compact, in third person, and answers both what and when with an explicit two-condition trigger clause. Its main weakness is a thin 'what' — the capability is stated in one generic phrase without the specific refactoring actions the skill actually performs.

Suggestions

Enumerate the concrete actions in the 'what' clause, e.g., "Refactors production code (renames, extracts methods, removes dead code) while keeping tests untouched and green" to raise specificity from domain-plus-qualifier to several listed actions.

Add natural synonyms users say, such as "clean up code", "restructure", or "tidy up", to the trigger phrasing so the description matches the keywords already listed in the frontmatter triggers.

Dimension	Reasoning	Score
Specificity	"Refactoring process with test safety" names the domain plus one qualifier, matching the anchor for 1-2 concrete actions; it does not list the several specific actions (e.g., extracting methods, removing dead code) needed for a 4.	3 / 5
Completeness	It answers both what ("Refactoring process with test safety") and when with an explicit, multi-condition trigger clause ("Invoke immediately when user or document mentions refactoring, or proactively when code gets too complex or messy"), matching the anchor for concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural phrases like "mentions refactoring" and "code gets too complex or messy" are present, but common variations such as "clean up code", "restructure", or "tidy" are missing from the description.	4 / 5
Distinctiveness Conflict Risk	Refactoring is a clear niche with distinct triggers, but "code gets too complex or messy" has minor overlap with general code-cleanup/simplification skills, matching the 'minor overlap risk with closely related skills' anchor.	4 / 5
	Total	16 / 20 Passed

Validation

93%

Warnings & errors only

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

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: ericjohnolson/tessl-test
Path: tiles/crafter/skills/refactor/SKILL.md
Revision: 2a98cc1

Reviewed: 23 hours ago

Discovery Implementation Validation

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.

refactor

Table of Contents

Is this your skill?