CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

mitigate-breaking-changes

Patterns and techniques for mitigating breaking changes in Azure management-plane SDKs. Covers SDK-side customizations (partial classes, CodeGenType, CodeGenSuppress) and TypeSpec decorator customizations (clientName, access, markAsPageable, alternateType, hierarchyBuilding).

Quality

74%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

—

The risk profile of this skill

Fix and improve this skill with Tessl

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

Quality

Content

67%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 dense, highly actionable instruction skill: concrete code and TypeSpec examples with explicit warnings, preconditions, and post-change validation guidance. Its weaknesses are repeated @@hierarchyBuilding/approval caveats that could be consolidated, an unresolvable external doc link, and abstract references to the regeneration and detector commands.

Suggestions

Consolidate the three statements of the @@hierarchyBuilding approval requirement (intro paragraph, "legacy escape hatch" note, and "Legacy-only scenarios" block) into a single clearly-marked section.

Factor the shared decorator requirements (add `using Azure.ClientGenerator.Core.Legacy;`, add the `#suppress` line, regenerate) into one note instead of repeating them under both @@markAsPageable and @@hierarchyBuilding.

Name the actual commands for regenerating the SDK and running the standalone breaking-change detector, and fix or remove the `../../../doc/dev/SDKBreakingChanges.md` relative link, which will not resolve inside the skill bundle.

DimensionReasoningScore

Conciseness

The body is mostly imperative with tight code snippets and no padding with basics Claude already knows, but it could be tightened: the @@hierarchyBuilding approval caveat is stated three times ("Do **not** use @@hierarchyBuilding...", "legacy escape hatch. Use it only with explicit owner approval", and the "Legacy-only scenarios that require explicit approval" block), and the using/#suppress/regenerate requirements are duplicated under both @@markAsPageable and @@hierarchyBuilding. This matches anchor 3 (mostly efficient, some repetition that could be trimmed) rather than anchor 4's "minor instances".

3 / 5

Actionability

Concrete, near-executable examples throughout: a partial-class C# snippet, `[CodeGenType("OriginalTypeSpecModelName")]`, exact TypeSpec decorator invocations, the `enable-wire-path-attribute: true` tspconfig.yaml block, and WRONG/CORRECT `Read<>` vs `ActionSync<>` examples. Minor gaps keep it below anchor 5: examples use `<Service>` placeholders and `...` elisions, and the actual regeneration/detector commands are never named.

4 / 5

Workflow Clarity

The workflow branches explicitly by mitigation type (generator / client customization / manual) with preconditions and stop conditions, and post-change validation is explicit: "regenerate and compile fresh artifacts..., rerun the standalone detector, then run ordinary builds, analyzers, and tests separately. Do not treat a missing GA baseline, stale artifact, or detector failure as a compatibility pass." It falls short of anchor 5 because the workflow is branchy prose rather than a sequenced checklist and there is no explicit validate→fix→retry loop for detector failures.

4 / 5

Progressive Disclosure

No bundle files exist (references/, scripts/, assets/ are absent), and the body is well-structured with clear ## and ### sections covering distinct pattern families. The only reference is the external link `[.NET pattern catalog](../../../doc/dev/SDKBreakingChanges.md)`, a repo-relative path that will not resolve inside a skill bundle, and ~200 lines of decorator detail could arguably be split into reference files — minor organization gaps matching anchor 4 rather than the appropriately-split, well-referenced anchor 5.

4 / 5

Total

15

/

20

Passed

Description

70%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 highly specific, well-scoped description with strong keyword coverage and near-zero conflict risk, written in third person. Its main weakness is the absence of an explicit "Use when..." trigger clause in the frontmatter, which caps completeness at 3.

Suggestions

Add an explicit trigger clause to the description, e.g. "Use when regenerating Azure management-plane .NET SDKs produces ApiCompat breaking-change errors or when backward compatibility of the SDK surface must be preserved."

Include natural user phrasings such as "backward compatibility", "ApiCompat", and "SDK regeneration" alongside the technical decorator names.

Mention the WirePathAttribute/emitter-option and extension-resource patterns so the description's coverage matches the body's actual scope.

DimensionReasoningScore

Specificity

The description names the domain ("mitigating breaking changes in Azure management-plane SDKs") and enumerates concrete mechanisms: "partial classes, CodeGenType, CodeGenSuppress" and "clientName, access, markAsPageable, alternateType, hierarchyBuilding". These are specific tool/decorator names rather than full actions, and body topics like WirePathAttribute emitter options and extension resources are unmentioned, so coverage has minor gaps — matching anchor 4 rather than the comprehensive anchor 5.

4 / 5

Completeness

The "what" is explicit and clear ("Patterns and techniques for mitigating breaking changes... Covers SDK-side customizations... and TypeSpec decorator customizations"), but there is no "Use when..." clause or equivalent trigger guidance in the description — the trigger phrases live only in the body. Per the rubric guideline, a missing explicit "when" caps completeness at 3, and anchor 3 (clear what, when missing) is the exact fit.

3 / 5

Trigger Term Quality

"mitigating breaking changes", "Azure management-plane SDKs", "TypeSpec", and the named decorators ("markAsPageable", "hierarchyBuilding", "CodeGenType") are terms users of this workflow would naturally say or paste from errors. Common variations like "backward compatibility", "ApiCompat", "regeneration", and ".NET" are missing, so it fits anchor 4 (good coverage, a few natural terms missing) rather than anchor 5.

4 / 5

Distinctiveness Conflict Risk

"Azure management-plane SDKs" plus generator-specific names like "CodeGenType", "CodeGenSuppress", and "markAsPageable" define a clear niche with distinct triggers and minimal conflict risk; even closely related SDK skills would not collide with these terms. Not anchor 4, because the overlap risk with any other skill is negligible rather than minor.

5 / 5

Total

16

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

relative_links

Relative link issues: 1 suspicious

Warning

Total

15

/

16

Passed

Repository

Azure/azure-sdk-for-net

Path

.github/skills/mitigate-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.