How do I install the API Compat skill?

Run npx skillmds@latest add magia187/api-compat in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is API Compat safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with API Compat?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is API Compat free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published API Compat?

magia187 (@magia187) published this skill. Their other Agent Skills are listed on their SkillMD profile.

API Compat by magia187 — Agent Skill

Name: API Compat
Rating: 4.2 (5 reviews)
Author: magia187

File contents

API Compatibility

When to use

Modifying request/response shapes, CLI flags, SDK exports, or event payloads consumers rely on.
Deprecating a field, endpoint, or behavior.
The user asks for a "breaking change", "v2", or "migrate callers".

When not to use

Purely internal helpers with a single in-repo caller and no published contract.
Bug fixes that restore documented behavior without changing the contract.
Experimental endpoints explicitly marked unstable in docs and headers.

Assumptions

You can identify the public surface (OpenAPI, exported types, CLI help, or docs).
Semver or an explicit API versioning scheme may apply; follow the repo's convention.
Do not delete or rename public endpoints/fields without confirmation and a migration note.
Do not force-push release tags or rewrite published changelog history without confirmation.

Workflow

Inventory the current public contract and known callers (in-repo first).
Prefer additive changes (new fields optional; new endpoints; new flags).
If a break is required, design deprecation → dual-run → remove, or a versioned path.
Document the change and migration steps in changelog/PR.
Ship with tests that lock both old (while supported) and new behavior.

Steps

Classify the change — Additive, deprecating, or breaking. Default to additive.
Preserve wire compatibility — New JSON fields optional; do not reuse field names for new meanings; avoid tightening validation unexpectedly.
Deprecation path — Mark old fields/endpoints deprecated with a removal timeline; keep them working until then when feasible.
Version or migrate — For hard breaks: new path (/v2), negotiated version header, or coordinated caller PRs. State which.
Tests & examples — Update contract tests, golden files, and README/OpenAPI examples in the same change.
Announce — PR summary includes impact, migration steps, and rollback (revert commit / previous version).

Success criteria

Change type (additive / deprecating / breaking) is explicit in the PR.
Breaks have a documented migration or version strategy.
Existing supported clients keep working, or unsupported breakage is called out with confirmation.
Contract tests/docs updated in the same diff.
Destructive removals were confirmed or deferred.

Out of scope

GraphQL schema federation strategy across many services.
Marketing version numbering unrelated to API contracts.
Database schema migrations without an external API impact (handle separately).

---name: api-compatdescription: Use when changing a public or shared API (HTTP, SDK, CLI, events). Prefer additive changes; document breaks; provide versioning or migration paths before shipping incompatible updates.---# API Compatibility## When to use- Modifying request/response shapes, CLI flags, SDK exports, or event payloads consumers rely on.- Deprecating a field, endpoint, or behavior.- The user asks for a "breaking change", "v2", or "migrate callers".## When not to use- Purely internal helpers with a single in-repo caller and no published contract.- Bug fixes that restore documented behavior without changing the contract.- Experimental endpoints explicitly marked unstable in docs and headers.## Assumptions- You can identify the public surface (OpenAPI, exported types, CLI help, or docs).- Semver or an explicit API versioning scheme may apply; follow the repo's convention.- Do **not** delete or rename public endpoints/fields without confirmation and a migration note.- Do **not** force-push release tags or rewrite published changelog history without confirmation.## Workflow1. Inventory the current public contract and known callers (in-repo first).2. Prefer additive changes (new fields optional; new endpoints; new flags).3. If a break is required, design deprecation → dual-run → remove, or a versioned path.4. Document the change and migration steps in changelog/PR.5. Ship with tests that lock both old (while supported) and new behavior.## Steps1. **Classify the change** — Additive, deprecating, or breaking. Default to additive.2. **Preserve wire compatibility** — New JSON fields optional; do not reuse field names for new meanings; avoid tightening validation unexpectedly.3. **Deprecation path** — Mark old fields/endpoints deprecated with a removal timeline; keep them working until then when feasible.4. **Version or migrate** — For hard breaks: new path (`/v2`), negotiated version header, or coordinated caller PRs. State which.5. **Tests & examples** — Update contract tests, golden files, and README/OpenAPI examples in the same change.6. **Announce** — PR summary includes impact, migration steps, and rollback (revert commit / previous version).## Success criteria- [ ] Change type (additive / deprecating / breaking) is explicit in the PR.- [ ] Breaks have a documented migration or version strategy.- [ ] Existing supported clients keep working, or unsupported breakage is called out with confirmation.- [ ] Contract tests/docs updated in the same diff.- [ ] Destructive removals were confirmed or deferred.## Out of scope- GraphQL schema federation strategy across many services.- Marketing version numbering unrelated to API contracts.- Database schema migrations without an external API impact (handle separately).

Frequently asked questions

API Compat