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

Quality

87%

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

85%

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

A well-structured, actionable review skill body with clear sequencing, embedded validation, and exemplary one-level-deep progressive disclosure. The only notable issue is mild redundancy between the description, the 'When to use' list, and the surface inventory.

Suggestions

Remove or condense the 'When to use' bullet list since those triggers already appear verbatim in the frontmatter description.

Consolidate the 'What is covered' list with the workflow's 'Inventory compatibility surfaces' step to eliminate the near-duplicate surface enumeration.

Dimension	Reasoning	Score
Conciseness	The body is largely lean and avoids explaining concepts Claude already knows, but the 'When to use' section repeats the description's trigger list verbatim and 'What is covered' overlaps with the workflow's surface inventory, so it could be tightened.	2 / 3
Actionability	For an instruction-only review skill it gives concrete, actionable guidance: a named four-tier classification (BREAKING / POTENTIALLY BREAKING / NON-BREAKING / UNKNOWN), enumerated compatibility surfaces, enumerated report elements, and explicit MUST/MUST NOT constraints.	3 / 3
Workflow Clarity	The five-step workflow is clearly sequenced (read reference -> inventory surfaces -> classify -> recommend migration -> report), and validation is embedded via the per-finding 'validation evidence or missing evidence' requirement and the mandated no-risk statement in the report.	3 / 3
Progressive Disclosure	SKILL.md is a lean overview that defers detailed guidance to a single, verified one-level-deep reference (references/056-design-avoid-breaking-changes.md), clearly signaled in the Workflow, Constraints, and a dedicated Reference section with easy navigation.	3 / 3
	Total	11 / 12 Passed

Description

90%

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, comprehensive description with explicit trigger guidance and good natural-language trigger terms. Its main weakness is second-person voice, which costs it one specificity point under the rubric.

Suggestions

Rewrite in third person (e.g., 'Reviews plans, OpenSpec changes... for breaking-change risk... Use when reviewing breaking changes in a spec') to avoid the second-person specificity penalty.

Trim the long surface enumeration slightly so the description stays scannable without losing concrete coverage.

Dimension	Reasoning	Score
Specificity	The description lists many concrete surfaces and actions ('commands, skills, generated outputs, XML sources, README/docs, tests, CI, APIs, schemas, configuration, data, migration, and release guidance'), which is comprehensive, but it is written in second person ('Use when you need to review'), triggering the rubric's one-point specificity penalty.	2 / 3
Completeness	It explicitly answers both what (review breaking-change risk across enumerated surfaces) and when ('Use when you need to...' plus a concrete 'This should trigger for requests such as' list), with explicit trigger guidance.	3 / 3
Trigger Term Quality	It provides natural trigger phrasings users would actually say — 'Review breaking changes in this spec', 'Check compatibility risks', 'Avoid breaking changes in this OpenSpec change', 'Review migration impact before release' — with good coverage of common variations.	3 / 3
Distinctiveness Conflict Risk	The breaking-change / compatibility-review niche is clearly framed with distinct triggers tied to specs, OpenSpec changes, and migration impact, making it unlikely to fire for unrelated skills.	3 / 3
	Total	11 / 12 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: jabrena/plinth
Path: skills/056-design-avoid-breaking-changes/SKILL.md
Commit: a8e5189

Reviewed: about 22 hours ago

Table of Contents

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.