PlugWiki

api-idempotency-retry Skill (samber): Safe Retries for Your API

Makes Claude design idempotency keys and retry rules for a public API, so a dropped connection never causes a double charge.

Installs
9.6K
on skills.sh
Stars
9
on GitHub
Files
4
besides SKILL.md
Updated
Nov 2026
last repo commit

api-idempotency-retry makes Claude design both halves of safe retries: server-side idempotency keys and the client retry behavior that uses them. It covers key scoping per caller, how long keys are stored, claiming a key atomically, what to return for a repeat request, and backoff with jitter.

It starts when you mention an Idempotency-Key header, duplicate or double-submitted requests, safe POST retries, backoff or jitter. Claude asks 7 opening questions first, then works through 7 steps. The skill is written advice with no scripts, and it says no ratified standard exists for the Idempotency-Key header, so your own semantics must be designed and documented.

Good for

  • Platform and API engineers fixing duplicate charges or double-created records
  • SDK authors choosing retry and backoff defaults
  • Teams writing the retry section of public API docs

Install api-idempotency-retry

Claude Code

  1. 1

    Copy this prompt.

    Install the api-idempotency-retry skill in Claude Code. Run this command:

/plugin marketplace add samber/developer-platform-skills
/plugin install developer-platform-skills@developer-platform-skills

Then check that it loaded and tell me how to use it.
  2. 2

    Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both, or you get every skill twice. The README asks you to install the whole set, not just api-idempotency-retry, because the skills reference each other and a lone skill leaves those hand-offs with nowhere to go. The plugin adds all 61 skills in the repo (counted from the repo tree). Its manifests list no hooks, agents or MCP servers.

From the project README. Source.

What's in the skill

When it loads

Design idempotency-key support and client retry guidance for a public API so integrators retry safely - key derivation and per-caller scoping, storage TTL and replay windows, atomic claim mechanisms (DB unique constraint, SERIALIZABLE row lock, conditional writes), payload-mismatch rejection, in-flight duplicate handling, exponential backoff with jitter, retry budgets, timeout propagation, and SDK retry defaults. Use whenever the user mentions an Idempotency-Key header, duplicate or double-submitted requests, safe POST retries, backoff, or jitter - even if they never say "idempotency". Do NOT use for what the error response signals (samber/developer-platform-skills@api-error-design) or webhook delivery retries (samber/developer-platform-skills@webhook-platform-design).

Sections in SKILL.md

  1. Clarifying questions
  2. Who controls the retry loop
  3. Workflow
  4. 1. Identify retry-unsafe endpoints
  5. 2. Design the key contract
  6. 3. Set storage and TTL
  7. 4. Claim the key atomically
  8. 5. Design the response semantics
  9. 6. Write client retry guidance and SDK defaults
  10. 7. Document the contract for integrators
  11. Failure modes
  12. Measurement
  13. Invocation examples
  14. References

Key facts

Author
Samuel Berthe
License
MIT
Version
1.0.1
Installs on skills.sh
9,604 (Nov 2, 2026)
GitHub stars
9 (Nov 2, 2026)
skills.sh audits
Gen Agent Trust Hub pass; Socket pass; Snyk pass (Nov 2, 2026)
Last repo commit
Nov 1, 2026
What installs
5 files including SKILL.md: evals/evals.json and 3 reference files. It bundles no scripts.
Needs
The other skills in the repo; the README says to install the whole set
Works in
Claude Code, Claude.ai, Codex, Cursor, Gemini CLI, and other agents through the skills CLI

What it includes

  • Asks 7 questions in one batch before designing anything.

    Try: “Add Idempotency-Key support to our POST /payments and POST /orders endpoints - we're seeing duplicate charges when mobile clients retry on timeout.”

    Opening questions

  • Lists state-changing endpoints that must take a key or be marked unsafe to retry.

    Identify retry-unsafe endpoints

  • Has the client mint the key, scoped per account, and recommends how to derive it.

    Design the key contract

  • Separates a replay window (about 24h) from a longer reaper threshold (about 72h).

    Set storage and TTL

  • Ranks three atomic claim methods so concurrent retries cannot both run.

    Claim the key atomically

  • Treats a key as absent, in-flight or complete, with a defined reply for each.

    Design the response semantics

  • Sets which errors to retry, backoff with jitter and defaults for shipped SDKs.

    Write client retry guidance and SDK defaults

  • Writes key rules, the replay window and expiry behavior into your docs.

    Document the contract for integrators

  • Fires identical concurrent requests, then crashes the server mid-request and retries.

    Run the two pass/fail tests

  • Advises saving decisions to developer-platform-context.md when memory is a file.

    Write · Remember decisions (optional)

From the official docs

Permissions

Low risk

This skill is written advice that bundles no scripts. The one thing it may write is a decisions file, so check what Claude saves.

What it can do

  • Read your data
  • Create and change things
  • Delete things
  • Read-only mode

Watch out for

  • It may save decisions to a file

    SKILL.md advises using developer-platform-context.md when memory lives in a file, and calls it an advisory reference. Check or delete that file if you do not want decisions kept. github.com

  • The plugin route adds all 61 skills

    The README asks you to install every skill in the repo, and the repo has 61. The plugin manifests list no hooks, agents or MCP servers, and the repo tree holds none. github.com

  • Folder holds Markdown and one JSON file

    This skill's folder has 5 files: SKILL.md, evals/evals.json and 3 reference files. It has no .py, .sh or .js file. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details
Turning on read-onlyNo read-only setting is documented. Decline the memory-file suggestion if you want no files written.
Scopes

  • Asks you opening questions and works from your answers and anything you share, such as specs or docs

  • May save settled decisions to a file named developer-platform-context.md if your memory lives in a file

Questions

How do I install api-idempotency-retry?

Use the install box above. The README asks you to install all 61 skills in the repo, not just this one, because the skills point to each other. In Claude Code that is the plugin route, and elsewhere the skills CLI or the client's own route installs the set.

Does api-idempotency-retry work in Claude.ai, Codex or Cursor?

The README documents installs for Claude.ai, Claude Code, Codex, Cursor and Gemini CLI. It also lists the skills CLI, which it calls universal for Agent Skills-compatible tools. The Claude.ai route adds the whole repo as a plugin marketplace.

Does it need an API key or any setup?

SKILL.md sets no environment variable and the folder bundles no scripts. It does ask for details of your own API or product in its opening questions.

Is api-idempotency-retry safe to use?

The folder holds Markdown and one JSON file, and no scripts. SKILL.md does suggest saving settled decisions to developer-platform-context.md when your memory lives in a file, so check what Claude writes. Our advice: treat the design it produces as a draft for your team to review before you publish it.

api-idempotency-retry vs api-error-design?

Use this skill for idempotency keys and how clients retry. SKILL.md sends what the error response signals to api-error-design, and webhook delivery retries to webhook-platform-design. api-error-design in turn leaves client backoff and keys to this skill.

Is there an official standard for the Idempotency-Key header?

SKILL.md says no. The IETF draft expired in April 2026 without being ratified, so each provider decides its own rules for expiry, mismatched payloads and concurrent duplicates. The skill has you design and document those rules instead of assuming them.

Information

updated Nov 2, 2026

Repository
samber/developer-platform-skills
Folder
skills/api-idempotency-retry

samber/developer-platform-skillsskills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6
  1. README · github.com
  2. api-idempotency-retry SKILL.md · github.com
  3. api-idempotency-retry folder · github.com
  4. api-error-design SKILL.md · github.com
  5. marketplace.json · github.com
  6. plugin.json · github.com

Updated Nov 2, 2026.