30 Skills Call an API. Only 15 Document the Rate Limit.

API skills are the most operationally demanding category, and the documentation is uneven in a predictable pattern.

Of 765 skills, 30 reference an api.* endpoint in their instructions. Their average score is 8.65 — above the corpus average, but with a long tail down to 6.3.

What they document:

Auth is covered almost universally. Rate limits and configuration are coin flips.

Why the gap matters

Authentication is the first thing an author hits when they build the skill. They write down how to get the key because they had to get one themselves. Rate limits are invisible until the skill is used repeatedly, and environment variables are invisible until someone else tries to run it.

An agent that knows how to authenticate but not how to back off will work perfectly in testing and fail in production. The failure is not subtle: the API returns 429, the skill has no instruction for 429, and the agent either retries immediately or reports a generic error.

What good API skill documentation contains

The 15 skills that mention rate limits tend to share four features:

1. The limit, stated as a number. "60 requests per minute per IP" is actionable; "be mindful of rate limits" is not.
2. The response shape. What a 429 body looks like, and whether it includes a retry-after header.
3. The backoff policy. Fixed sleep, exponential, or stop and ask.
4. A credential preflight. Check the key exists before making any call, and say exactly which variable is missing.

The fourth one is the most underrated. A missing API_KEY produces a confusing error three steps into the workflow. One line at the top — "if API_KEY is unset, stop and tell the user" — converts a mystery into an instruction.

The environment-variable count is the concerning one

Only 14 of 30 skills tell the reader how the skill is configured. That means at least 16 skills assume credentials are already in the environment, with no statement of which ones or where they come from.

For a personal skill, that assumption is fine. For a published skill, it is the main reason someone else cannot run it.

A minimal contract for API skills

Before the workflow, state four things:

Requires: API_KEY (from provider dashboard)
Endpoint: https://api.example.com/v1/...
Rate limit: 60/min — back off 60s on 429
On error: stop, report status code and body, do not retry blindly

Five lines. They cover the four gaps above, and they make the difference between a skill that works on the author's machine and one that works on a stranger's.