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.
In this repository51 other files it gives its agents.
- antislop-codeSkill
- antislop-copywritingSkill
- antislop-humanSkill
- antislop-layoutmobileSkill
- antislopSkill
- antislop-uiSkill
- context7Skill
- handoffSkill
- shadow-accessibilitySkill
- shadow-apiSkill
- shadow-architectSkill
- shadow-authSkill
- shadow-bootstrapSkill
- shadow-browserSkill
- shadow-cacheSkill
- shadow-concurrencySkill
- shadow-dataSkill
- shadow-dbSkill
- shadow-debugSkill
- shadow-designSkill
- shadow-discoverySkill
- shadow-docSkill
- shadow-domainSkill
- shadow-eaSkill
- shadow-evalSkill
- shadow-finopsSkill
- shadow-gitSkill
- shadow-grcSkill
- shadow-handoverSkill
- shadow-integrateSkill
- shadow-maintainSkill
- shadow-mobileSkill
- shadow-modernizeSkill
- shadow-monarchSkill
- shadow-observeSkill
- shadow-opsSkill
- shadow-perfSkill
- shadow-planSkill
- shadow-pmoSkill
- shadow-presalesSkill
- shadow-privacySkill
- shadow-qualitySkill
- shadow-realtimeSkill
- shadow-refactorSkill
- shadow-releaseSkill
- shadow-resilienceSkill
- shadow-searchSkill
- shadow-secSkill
- shadow-supplychainSkill
- shadow-testSkill
- shadow-uatSkill
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
- Distinctive: line 8
Use this skill when modifying existing API contracts, upgrading framework/library dependencies, or verifying that web and mobile interfaces …
- Distinctive: line 14
When mobile apps (which users do not update immediately), partner webhooks, or external systems consume your backend API:
- Very specific: line 28
When upgrading packages (package.json, requirements.txt, composer.json, go.mod):
- Very specific: line 29
Audit Breaking Changes First: Use /context7 MCP to inspect the official migration guide / changelog between the installed major version and …
- Very specific: line 31
Lockfile & Native Binding Check: Verify compatibility with the production OS/architecture (linux/amd64 vs linux/arm64, glibc vs musl Alpine …
- Very specific: line 39
Use 100dvh (min-h-dvh) instead of 100vh so the iOS Safari address bar does not clip bottom buttons.
- Very specific: line 40
Ensure all <input>, <select>, and <textarea> elements have font-size >= 16px (1rem) on mobile so iOS Safari does not auto-zoom the page on …
- Very specific: line 43
Never pass non-standard date strings like "2026-11-10 14:30:00" into new Date(...) (returns Invalid Date in Safari/WebKit!).
≈ “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.
Files
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 Type | Classification | Safe Evolution Rule |
| Adding an optional request field or new response field | Non-Breaking (Safe) | Safe to deploy in minor release (v1.x). |
| Adding a required request field | BREAKING | Make optional with a safe server default, or introduce /api/v2/... endpoint. |
| Renaming or removing a response field | BREAKING | Keep 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) | BREAKING | Never 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 Breaking | Ensure 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):
- Audit Breaking Changes First: Use
/context7MCP to inspect the official migration guide / changelog between the installed major version and target version. - 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.
- Lockfile & Native Binding Check: Verify compatibility with the production OS/architecture (
linux/amd64vslinux/arm64,glibcvsmuslAlpine 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 of100vhso the iOS Safari address bar does not clip bottom buttons. - Ensure all
<input>,<select>, and<textarea>elements havefont-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.
- Use
- Date & Timezone Parsing:
- Never pass non-standard date strings like
"2026-11-10 14:30:00"intonew Date(...)(returnsInvalid Datein Safari/WebKit!). Always use strict ISO-8601"2026-11-10T14:30:00Z"or explicit date parsers.
- Never pass non-standard date strings like
- Windows vs Linux Path & Case-Sensitivity:
- Git on Windows is case-insensitive by default (
import './Header'works locally even if file isheader.tsx), which breaks immediately on Linux CI/Docker builds! Always verify exact filename casing.
- Git on Windows is case-insensitive by default (
Schema Evolution Compatibility Matrix & Contract Governance
- Wire & Schema Evolution Rules:
| Evolution Mode | Constraint | Safe Deployment Order |
| Backward Compatible | New consumer/reader reads old producer payloads (add optional field with safe default) | Deploy Consumer first, then Producer |
| Forward Compatible | Old consumer ignores new optional fields (tolerant reader + no additionalProperties: false breakage) | Deploy Producer first, then Consumer |
| Full Compatible | Only add/remove fields that both old and new versions default safely; never rename/retype in place | Expand-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,
nullvs 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 (
DeprecationandSunsettimestamps), document migration guides, and verify telemetry shows near-zero legacy traffic before the Contract phase removes the field or route.
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
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.

