How to use the API Rate Limit Handler agent skill

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent can load when a task matches them. This skill covers the case where the code the agent writes calls external APIs such as GitHub, Stripe or OpenAI, which enforce rate limits.

With the skill loaded, the agent classifies each failed response as retryable or terminal, reads Retry-After and provider reset headers before computing its own delay, and waits with capped exponential backoff plus jitter when no hint exists. It also stops within a total time budget and avoids retrying operations that could cause duplicate side effects. Optionally it adds a token bucket to throttle outgoing requests.

• Retries 408, 429, 500, 502, 503 and 504; does not retry 400, 401, 403 or 404.
• Treats Retry-After and provider reset headers as minimum waits, never shortening them.
• Refuses to schedule a retry that would exceed the total time budget.
• Does not retry POST or other side-effect operations unless the provider documents an idempotency mechanism and the same key is reused.

How do you install the API Rate Limit Handler skill?

Download the ZIP from the skill's page in this directory, then choose one of two routes. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder so it applies only there.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project: unzip into .claude/skills/ inside your repository
• Claude apps: Settings → Capabilities → Skills, then upload

Requirements for the code examples

The TypeScript examples need Node.js or another runtime that provides fetch. The Python example needs Python with the httpx package. The skill does not run scripts and does not itself make network calls; it supplies instructions and code patterns that the agent writes into your project.

• TypeScript: Node.js or a runtime with fetch
• Python: Python with httpx

How do you trigger the skill with natural requests?

You do not need a special command. Ask for the behaviour in ordinary words when you are writing code that calls an API. The skill's description matches requests such as handling rate limits, adding retry logic, a backoff strategy, or not getting throttled. You can also name the API and the problem, for example that a GitHub integration is returning 429 errors under load.

• "Handle rate limits when calling the GitHub API from this script."
• "Add retry logic with backoff to our Stripe client, but don't retry charges."
• "Our service gets 503s under load from the provider. Add retries that respect Retry-After."
• "Don't get throttled: limit our OpenAI calls to 60 requests per minute."

What does the generated code look like?

The skill's core pattern is a fetchWithRetry function. It takes a URL, request options, a maximum retry count and a total elapsed-time budget. Retries are skipped for non-idempotent methods unless the caller sets retryNonIdempotent explicitly. The delay helper prefers Retry-After, then a GitHub-style x-ratelimit-reset header, and falls back to jittered backoff capped at 60 seconds.

• Default: 3 retries within a 120-second budget.
• Upstream hints are minimum waits; if a hint would exceed the remaining budget, the function throws instead of retrying early.
• A TokenBucket class can throttle outgoing requests before they reach the provider.

What about POST requests and payments?

The skill is explicit that retrying a POST can duplicate a charge or record. Leave retryNonIdempotent false unless the provider documents an idempotency mechanism and your code reuses the same stable idempotency key for every attempt. Non-idempotent operations such as payments or order creation without such a key are a case the skill says not to retry.

Safety notes and tips

The skill provides general guidance. It does not replace a provider's documented retry policy, so check each provider's docs before relying on specific header formats. Provider reset headers do not share one unit: some return durations while GitHub returns Unix epoch seconds, so parse an extra header only after confirming it in that provider's documentation.

Review the generated code before shipping, especially the timeout and budget values, which you should choose for your own workload.

• Use the skill for real integrations, not one-off scripts that make a few requests.
• Confirm header formats in each provider's current documentation.
• Keep retries bounded so failures surface instead of piling up.