agentleFS
Sign inStart free
magia187magia187/premium-agent-skills/skills/api-compat/SKILL.md

api-compat

Skill0 starsChanged 2 months agoMITView on GitHub

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.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Do not delete or rename public endpoints/fields without confirmation and a migration note.

    line 27
  2. Distinctive:

    Do not force-push release tags or rewrite published changelog history without confirmation.

    line 28
  3. Distinctive:

    Prefer additive changes (new fields optional.

    line 33
  4. Distinctive:

    If a break is required, design deprecation → dual-run → remove, or a versioned path.

    line 34
  5. Distinctive:

    Document the change and migration steps in changelog/PR.

    line 35

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

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

  1. 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.

Steps

  1. 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).

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.

Check your setup, free