How to use the API Breaking Change Detector agent skill

What is an agent skill and what does this one make the agent do?

An agent skill is a folder with a SKILL.md file that gives an AI coding agent a set of instructions for one kind of task. The agent reads those instructions when a request matches the skill's description.

This skill tells the agent to read your C# controllers, DTOs and route definitions, then find the frontend or client code that consumes them. It looks for mismatches in both directions. Backend changes that would break a client include renamed or removed JSON fields, new required parameters, and status codes the client does not handle. Frontend code that sends fields the backend ignores, or reads fields the backend no longer returns, is also flagged. The skill reports findings and does not change any code.

• Backend to client breaks: renamed or removed keys, new required request fields, response status codes the client does not handle, and changed response field types.
• Client to backend drift: fields the client sends that the backend ignores, and client code that reads response fields the backend no longer returns.
• Output: a report with scope, breaks grouped by endpoint, drift, unmatched endpoints, and a match confidence summary.

Install the skill from the ZIP download

Download the ZIP for the api-breaking-change-detector skill from this page. The skill is published in the github/awesome-copilot repository under skills/api-breaking-change-detector and is licensed under MIT. The package contains a single file, SKILL.md.

Choose one of two install locations. For a personal install available in all your projects, unzip the folder into ~/.claude/skills/. For a skill that only applies to one repository, unzip it into that project's .claude/skills/ folder so teammates who clone the repo get it too.

If you use the Claude apps rather than a coding tool, you can upload the ZIP instead. Open Settings, go to Capabilities, then Skills, and upload the file there.

• Personal install: ~/.claude/skills/api-breaking-change-detector/SKILL.md
• Project install: .claude/skills/api-breaking-change-detector/SKILL.md inside your repository
• Claude apps: Settings → Capabilities → Skills → upload the ZIP

Check what the skill needs before you start

The skill needs access to the files it audits: your C# source (controllers, DTOs and Program.cs) and the TypeScript or JavaScript client code in the same repository. Program.cs matters because the skill checks it for global JSON naming settings.

The skill file does not describe any API keys, accounts or network access. According to its metadata, it runs no scripts and uses no network. It works on source code, not on exported OpenAPI spec files.

• Read access to C# controllers, DTOs and Program.cs
• Read access to the TypeScript or JavaScript client code in the repository
• No scripts run and no network use, according to the skill metadata

Trigger the skill with a natural request

You do not need a special command. Describe what you want checked in plain language, and mention the DTO, controller or endpoint if you know it. The skill is written to trigger when you ask to check for breaking API changes, verify that frontend and backend contracts are in sync, or audit a DTO or controller change against its consumers before merging.

Be specific about scope. A single endpoint gives a focused report. Asking for the whole API surface before a release gives a broader audit that takes longer.

• "Will changing the CreateOrderRequest DTO break any frontend code?"
• "Check whether my UserController changes are still compatible with the React client."
• "Audit the API surface against its TypeScript consumers before the release branch is merged."
• "Verify frontend and backend contract sync for the billing endpoints."

Read the report: confidence and severity

The skill labels every finding with how it found the client code. Auto-generated clients from NSwag or OpenAPI Generator are a high-confidence match, matched by generated method or interface name. Hand-written fetch, Axios, HttpClient or similar calls are a medium-confidence match, matched by normalized URL pattern. If no client was found, the report says "No consumer located via static search" rather than guessing.

Breaks are marked as either a compilation error or a silent runtime failure. Frontend code that reads a response field the backend no longer returns is treated as the most serious kind of drift, because it can show as undefined at runtime.

• Auto-generated client match: high confidence
• Normalized route match in hand-written code: medium confidence
• No match: listed under No Consumer Found for manual confirmation
• Silent runtime failure: treated as high severity

Tips for useful results

The skill matches JSON names using global camelCase settings in Program.cs and any explicit JsonPropertyName attributes. Properties marked JsonIgnore are skipped. If your project uses a different naming setup, mention it in your request so the agent checks the right place.

Because the skill cannot prove an endpoint is unused from static code alone, treat the No Consumer Found section as a list to verify by hand, not as proof that code is dead.

• Name the DTO or controller when you can, to narrow the scope.
• Run the audit before merging a DTO change, not after the release.
• Confirm entries in No Consumer Found manually, since static search can miss calls.
• The skill does not modify code, so you still need to make and review any fixes yourself.