CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

refactor-plan

Judge whether a system is fragile or just fast-moving, and write a ticket-ready refactor plan for one root problem, with measured evidence and a stable fingerprint. Use after system history (or a bug trace) points at a systemic problem worth fixing at the root.

Quality

90%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

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

An exemplarily lean skill body: executable scaffold command, concrete fill and acceptance criteria, and clean one-level-deep progressive disclosure into real reference files. The only gap is that the failure/retry loop for the findings-upsert acceptance check is delegated to the reference rather than stated explicitly.

DimensionReasoningScore

Conciseness

The ~30-line body is dense and lean: every line directs action ("Replace every `TODO(agent)` marker", "Keep slugs stable across runs", "Plans go to `<plansDir>/<run>/<slug>.md`") with zero padding and no explanation of concepts Claude already knows. Clearly matches the anchor-5 example of every token earning its place.

5 / 5

Actionability

Provides a copy-paste-ready scaffold command with enumerated flags and area values (`pnpm exec tsx .agents/skills/refactor-plan/scripts/new-plan.ts --run <id> --slug <kebab> ... --area <Framework|Slides|...>`), the exact output location, concrete bug-plan variant behavior, and an explicit done criterion (findings-upsert.ts acceptance). Delegates detail to real, existing reference files — fully executable guidance matching anchor 5.

5 / 5

Workflow Clarity

Clear sequence across sections — judge first (rubric.md, read diffs, find a named repeated mechanism), scaffold (command), fill (replace markers per plan-guide.md), with an explicit end-state validation ("A plan is finished when fragility-common's `findings-upsert.ts` accepts it"). The recovery loop when findings-upsert.ts rejects a plan (fix markers/confidence, re-run) is only implied via the reference rather than stated in the body, which is the minor checkpoint gap of anchor 4 rather than the explicit feedback loop of anchor 5.

4 / 5

Progressive Disclosure

The body is a concise overview with two well-signaled, one-level-deep references — "`references/rubric.md` separates fragile from fast-moving from coupled, and sets confidence" and "following `references/plan-guide.md`" — both of which exist in the bundle and carry the detail, while executable logic lives in `scripts/new-plan.ts` (with `lib.ts`). No nested doc chains, content appropriately split; matches anchor 5.

5 / 5

Total

19

/

20

Passed

Description

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

A strong description: it states what the skill does in concrete, third-person terms, includes an explicit and specific 'Use after...' trigger clause, and occupies a distinct niche. Trigger-term coverage is good but not exhaustive — synonyms like 'tech debt' or 'keeps breaking' would strengthen it.

DimensionReasoningScore

Specificity

Names concrete actions — "Judge whether a system is fragile or just fast-moving" and "write a ticket-ready refactor plan for one root problem" — with specific deliverable attributes ("measured evidence", "a stable fingerprint"). Falls between anchor 3 (1-2 concrete actions, not comprehensive) and anchor 5 (comprehensive coverage); it is more specific than 3 but does not enumerate the full range of capabilities, so 4 fits.

4 / 5

Completeness

Explicitly answers both questions: what ("Judge whether a system is fragile or just fast-moving, and write a ticket-ready refactor plan... with measured evidence and a stable fingerprint") and when ("Use after system history (or a bug trace) points at a systemic problem worth fixing at the root") with concrete trigger conditions. The 'when' clause is explicit and specific, so it exceeds anchor 4 ('when' could be more explicit) and matches anchor 5.

5 / 5

Trigger Term Quality

Contains natural domain terms a user would say — "refactor plan", "fragile", "system history", "bug trace", "systemic problem", "root" — but misses common synonyms and variations such as "tech debt", "keeps breaking", or "repeated bugs". Good coverage without being comprehensive, matching anchor 4 rather than 5.

4 / 5

Distinctiveness Conflict Risk

Carves a clear niche — fragility triage that produces a deduplicated, ticket-ready root-cause plan — with a distinct trigger gated on prior system history or a bug trace. Minor theoretical overlap with a generic refactoring skill, but the trigger and deliverables (fingerprint, measured evidence) are distinct enough to match anchor 5 over anchor 4.

5 / 5

Total

18

/

20

Passed

Validation

81%

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

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

metadata_field

'metadata' should map string keys to string values

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

13

/

16

Passed

Repository

BuilderIO/agent-native

Path

.agents/skills/refactor-plan/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.