Overview

Compares the current Claude Code API surface against the plugin ecosystem to detect compatibility issues. It maps any breaking changes to the specific plugin files affected, enabling targeted migrations and risk assessment.

How This Skill Works

Loads the local api-surface.md, fetches the latest Claude Code API docs, and diffs added/changed/removed APIs. It then greps each plugin for impacted APIs and reports a file:line mapping of breakages.

When to Use It

• After Claude Code releases an API update
• Before publishing plugin updates to ensure compatibility
• When the changelog flags Removed, Changed, or Deprecated APIs
• During incident triage when a plugin fails due to API changes
• When introducing new required fields that affect plugin manifests

Quick Start

1. Step 1: Run the skill with a version argument, e.g., breaking-changes [version]
2. Step 2: Review the file:line impact report and severity mapping
3. Step 3: Update affected plugins and add migration notes

Best Practices

• Tie the detector to CI to auto-check PRs against api-surface changes
• Maintain a mapping from change types to affected plugin files
• Prioritize breaking changes by severity and plan migrations
• Grep all relevant plugin manifests and hooks for impacted APIs
• Document fixes with migration notes and a migration guide template

Example Use Cases

• Detected a Removed API hook type in api-surface.md and mapped to pluginA/src/hooks.ts:18
• Flagged a renamed frontmatter field that breaks pluginB's manifest parsing
• Found a new required parameter in the API surface, triggering changes in pluginB
• Identified a deprecated API used by pluginC, suggesting a migration path
• Sensed a new optional API addition with no immediate impact on existing plugins

Frequently Asked Questions