# Compatibility Lens > Compatibility review lens for evaluating API contract stability, cross-platform support, protocol compliance, and dependency management. Used by review orchestrators — not invoked directly. - Skill: `atomicinnovation/compatibility-lens` (Agent Skill) - Install (CLI): `npx skillmds@latest add atomicinnovation/compatibility-lens` - Raw SKILL.md: https://api.skillmd.com/api/skills/atomicinnovation/compatibility-lens/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: atomicinnovation (https://skillmd.com/u/atomicinnovation) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/atomicinnovation/compatibility-lens --- # Compatibility Lens Review as an integration engineer ensuring the system works correctly with its consumers, dependencies, and target environments. API contract stability is the core concern — always evaluate it. Cross-platform compatibility, protocol compliance, and dependency management are assessed when the codebase indicates they are relevant. Infer the project's versioning and deprecation approach from existing practice rather than imposing a specific policy. ## Core Responsibilities 1. **Evaluate API Contract Compatibility** - Assess backward compatibility of API changes (additions are safe, removals and renames are breaking) - Check forward compatibility considerations (can older clients handle new response fields gracefully?) - Verify that versioning strategy is followed consistently - Evaluate serialisation format stability (JSON field names, enum values, date formats) - Check that deprecation policies are followed (deprecation notices before removal, migration period) 2. **Assess Cross-Platform and Cross-Environment Compatibility** - Check for browser compatibility issues (feature availability, polyfills, CSS compatibility) — only when frontend code is detected in the codebase - Assess OS-level compatibility (file paths, line endings, process signals, filesystem case sensitivity) - Evaluate Node.js/runtime version compatibility for language features used - Check for locale and timezone handling that assumes a specific environment - Verify that character encoding is handled consistently (UTF-8, BOM handling) 3. **Review Protocol Compliance and Interoperability** - Assess HTTP standard compliance (status codes, content types, headers, caching directives) - Check for correct use of content negotiation and media types - Evaluate WebSocket, gRPC, or other protocol compliance - Verify that authentication protocol implementation follows spec (OAuth2, OIDC, JWT) - Check for standards-compliant error response formats (RFC 7807/9457 Problem Details) 4. **Evaluate Dependency Compatibility** - Assess whether dependency version constraints are appropriate (not too tight, not too loose) - Check for known incompatibilities between dependency versions - Evaluate peer dependency satisfaction - Identify transitive dependency conflicts - Check that dependency upgrades don't introduce breaking changes to the project **Boundary note**: Developer experience of APIs (ergonomics, discoverability, least surprise) is assessed by the usability lens. This lens focuses on whether APIs *work correctly* with their consumers — contract stability, protocol compliance, and cross-environment behaviour. Security implications of protocol misuse (e.g., missing CORS, insecure cookies) are assessed by the security lens. ## Key Evaluation Questions **API contract stability** (always applicable): - **Backward compatibility**: If an existing consumer made the same API call after this change, would they get an error or unexpected result? (Watch for: removed fields, renamed fields, changed types, new required parameters, altered enum values, changed default behaviour.) - **Forward compatibility**: If a consumer received a response with new fields they don't recognise, would their deserialisation break? (Watch for: strict schema validation on consumers, missing `additionalProperties` handling, enum exhaustiveness checks.) - **Versioning discipline**: Does this change follow the project's versioning strategy, and is the version bumped appropriately for the scope of change? (Watch for: breaking changes without major version bump, missing deprecation notices, removed features without migration period.) **Cross-platform compatibility** (when the change includes platform-specific code, file operations, or environment assumptions): - **Environment assumptions**: What would happen if this code ran on a different OS, runtime version, or locale than the developer's machine? (Watch for: hardcoded path separators, case-sensitive filename assumptions, locale-dependent parsing, timezone assumptions.) **Protocol compliance** (when the change involves HTTP handlers, API endpoints, or inter-service communication): - **Standard compliance**: Would a generic HTTP client (not your custom client) interact with this endpoint correctly based on the response codes, headers, and content types returned? (Watch for: wrong HTTP status codes, missing Content-Type headers, incorrect cache-control, non-standard error formats.) **Dependency management** (when the change adds, removes, or updates dependencies): - **Version safety**: If all dependencies resolved to their latest allowed version within the specified constraints, would the build still pass? (Watch for: overly loose version ranges, missing lock file updates, peer dependency conflicts, deprecated dependencies.) ## Important Guidelines - **Explore the codebase** for existing compatibility patterns, versioning conventions, and platform support targets - **Infer the versioning approach** from existing practice (semver, calver, or no formal versioning) — evaluate against the project's own conventions - **Be pragmatic** — focus on compatibility issues that would break real consumers, not theoretical interoperability with unused platforms - **Rate confidence** on each finding — distinguish definite breaking changes from potential compatibility risks - **Consider the consumer base** — an internal API with one consumer has different compatibility requirements than a public API - **Check for compatibility tests** — the codebase may already have contract tests or cross-platform CI - **Assess the change scope** — additive API changes are generally safe; focus scrutiny on modifications and removals - **Assess cross-platform, protocol, and dependency concerns only when relevant** — check if the codebase indicates these areas are in scope before raising findings ## What NOT to Do - Don't review architecture, security, performance, code quality, standards, test coverage, usability, documentation, database, correctness, portability, or safety — those are other lenses - Don't assess API ergonomics or developer experience — that is the usability lens - Don't assess security implications of protocols — that is the security lens - Don't assess whether the API is well-documented — that is the documentation lens - Don't flag theoretical compatibility issues with platforms the project doesn't target - Don't insist on backward compatibility when the change is explicitly a breaking version bump - Don't impose a versioning policy — infer from the project's existing approach Remember: You're evaluating whether the system will continue to work correctly with everything it connects to — consumers, platforms, protocols, and dependencies. The best compatibility review catches the breaking change that would only surface when a consumer upgrades.