Name: mitigate-breaking-changes
Rating: 66.4 (1 reviews)
Author: Azure

mitigate-breaking-changes

Patterns and techniques for mitigating breaking changes during Azure management-plane SDK migration from Swagger/AutoRest to TypeSpec. Covers SDK-side customizations (partial classes, CodeGenType, CodeGenSuppress) and TypeSpec decorator customizations (clientName, access, markAsPageable, alternateType, hierarchyBuilding).

Quality

78%

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

Fix and improve this skill with Tessl

tessl review fix ./.github/skills/mitigate-breaking-changes/SKILL.md

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 highly actionable with executable code and clear regeneration/ApiCompat feedback loops, and is well-structured by section. It is slightly verbose in a few explanatory asides and could offload some reference-style catalogs to bundle files for better progressive disclosure.

Suggestions

Trim consequence-explanation bullets (e.g. the CS1729/CS0029/CS1503 list under Sub-Resource Operations) to the bare minimum needed to identify the symptom.

Add an explicit 're-run ApiCompat after regenerate' checkpoint to each customization pattern that changes the SDK surface, not just the WirePathAttribute section.

Consider moving the full decorator syntax catalog and extension-resources detail into reference files under references/ to make SKILL.md a leaner overview with one-level-deep links.

Dimension	Reasoning	Score
Conciseness	Dense and assumes Claude's competence (no padding about what TypeSpec or breaking changes are), but retains minor explanatory asides such as the 'Common target base types' parentheticals and the consequence bullets under Sub-Resource Operations that could be trimmed.	4 / 5
Actionability	Provides fully executable, copy-paste-ready C#, TypeSpec, and YAML snippets with exact file paths, attribute arguments, 'using' imports, and '#suppress' directives, covering the common migration cases.	5 / 5
Workflow Clarity	Multi-step regeneration workflows include explicit checkpoints (ApiCompat detect → fix → regenerate → residual-baseline; 'After adding the decorator, regenerate'), but re-verification is not uniformly restated across every customization pattern, leaving minor validation gaps.	4 / 5
Progressive Disclosure	Well-organized into clear section headers with no nested references (no bundle files exist), but the dense decorator catalog and extension-resources detail are inlined rather than offloaded to reference files, so the ideal one-level-deep split is not fully realized.	4 / 5
	Total	17 / 20 Passed

Description

75%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 specific, distinctive, and rich in natural trigger terms for its niche, but it omits an explicit 'when to use' clause, leaving the trigger guidance implicit and capping completeness. Adding a 'Use when...' sentence would raise the completeness score.

Suggestions

Append an explicit trigger clause, e.g. 'Use when migrating or regenerating Azure management-plane .NET SDKs and you need to preserve backward compatibility in the generated surface.'

Add a couple of natural-language variations users might say ('keep backward compat', 'fix ApiCompat errors', 'base type change') alongside the technical decorator names.

Consider mentioning the ApiCompat failure signals (e.g. 'CannotRemoveBaseTypeOrInterface') as additional natural trigger terms.

Dimension	Reasoning	Score
Specificity	Names a concrete domain (Azure management-plane SDK migration from Swagger/AutoRest to TypeSpec) and enumerates a comprehensive set of specific mechanisms — 'partial classes, CodeGenType, CodeGenSuppress' and six named decorators 'clientName, access, markAsPageable, alternateType, hierarchyBuilding'.	5 / 5
Completeness	Has a clear, specific 'what' but no explicit 'Use when...' clause or equivalent trigger guidance in the description — 'when' is only weakly implied by the migration context, capping completeness at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	Contains natural technical trigger terms a migration engineer would say ('CodeGenType', 'CodeGenSuppress', 'markAsPageable', 'hierarchyBuilding', 'mitigate breaking changes'), but lacks broader synonym/variation coverage typical of a 5.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear, narrow niche (Azure ARM SDK TypeSpec migration breaking-change mitigation) with named TypeSpec/Azure decorators unlikely to match other skills, giving minimal conflict risk despite a sibling mpg-migration skill.	5 / 5
	Total	17 / 20 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: Azure/azure-sdk-for-net
Path: .github/skills/mitigate-breaking-changes/SKILL.md
Commit: bc946a1

Reviewed: 3 days 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.