agentleFS
RidhuanDEVRidhuanDEV/claude-skills/shadow-compat/SKILL.md

shadow-compat

Skill1 starsChanged yesterdayMITView on GitHub

Compatibility & Upgrade Assurance. Use when auditing API/webhook backward compatibility, database schema evolution safety, dependency upgrade breaking changes, or cross-browser/device support matrices.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when modifying existing API contracts, upgrading framework/library dependencies, or verifying that web and mobile interfaces …

    line 8
  2. Distinctive:

    When mobile apps (which users do not update immediately), partner webhooks, or external systems consume your backend API:

    line 14
  3. Very specific:

    When upgrading packages (package.json, requirements.txt, composer.json, go.mod):

    line 28
  4. Very specific:

    Audit Breaking Changes First: Use /context7 MCP to inspect the official migration guide / changelog between the installed major version and …

    line 29
  5. Very specific:

    Lockfile & Native Binding Check: Verify compatibility with the production OS/architecture (linux/amd64 vs linux/arm64, glibc vs musl Alpine …

    line 31
  6. Very specific:

    Use 100dvh (min-h-dvh) instead of 100vh so the iOS Safari address bar does not clip bottom buttons.

    line 39
  7. Very specific:

    Ensure all <input>, <select>, and <textarea> elements have font-size >= 16px (1rem) on mobile so iOS Safari does not auto-zoom the page on …

    line 40
  8. Very specific:

    Never pass non-standard date strings like "2026-11-10 14:30:00" into new Date(...) (returns Invalid Date in Safari/WebKit!).

    line 43

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Shadow Compat (/shadow-compat) — API, Dependency & Cross-Browser/Device Compatibility

Use this skill when modifying existing API contracts, upgrading framework/library dependencies, or verifying that web and mobile interfaces work consistently across browsers, operating systems, and client versions.


1. API & Contract Backward-Compatibility Rules

When mobile apps (which users do not update immediately), partner webhooks, or external systems consume your backend API:

Change TypeClassificationSafe Evolution Rule
Adding an optional request field or new response fieldNon-Breaking (Safe)Safe to deploy in minor release (v1.x).
Adding a required request fieldBREAKINGMake optional with a safe server default, or introduce /api/v2/... endpoint.
Renaming or removing a response fieldBREAKINGKeep returning both old and new fields during deprecation window; remove old field only after all clients upgrade.
Changing field type (e.g., number -> string or object -> array)BREAKINGNever mutate field types in-place on live endpoints.
Narrowing an enum in responses (adding a new enum value that old mobile clients don't recognize)Potentially BreakingEnsure mobile/frontend clients have a safe fallback branch for unknown enum values.

2. Dependency & Runtime Upgrade Protocol

When upgrading packages (package.json, requirements.txt, composer.json, go.mod):

  1. Audit Breaking Changes First: Use /context7 MCP to inspect the official migration guide / changelog between the installed major version and target version.
  2. Incremental Group Upgrades: Upgrade one ecosystem group at a time (e.g., ORM first -> verify tests -> framework next -> verify tests), never 40 major versions in a single blind commit.
  3. Lockfile & Native Binding Check: Verify compatibility with the production OS/architecture (linux/amd64 vs linux/arm64, glibc vs musl Alpine in Docker).

3. Cross-Browser & Mobile Device Compatibility Checklist

Watch for and eliminate common cross-platform pitfalls:

  • iOS Safari Viewport & Input Quirks:
    • Use 100dvh (min-h-dvh) instead of 100vh so the iOS Safari address bar does not clip bottom buttons.
    • Ensure all <input>, <select>, and <textarea> elements have font-size >= 16px (1rem) on mobile so iOS Safari does not auto-zoom the page on input focus!
    • Respect env(safe-area-inset-bottom) on fixed bottom navigation bars and sticky action footers.
  • Date & Timezone Parsing:
    • Never pass non-standard date strings like "2026-11-10 14:30:00" into new Date(...) (returns Invalid Date in Safari/WebKit!). Always use strict ISO-8601 "2026-11-10T14:30:00Z" or explicit date parsers.
  • Windows vs Linux Path & Case-Sensitivity:
    • Git on Windows is case-insensitive by default (import './Header' works locally even if file is header.tsx), which breaks immediately on Linux CI/Docker builds! Always verify exact filename casing.

Schema Evolution Compatibility Matrix & Contract Governance

  • Wire & Schema Evolution Rules:
Evolution ModeConstraintSafe Deployment Order
Backward CompatibleNew consumer/reader reads old producer payloads (add optional field with safe default)Deploy Consumer first, then Producer
Forward CompatibleOld consumer ignores new optional fields (tolerant reader + no additionalProperties: false breakage)Deploy Producer first, then Consumer
Full CompatibleOnly add/remove fields that both old and new versions default safely; never rename/retype in placeExpand-Contract dual-write / dual-read window (/shadow-data)
  • Semantic API Diff & Consumer-Driven Contract Tests: Beyond AST/OpenAPI syntactic diffs, audit semantic breaking changes (default value flips, keyset/sort order changes, error code remapping, null vs omitted field semantics, pagination limit caps). Enforce consumer-driven contract tests (Pact, OpenAPI schema snapshots, or golden payload replay) against every active client before merging.
  • Deprecation & Sunset Policy: Annotate deprecated endpoints/fields with RFC 8594/9745 headers (Deprecation and Sunset timestamps), document migration guides, and verify telemetry shows near-zero legacy traffic before the Contract phase removes the field or route.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.