CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

056-design-avoid-breaking-changes

Use when you need to review a plan, OpenSpec change, specification, or implementation proposal for breaking-change risk across commands, skills, generated outputs, XML sources, README/docs, tests, CI, APIs, schemas, configuration, data, migration, and release guidance. This should trigger for requests such as Review breaking changes in this spec; Check compatibility risks; Avoid breaking changes in this OpenSpec change; Review migration impact before release; Assess command and skill compatibility. Part of Plinth Toolkit

67

Quality

84%

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

SKILL.md
Quality
Evals
Security

Quality

Content

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

A well-structured overview body: lean token usage, a concrete classification taxonomy, a clear five-step workflow, and exemplary progressive disclosure with one real, one-level-deep reference file. The main improvement room is in actionability and workflow clarity, where inline checklists or a worked example would make the steps self-sufficient without the reference.

Suggestions

Add a compact inline checklist for step 2 (e.g., a one-line list of the exact files/directories to inspect for each surface like .cursor/commands, .agents/skills, README*.md) so the inventory step is executable without opening the reference.

Include a short worked example of one classified finding (e.g., a command renamed in a change → BREAKING → affected users + migration note) to make the step-3/step-4 output format concrete.

Add an explicit validation checkpoint between classification and reporting (e.g., 're-check that every BREAKING/POTENTIALLY BREAKING finding cites evidence; if evidence is missing, downgrade to UNKNOWN') to close the workflow's feedback loop.

DimensionReasoningScore

Conciseness

The body is lean and assumes competence — no space is spent explaining what breaking changes or OpenSpec are; sections are compact bullet lists and short steps. It is not a 5 because the "What is covered" bullet list substantially duplicates the surface enumeration already in the description, and lines like "**This is an interactive SKILL**" add little; it is well above a 3 since there is no concept over-explanation or padding.

4 / 5

Actionability

For an instruction-only skill the guidance is concrete: a mandated reference read ("MUST read references/056-design-avoid-breaking-changes.md before producing compatibility guidance"), an explicit classification taxonomy ("BREAKING, POTENTIALLY BREAKING, NON-BREAKING, or UNKNOWN"), and a defined report shape (reviewed sources, severity-ranked findings, validation guidance). It stops short of a 5 because steps like "Check commands, skills, generated outputs..." remain high-level pointers with no worked example, checklist, or command inline — the executable detail is deferred entirely to the reference file.

4 / 5

Workflow Clarity

Five clearly sequenced steps (read reference → inventory surfaces → classify → recommend migration → report) each carry concrete sub-instructions, and step 3 requires "validation evidence or missing evidence" per finding. It is not a 5 because there is no explicit feedback/checkpoint loop (e.g., verifying the inventory was complete or that each classification has evidence before reporting); it is not a 3 since the sequence is complete and step 3 embeds an evidence requirement.

4 / 5

Progressive Disclosure

The body is a pure overview: scope bullets, constraints, triggers, a 5-step workflow, and a single clearly-signaled one-level-deep reference — [references/056-design-avoid-breaking-changes.md](references/056-design-avoid-breaking-changes.md) — which exists as a real file containing the detailed guidance with no further nested references. This matches the anchor of a clear overview with well-signaled, one-level-deep references and easy navigation.

5 / 5

Total

17

/

20

Passed

Description

83%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 that explicitly covers both what the skill does and when to use it, backed by concrete quoted trigger phrases and a well-enumerated set of compatibility surfaces. Its only deductions are minor: a single dominant action verb, a few missing synonyms (e.g., backward compatibility, deprecation), and slight breadth-driven overlap with general review skills.

DimensionReasoningScore

Specificity

The description grounds itself in concrete review surfaces ("commands, skills, generated outputs, XML sources, README/docs, tests, CI, APIs, schemas, configuration, data, migration, and release guidance") and a clear action ("review a plan, OpenSpec change, specification, or implementation proposal for breaking-change risk"). It falls short of a 5 because it names essentially one action verb (review/assess) rather than multiple distinct capabilities, and above a 3 because the enumerated coverage goes well beyond naming a domain with 1-2 actions.

4 / 5

Completeness

Both questions are answered explicitly: the "what" is "review ... for breaking-change risk across" a concrete list of surfaces, and the "when" opens with "Use when you need to review a plan, OpenSpec change, specification, or implementation proposal" plus five literal trigger phrases. It matches the anchor 5 example pattern (what + explicit 'Use when' with concrete trigger phrases); it is not a 4 because the 'when' is not merely present but spelled out with quoted request examples.

5 / 5

Trigger Term Quality

It quotes natural user phrasings — "Review breaking changes in this spec; Check compatibility risks; Avoid breaking changes in this OpenSpec change; Review migration impact before release; Assess command and skill compatibility" — which are phrases a user would plausibly say. Not a 5 because common synonyms like "backward compatibility" or "deprecation risk" are absent, leaving a few natural trigger variants uncovered.

4 / 5

Distinctiveness Conflict Risk

The niche — breaking-change/compatibility review of OpenSpec changes and implementation proposals — is well-differentiated with distinct trigger phrases. It is not a 5 because the broad surface list (APIs, schemas, configuration, CI) creates minor overlap risk with general code-review or migration-review skills.

4 / 5

Total

17

/

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

jabrena/plinth

Path

skills/056-design-avoid-breaking-changes/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.