agent-rate-limiter_skill

Overview

This skill prevents 429 rate-limit errors by applying tier-based throttling and exponential backoff. It runs as a single Python script with a JSON state file, no external dependencies or API keys. The agent downshifts work automatically based on a rolling-window usage estimate to preserve context and avoid wasted tokens.

How this skill works

Before doing work, the agent runs a gate check that returns a tier (ok, cautious, throttled, critical, paused) and an exit code indicating allowed activity. After work, the agent records usage (optional token estimate) which updates a rolling-window counter against a configurable estimated limit. On a real 429, the skill auto-pauses with exponential backoff and sets a resume time; it also supports manual pause/resume and persistent state in a single JSON file.

When to use it

• Prior to any expensive API call or spawning sub-agents to decide whether to proceed
• In cron jobs and heartbeat checks to avoid non-essential work during high usage
• After significant operations to record usage and keep the rolling estimate accurate
• When integrating agents that can spawn background checks, sub-agents, or parallel requests
• As an automated safety net if your provider doesn’t expose real-time usage APIs

Best practices

• Gate before work and record after work: gate -> work -> record
• Start with conservative provider presets and tune RATE_LIMIT_ESTIMATE from real data
• Give each agent instance its own RATE_LIMIT_STATE file to avoid cross-instance interference
• Treat exit codes: 0 proceed, 1 reduce activity, 2 stop non-essential work
• On a 429, call pause and schedule resume at the provided pausedUntil timestamp

Example use cases

• Agent orchestration loops that spawn multiple sub-agents and must avoid abrupt halts
• Cron jobs that should no-op or reduce scope when the agent is near provider limits
• User-facing agents that must preserve conversational context without wasting tokens
• Automated pipelines that run periodic checks but should automatically throttle under load
• Teams running multiple instances that need per-instance rate tracking using separate state files