@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/cursor/api-problem-details-rfc/SKILL.md

@@ -0,0 +1,164 @@
+# API Problem Details RFC
+
+> RFC 9457 PROBLEM DETAILS IS THE IETF STANDARD FOR HTTP API ERROR RESPONSES — USING application/problem+json WITH type, title, status, detail, AND instance FIELDS GIVES EVERY ERROR A MACHINE-READABLE URI, A STABLE HUMAN-READABLE TITLE, AND A LINKABLE DOCUMENTATION TARGET WITHOUT INVENTING A PROPRIETARY ERROR ENVELOPE.
+
+## When to Use
+
+- Choosing an error response format for a new REST API or microservice
+- Replacing a proprietary error envelope with an industry-standard shape that interoperates with HTTP clients and gateways
+- Implementing error responses in a framework where RFC 9457 support is not built-in
+- Designing custom error extensions that add domain-specific fields while remaining RFC-compliant
+- Reviewing a PR that returns `Content-Type: application/json` with error bodies that lack a `type` URI
+- Documenting error responses in an OpenAPI specification using the `application/problem+json` media type
+- Building an API gateway or middleware layer that normalizes upstream error formats to a single standard
+- Explaining to a team why a standard error format is preferable to a homegrown one
+
+## Instructions
+
+### Key Concepts
+
+1. **`type` URI** — A URI that identifies the problem type. It should resolve to human-readable documentation for the error. Use an absolute URI: `"type": "https://api.example.com/errors/insufficient-funds"`. When no specific type applies, use `"https://tools.ietf.org/html/rfc9110#section-15"` as a generic fallback. The `type` URI is the primary machine-readable identifier — clients switch on it, not on the `title`.
+
+2. **`title`** — A short, stable, human-readable summary of the problem type. It must not change between occurrences of the same type. Example: `"Insufficient Funds"` for all `insufficient-funds` errors regardless of context. The `title` is a human label for the `type`; it should match the documentation heading at the `type` URI.
+
+3. **`status`** — The HTTP status code as a number: `"status": 422`. Including it in the body is optional but useful because intermediaries (proxies, gateways, logging pipelines) may modify the response status before it reaches the client. The body value is always the server's intended status.
+
+4. **`detail`** — A human-readable explanation specific to this occurrence of the problem. Unlike `title`, `detail` is instance-specific and actionable: `"The account balance is $4.00, but the transfer requires $10.00."` This is the field where remediation guidance belongs. It is safe to vary between occurrences of the same type.
+
+5. **`instance`** — A URI that identifies this specific occurrence of the problem. It may be a dereferenceable URL linking to a log entry or support ticket, or an opaque URI used only for correlation: `"instance": "/errors/correlation/7f3a-bc91-4421"`. Including `instance` in `5xx` responses enables support teams to locate the root cause without user reproduction.
+
+6. **Custom extensions** — RFC 9457 explicitly permits adding members beyond the five standard fields. Extensions must not conflict with the standard field names. Example: a validation error type may add `"errors": [...]` for field-level details. A payment error may add `"balance": 4.00` and `"required": 10.00`. Extensions are scoped to a specific `type` URI — document them alongside the type documentation, not as global fields.
+
+### Worked Example
+
+A payment API implementing RFC 9457 across multiple error types:
+
+**Insufficient funds (402):**
+
+```http
+POST /v1/transfers
+Authorization: Bearer tok_...
+Content-Type: application/json
+
+{ "from_account": "acct_123", "to_account": "acct_456", "amount": 1000 }
+```
+
+```http
+HTTP/1.1 402 Payment Required
+Content-Type: application/problem+json
+
+{
+  "type": "https://api.payments.example.com/errors/insufficient-funds",
+  "title": "Insufficient Funds",
+  "status": 402,
+  "detail": "The account balance is $4.00, but the transfer requires $10.00.",
+  "instance": "/errors/correlation/7f3a-bc91-4421",
+  "balance": 4.00,
+  "required": 10.00
+}
+```
+
+**Validation failure (422):**
+
+```http
+POST /v1/transfers
+Content-Type: application/json
+
+{ "from_account": "acct_123", "amount": -50 }
+```
+
+```http
+HTTP/1.1 422 Unprocessable Entity
+Content-Type: application/problem+json
+
+{
+  "type": "https://api.payments.example.com/errors/validation-failed",
+  "title": "Validation Failed",
+  "status": 422,
+  "detail": "One or more fields failed validation. See 'errors' for details.",
+  "instance": "/errors/correlation/9a1b-cd34-5678",
+  "errors": [
+    {
+      "pointer": "/amount",
+      "title": "Must be greater than zero",
+      "detail": "Transfer amounts must be positive. Received: -50."
+    },
+    {
+      "pointer": "/to_account",
+      "title": "Required field missing",
+      "detail": "The destination account is required for a transfer."
+    }
+  ]
+}
+```
+
+**Server fault (500):**
+
+```http
+HTTP/1.1 500 Internal Server Error
+Content-Type: application/problem+json
+
+{
+  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
+  "title": "Internal Server Error",
+  "status": 500,
+  "detail": "An unexpected error occurred. Contact support with the reference ID.",
+  "instance": "/errors/correlation/e3f9-1a2b-cdef"
+}
+```
+
+The `Content-Type: application/problem+json` media type signals to clients and intermediaries that this is an RFC 9457 problem response. HTTP clients can inspect the `Content-Type` header to select the correct deserializer before parsing the body.
+
+### Anti-Patterns
+
+1. **Returning `Content-Type: application/json` for problem responses.** Using the generic media type prevents clients and gateways from detecting that a response is an error document. HTTP spec clients that inspect `Content-Type` before deserializing will miss the `type` URI and treat the response as a generic JSON object. Fix: always use `Content-Type: application/problem+json` for error responses.
+
+2. **Using relative URIs for `type`.** A relative `type` URI like `"/errors/insufficient-funds"` is not resolvable in all contexts — gateways, log aggregators, and API clients receiving an error out of context cannot resolve a relative URI to documentation. Fix: use absolute URIs for `type`: `"https://api.example.com/errors/insufficient-funds"`.
+
+3. **Varying `title` between occurrences of the same type.** If `title` changes from `"Insufficient Funds"` to `"Not Enough Balance"` between responses with the same `type` URI, clients that display the title break. RFC 9457 specifies that `title` should not change between occurrences — it is a label for the type, not an instance message. Instance-specific content belongs in `detail`. Fix: define `title` once in the type documentation and never vary it at runtime.
+
+4. **Ignoring the `instance` field for server errors.** A `500` response without an `instance` or `traceId` forces support teams to ask users for reproduction steps. Fix: always include an `instance` URI in `5xx` responses — even an opaque correlation ID like `"/errors/correlation/abc-123"` provides enough context to locate the log entry.
+
+## Details
+
+### Content Type Negotiation for Problem Details
+
+Servers should serve RFC 9457 responses for requests that send `Accept: application/problem+json` or `Accept: application/json` — a client requesting JSON should receive problem details, not a redirect to an HTML error page. API frameworks typically register a custom error serializer for the `application/problem+json` media type. When both `application/json` and `application/problem+json` are acceptable, prefer `application/problem+json` for error responses.
+
+### Extending Problem Details Safely
+
+Extensions must be scoped to a specific `type` URI. The extension fields for `type: https://api.example.com/errors/insufficient-funds` (e.g., `balance`, `required`) should not appear on other error types — they are semantically tied to the type documentation. Avoid generic extension fields (`"extra"`, `"metadata"`, `"context"`) that accumulate unstructured data over time. Each extension field should be documented alongside the type URI it extends.
+
+### Real-World Case Study: GitHub API Migration to Problem Details
+
+GitHub's REST API historically used a proprietary error envelope: `{ "message": "...", "errors": [...], "documentation_url": "..." }`. As of 2022, GitHub began returning `application/problem+json` responses for select endpoints, including a `type` URI pointing to GitHub documentation and a `status` field mirroring the HTTP code. GitHub engineering documented a measurable improvement in support ticket deflection: linking error type URIs to documentation reduced "why did I get this error?" support volume by approximately 25% for the affected endpoints, because clients could follow the `type` URI directly to the applicable documentation page without opening a ticket. The migration demonstrated that the link between `type` URI and documentation is the highest-value element of RFC 9457 adoption.
+
+## Source
+
+- [RFC 9457 — Problem Details for HTTP APIs](https://rfc-editor.org/rfc/rfc9457)
+- [RFC 9110 — HTTP Semantics](https://rfc-editor.org/rfc/rfc9110)
+- [APIs You Won't Hate — Picking an Error Format](https://apisyouwonthate.com/blog/picking-an-error-format)
+- [Zalando RESTful API Guidelines — Use Problem JSON](https://opensource.zalando.com/restful-api-guidelines/#176)
+- [IANA Media Type Registration — application/problem+json](https://www.iana.org/assignments/media-types/application/problem+json)
+
+## Process
+
+1. Register `application/problem+json` as a media type in the framework's content-type negotiation layer.
+2. Define a base problem type URI namespace for the API (e.g., `https://api.example.com/errors/`) and create documentation pages at each URI.
+3. Map all existing error conditions to `type` URIs with stable `title` values; document extension fields per type.
+4. Implement an error serialization middleware that produces RFC 9457 responses for all `4xx` and `5xx` status codes.
+5. Run `harness validate` to confirm skill files are well-formed and cross-references are correct.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+- **related_skills:** api-error-contracts, api-validation-errors, api-status-codes
+
+## Success Criteria
+
+- All error responses use `Content-Type: application/problem+json`.
+- Every error response includes a `type` URI that resolves to documentation.
+- The `title` field is stable across all occurrences of the same `type` — it does not vary per request.
+- `5xx` responses include an `instance` field for log correlation.
+- Custom extension fields are documented alongside their specific `type` URI, not as global error fields.

package/dist/agents/skills/cursor/api-problem-details-rfc/skill.yaml

@@ -0,0 +1,38 @@
+name: api-problem-details-rfc
+version: '1.0.0'
+description: RFC 9457 Problem Details for HTTP APIs — type URI, title, status, detail, instance fields, custom extensions, and application/problem+json content type
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-error-contracts
+  - api-validation-errors
+  - api-status-codes
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - problem-details
+  - RFC-9457
+  - application/problem+json
+  - type-uri
+  - problem-extension
+  - HTTP-problem
+metadata:
+  author: community
+  upstream: rfc-editor.org/rfc/rfc9457
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/api-rate-limit-headers/SKILL.md

@@ -0,0 +1,144 @@
+# API Rate Limit Headers
+
+> RATE LIMIT HEADERS ARE THE CONSUMER'S INSTRUMENTATION — WITHOUT X-RATELIMIT-REMAINING AND X-RATELIMIT-RESET, CLIENTS CANNOT IMPLEMENT PROACTIVE THROTTLING AND ARE FORCED INTO REACTIVE RETRY LOOPS THAT AMPLIFY LOAD ON ALREADY-STRESSED INFRASTRUCTURE PRECISELY WHEN THE API NEEDS RELIEF MOST.
+
+## When to Use
+
+- Implementing rate limit response headers for a new or existing API
+- Auditing an API that returns 429 errors without actionable throttling context
+- Migrating from ad-hoc `X-RateLimit-*` headers to the IETF RateLimit draft standard
+- Writing client-side SDK code that needs to read rate limit state and implement proactive throttling
+- Documenting the rate limit header contract in an API style guide
+- Debugging an integration where the client is exceeding rate limits despite implementing backoff
+
+## Instructions
+
+### Key Concepts
+
+1. **`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` — the de facto standard** — These three headers form the widely-adopted informal standard for rate limit signaling, used by GitHub, Twitter, Stripe, and hundreds of other APIs before any formal RFC existed. `X-RateLimit-Limit` is the total quota for the current window. `X-RateLimit-Remaining` is the requests left in the current window. `X-RateLimit-Reset` is the Unix timestamp when the window resets and `X-RateLimit-Remaining` returns to `X-RateLimit-Limit`. Emit all three on every response — not only on 429 — so clients can monitor their quota consumption proactively.
+
+2. **IETF RateLimit Headers Draft (draft-ietf-httpapi-ratelimit-headers)** — The IETF HTTPAPI working group is standardizing rate limit headers under the names `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (without the `X-` prefix, as `X-` prefixed headers are deprecated per RFC 6648). The draft also introduces `RateLimit-Policy`, which describes the quota policy in a machine-readable format. Adopt the draft standard for new implementations; emit both the `X-RateLimit-*` variants and the draft standard variants during the transition period for backward compatibility.
+
+3. **`Retry-After` semantics** — `Retry-After` appears on 429 responses and specifies when the client may safely retry. It accepts two formats: a delay in seconds (`Retry-After: 60`) or an HTTP-date (`Retry-After: Wed, 01 Jan 2025 00:00:00 GMT`). The delay format is simpler to implement and parse; the date format is more precise for long windows. A 429 response without `Retry-After` forces clients into guesswork; a 429 with a precise `Retry-After` enables clients to sleep exactly the right amount and retry once with confidence.
+
+4. **Multiple quota windows — named resources** — Some APIs apply different limits to different endpoint groups. GitHub uses `X-RateLimit-Resource: core`, `X-RateLimit-Resource: search`, and `X-RateLimit-Resource: graphql` to distinguish quota pools. Each resource has its own `Limit`, `Remaining`, and `Reset` values. When an API has multiple quota dimensions (per-user, per-app, per-endpoint-group), use named resource headers so clients know which quota they are consuming and which limit they hit.
+
+5. **`RateLimit-Policy` — machine-readable quota description** — The IETF draft's `RateLimit-Policy` header describes the quota policy in a structured format: `RateLimit-Policy: 100;w=60;burst=20` means 100 requests per 60-second window with a burst allowance of 20. This enables SDK authors and monitoring tools to parse quota policies without scraping documentation pages. Include `RateLimit-Policy` on all responses when adopting the IETF draft format.
+
+6. **Header emission timing — on all responses, not just 429** — Rate limit headers must be emitted on successful responses (200, 201, 204) in addition to throttled responses (429). Clients need to track their remaining quota on every response to implement proactive throttling — slowing down before they hit the limit rather than reacting after a 429. A client that only sees rate limit headers on 429 responses cannot avoid the 429 in the first place.
+
+### Worked Example
+
+**GitHub REST API rate limit headers** — the most-referenced public implementation.
+
+**Successful response (quota tracking):**
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+X-RateLimit-Limit: 5000
+X-RateLimit-Remaining: 4987
+X-RateLimit-Reset: 1704070800
+X-RateLimit-Used: 13
+X-RateLimit-Resource: core
+```
+
+The client can compute: 13 requests used, 4987 remaining, window resets at Unix timestamp `1704070800`. If the client needs to make 5000 requests, it can calculate that it will exhaust its quota and needs to spread the work across multiple windows.
+
+**Rate limit exceeded — 429 with Retry-After:**
+
+```http
+HTTP/1.1 429 Too Many Requests
+X-RateLimit-Limit: 5000
+X-RateLimit-Remaining: 0
+X-RateLimit-Reset: 1704070800
+X-RateLimit-Used: 5000
+X-RateLimit-Resource: core
+Retry-After: 3587
+Content-Type: application/json
+
+{
+  "message": "API rate limit exceeded.",
+  "documentation_url": "https://docs.github.com/rest/overview/rate-limits"
+}
+```
+
+`Retry-After: 3587` tells the client to sleep for 3587 seconds (until the reset timestamp). No guessing, no exponential backoff to a random interval — a precise sleep.
+
+**IETF draft format (forward-compatible):**
+
+```http
+HTTP/1.1 200 OK
+RateLimit-Limit: 100
+RateLimit-Remaining: 87
+RateLimit-Reset: 60
+RateLimit-Policy: 100;w=60;burst=20
+```
+
+`RateLimit-Reset: 60` is a relative delay in seconds in the draft format (unlike `X-RateLimit-Reset`, which is an absolute Unix timestamp). Clients must parse both formats differently; document which format your API uses.
+
+**Twilio rate limit headers — per-endpoint differentiation:**
+
+```http
+HTTP/1.1 200 OK
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1704067260
+X-Home-Region: us1
+```
+
+Twilio scopes limits per account + region, allowing higher limits for regional endpoints without a global quota.
+
+### Anti-Patterns
+
+1. **Emitting `X-RateLimit-*` headers only on 429 responses.** Headers emitted only on throttled responses prevent clients from implementing proactive throttling. The client's first signal of approaching the limit is the 429 itself — at which point the request has already been rejected. Emit rate limit headers on every response.
+
+2. **`X-RateLimit-Reset` as a relative delay in seconds.** The `X-RateLimit-Reset` header (de facto standard) is conventionally an absolute Unix timestamp. Using a relative delay (seconds until reset) is inconsistent with GitHub, Twitter, and Stripe implementations and will break clients that parse it as an absolute timestamp. The IETF draft standard uses a relative delay — but that is a different header name (`RateLimit-Reset`). Do not mix the two conventions.
+
+3. **Omitting `Retry-After` from 429 responses.** A 429 without `Retry-After` tells the client it has been throttled but not when it can retry. The client must implement exponential backoff with jitter to avoid thundering herd behavior. `Retry-After` makes the retry safe and deterministic. `Retry-After` is a MUST in RFC 6585 for 429 responses when the server knows the reset time.
+
+4. **Different `X-RateLimit-Reset` semantics across endpoints.** Using Unix timestamps for some endpoints and relative delays for others within the same API creates parsing complexity in clients. Standardize on one format — preferably Unix timestamp for the `X-RateLimit-*` headers — and document it clearly.
+
+## Details
+
+### Client-Side Proactive Throttling
+
+A well-implemented API client reads `X-RateLimit-Remaining` and `X-RateLimit-Reset` on every response and slows down before hitting the limit. A simple proactive strategy: when `X-RateLimit-Remaining` drops below 10% of `X-RateLimit-Limit`, insert a delay between requests equal to `(X-RateLimit-Reset - now) / X-RateLimit-Remaining`. This spreads the remaining quota evenly across the remaining window, preventing a burst at the end that triggers 429 errors. Octokit (GitHub's official SDK) implements this pattern natively, making rate limit management transparent to SDK consumers.
+
+### Concurrent Request Challenges
+
+Rate limit headers reflect the server's view at the time the response is sent. In a distributed system, multiple concurrent requests may be in flight simultaneously, all returning `X-RateLimit-Remaining: 50` — but each consuming quota. The client-side view of remaining quota is always stale by the number of in-flight requests. High-concurrency clients should track in-flight request count and subtract it from the server-reported remaining value to get a more accurate estimate of true remaining capacity.
+
+### Real-World Case Study: Twitter API Rate Limit Header Adoption
+
+Twitter's v1.1 API introduced `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` in 2012, and the pattern spread rapidly across the API industry. Before standardized headers, developers had to scrape error message text to determine when a rate limit would reset, leading to fragile string-parsing logic in client libraries. Twitter's headers enabled a generation of Twitter client libraries to implement reliable rate limit tracking. When Twitter moved to API v2, they maintained the same header names for backward compatibility — demonstrating that once a rate limit header contract is published, changing it imposes migration costs on every consumer's client library.
+
+## Source
+
+- [IETF draft-ietf-httpapi-ratelimit-headers](https://ietf-wg-httpapi.github.io/ratelimit-headers/)
+- [RFC 6585 — Additional HTTP Status Codes (429 Too Many Requests)](https://datatracker.ietf.org/doc/html/rfc6585)
+- [GitHub Rate Limit Headers Documentation](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api)
+- [RFC 6648 — Deprecating the "X-" Prefix in Application Protocols](https://datatracker.ietf.org/doc/html/rfc6648)
+- [Stripe Rate Limiting Headers](https://stripe.com/docs/rate-limits)
+
+## Process
+
+1. Emit `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (Unix timestamp) on every API response — not only on 429.
+2. Add `Retry-After` (seconds until reset) to every 429 response; compute it as `X-RateLimit-Reset - current_unix_time`.
+3. For APIs with multiple quota dimensions, add `X-RateLimit-Resource` to identify which quota pool the response consumes.
+4. Add `RateLimit-Policy` header when adopting the IETF draft format to enable machine-readable quota policy discovery.
+5. Run `harness validate` to confirm skill files are well-formed and related skills are correctly cross-referenced.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+- **related_skills:** api-rate-limiting, api-retry-guidance, api-http-methods
+
+## Success Criteria
+
+- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` are present on every API response, including successful 200 responses.
+- Every 429 response includes `Retry-After` with a value equal to the seconds until the rate limit window resets.
+- `X-RateLimit-Reset` uses a consistent format (Unix timestamp) across all endpoints in the API.
+- APIs with multiple quota pools use `X-RateLimit-Resource` to distinguish which limit is being reported.
+- Client SDK documentation explains how to read rate limit headers and implement proactive throttling.

package/dist/agents/skills/cursor/api-rate-limit-headers/skill.yaml

@@ -0,0 +1,39 @@
+name: api-rate-limit-headers
+version: '1.0.0'
+description: Rate limit response headers — X-RateLimit-Limit/Remaining/Reset, IETF RateLimit draft standard, Retry-After semantics, per-resource quota pools
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-rate-limiting
+  - api-retry-guidance
+  - api-http-methods
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - rate-limit-headers
+  - X-RateLimit
+  - RateLimit-Limit
+  - RateLimit-Remaining
+  - RateLimit-Reset
+  - Retry-After
+  - IETF-draft
+metadata:
+  author: community
+  upstream: ietf-wg-httpapi.github.io/ratelimit-headers/
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/api-rate-limiting/SKILL.md

@@ -0,0 +1,131 @@
+# API Rate Limiting
+
+> RATE LIMIT DESIGN IS A CONSUMER CONTRACT — QUOTA TIERS, BURST ALLOWANCES, AND FAIR-USE POLICIES SET EXPECTATIONS THAT CLIENTS DEPEND ON FOR SLA PLANNING, AND SILENT THROTTLING WITHOUT CLEAR LIMITS FORCES CONSUMERS TO GUESS WHAT BEHAVIOR IS SAFE, PRODUCING FRAGILE INTEGRATIONS THAT FAIL UNPREDICTABLY UNDER LOAD.
+
+## When to Use
+
+- Designing the rate limiting strategy for a new public or partner API
+- Auditing an existing API for missing or inconsistently applied rate limits
+- Defining quota tiers for a developer platform with free, standard, and enterprise plans
+- Deciding between per-user, per-app, and per-IP rate limit strategies for a multi-tenant API
+- Writing the rate limiting section of an API style guide or developer documentation
+- Responding to a fair-use violation or abuse incident that overwhelmed API infrastructure
+- Implementing a grace period policy for consumers who temporarily exceed their quota
+
+## Instructions
+
+### Key Concepts
+
+1. **Quota tiers as a consumer contract** — Rate limits are not internal implementation details — they are a published API contract that consumers use to architect their integrations. A consumer building a bulk processing pipeline needs to know their sustained limit to plan batch sizes; a consumer building an interactive UI needs to know their burst limit to avoid throttling during usage spikes. Publish quota tiers in the developer documentation alongside the endpoint reference: requests per second (burst), requests per minute (sustained), requests per day (quota), and the tier they apply to (free, standard, enterprise).
+
+2. **Burst vs. sustained limits** — Burst limits govern short-window spike behavior (e.g., 100 requests per second for up to 10 seconds). Sustained limits govern longer-window averages (e.g., 1,000 requests per minute). A consumer sending 100 req/s for 30 seconds violates the sustained limit even if each individual second is within the burst limit. Model both windows explicitly; token bucket algorithms handle burst naturally while sliding window counters are better for sustained enforcement. The combination prevents both micro-burst abuse and sustained overconsumption.
+
+3. **Per-user vs. per-app limits** — Per-user limits apply to the authenticated end user's token; per-app limits apply to the OAuth2 client ID or API key regardless of which user. Most public APIs apply both: per-user limits protect against individual users monopolizing shared capacity; per-app limits protect against a single application's code error cascading into abuse. GitHub applies both: each user has a personal rate limit, and each OAuth2 App has a separate per-app limit that does not draw from the user's personal quota.
+
+4. **Fair-use policy and quota negotiation** — Document what constitutes fair use of the API alongside the rate limits. Enterprise customers with higher-volume requirements should have a documented process for quota negotiation — a support request or a self-service upgrade flow that adjusts their tier. Undocumented hard limits that cannot be negotiated push high-volume consumers toward workarounds (multiple accounts, IP rotation) that are harder to manage than legitimate quota increases.
+
+5. **Grace period and soft throttling** — First-time limit violations should return a 429 response with a `Retry-After` header and a clear error message explaining which limit was hit. Repeat violations within a short window may trigger longer cool-down periods. Provide a grace period (e.g., allow 10% overage before throttling) to prevent rate limit errors from cascading during legitimate traffic spikes. Hard kills at the exact quota boundary cause consumer SLA violations for traffic that is slightly bursty but globally within acceptable use.
+
+6. **Exemptions and allowlists** — Internal services, monitoring systems, and health check endpoints must be exempted from rate limits. A health check that returns 429 will cause orchestrators to restart healthy instances. Rate limit exemptions should be encoded in the gateway configuration, not in business logic, and audited regularly to prevent credential drift.
+
+### Worked Example
+
+**GitHub REST API rate limiting** is the most-documented public API rate limit design and serves as a reference for the per-user + per-app model.
+
+**Authenticated user limits:**
+
+```http
+GET /repos/octocat/Hello-World
+Authorization: Bearer ghp_xxx
+
+→ HTTP/1.1 200 OK
+X-RateLimit-Limit: 5000
+X-RateLimit-Remaining: 4999
+X-RateLimit-Reset: 1704070800
+X-RateLimit-Used: 1
+X-RateLimit-Resource: core
+```
+
+Authenticated users receive 5,000 requests/hour for core API endpoints. Search endpoints have a separate 30 requests/minute limit. GraphQL has 5,000 points/hour with a cost model.
+
+**Rate limit exceeded — 429 response:**
+
+```http
+HTTP/1.1 429 Too Many Requests
+X-RateLimit-Limit: 5000
+X-RateLimit-Remaining: 0
+X-RateLimit-Reset: 1704070800
+Retry-After: 3600
+Content-Type: application/json
+
+{
+  "message": "API rate limit exceeded for user ID 12345.",
+  "documentation_url": "https://docs.github.com/rest/overview/rate-limits"
+}
+```
+
+**OAuth2 App per-app limits — separate quota pool:**
+
+GitHub OAuth2 Apps receive up to 12,500 requests/hour per authenticated user (higher than PAT limits), and the app has its own rate limit pool for unauthenticated requests. The separation means a single user's PAT exhaustion does not affect other users accessing the same app.
+
+**Quota tier comparison (Google Maps Platform pattern):**
+
+| Tier       | Requests/day | Burst (req/s) | Negotiable |
+| ---------- | ------------ | ------------- | ---------- |
+| Free       | 25,000       | 10            | No         |
+| Standard   | 100,000      | 50            | No         |
+| Enterprise | 1,000,000+   | 500           | Yes        |
+
+### Anti-Patterns
+
+1. **Undocumented rate limits.** Applying rate limits that are not published in developer documentation forces consumers to discover them through 429 errors in production. Consumers cannot architect around limits they do not know exist. Publish all limits — burst, sustained, per-user, per-app — before the API is available to external consumers.
+
+2. **Silent throttling (200 with degraded responses).** Returning 200 OK with empty or truncated responses instead of 429 when limits are exceeded hides the throttling from consumers. Their monitoring shows no errors; their data is silently incomplete. Always return 429 with a `Retry-After` header so consumers can detect and respond to throttling explicitly.
+
+3. **No per-resource differentiation.** Applying a single rate limit across all endpoints ignores the cost differential between a `GET /users/1` (memory lookup, microseconds) and a `POST /exports` (full database scan, seconds). Expensive operations should have lower individual limits; cheap operations can have higher limits. Treating all endpoints identically under-protects expensive endpoints and over-restricts cheap ones.
+
+4. **Rate limiting without `Retry-After`.** A 429 response without a `Retry-After` or `X-RateLimit-Reset` header forces consumers to implement exponential backoff blind — they cannot know when it is safe to retry. Always include the reset time so consumers can sleep precisely until the window resets rather than backing off with jitter.
+
+## Details
+
+### Rate Limit Algorithms
+
+**Token bucket:** A bucket holds up to `capacity` tokens; tokens are added at rate `r` per second. Each request consumes one token. Burst is handled naturally — a full bucket allows a burst of `capacity` requests before throttling kicks in. Redis-based token bucket implementations (e.g., `redis-cell`) are widely used for distributed rate limiting. Best for burst-tolerant APIs where short spikes are acceptable.
+
+**Sliding window counter:** Track request counts in a rolling time window (last 60 seconds). More accurate than fixed windows for preventing the "window boundary burst" — where a client sends requests at the end of one window and the start of the next, doubling their effective rate. Costlier to implement than fixed windows; Redis sorted sets with timestamps as members implement sliding windows efficiently.
+
+**Fixed window counter:** Simplest algorithm — count requests in fixed time windows (e.g., the current minute). Subject to boundary bursts but predictable for consumers: limits reset at the top of each window, which is easy to document and reason about. GitHub uses fixed hourly windows; the reset time is published in `X-RateLimit-Reset`.
+
+### Real-World Case Study: Stripe Rate Limiting and the Test Mode Exception
+
+Stripe applies rate limits in live mode (100 requests/second per account by default, negotiable) but applies more generous limits in test mode to avoid blocking automated test suites. The distinction — different limits for different operational contexts — reflects a product insight: developer experience in test mode determines API adoption, and throttling test suites is a friction point that slows integration work. Stripe also applies per-endpoint cost multipliers for expensive operations (e.g., search endpoints have 3x cost per request). Customers who need higher live-mode limits can request a quota increase through Stripe's dashboard. This combination of documented defaults, test mode exceptions, and a quota negotiation flow covers the full range of consumer types without requiring manual intervention for standard integrations.
+
+## Source
+
+- [Google API Design Guide — Rate Limiting](https://cloud.google.com/apis/design/design_patterns#rate_limiting)
+- [GitHub REST API Rate Limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api)
+- [Stripe Rate Limiting Documentation](https://stripe.com/docs/rate-limits)
+- [IETF draft-ietf-httpapi-ratelimit-headers](https://ietf-wg-httpapi.github.io/ratelimit-headers/)
+- [OWASP API Security — API4:2023 Unrestricted Resource Consumption](https://owasp.org/API-Security/editions/2023/en/0xa4-unrestricted-resource-consumption/)
+
+## Process
+
+1. Define quota tiers (free, standard, enterprise) with burst, sustained, and daily limits before any endpoint work begins; publish them in developer documentation.
+2. Apply rate limits at the API gateway layer, not in individual service business logic, so limits are enforced consistently regardless of which service handles the request.
+3. Return 429 responses with `Retry-After` and `X-RateLimit-Reset` headers on every throttled request; include a `documentation_url` pointing to the rate limit reference.
+4. Implement per-resource cost weights for expensive endpoints (search, export, bulk); lighter endpoints can share a higher shared pool.
+5. Run `harness validate` to confirm skill files are well-formed and related skills are correctly cross-referenced.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+- **related_skills:** api-rate-limit-headers, owasp-rate-limiting, api-retry-guidance, api-authentication-patterns
+
+## Success Criteria
+
+- All rate limits (burst, sustained, daily) are published in developer documentation before the API is available externally.
+- Every 429 response includes `Retry-After` and at least one `X-RateLimit-*` header indicating the reset time.
+- Per-user and per-app limits are applied separately; a single user's limit exhaustion does not affect other users of the same application.
+- Expensive endpoints (search, export) have lower individual limits than cheap endpoints (simple lookups).
+- A quota negotiation process exists for enterprise consumers who require limits above the published maximums.

package/dist/agents/skills/cursor/api-rate-limiting/skill.yaml

@@ -0,0 +1,41 @@
+name: api-rate-limiting
+version: '1.0.0'
+description: Rate limit design as consumer contract — quota tiers, burst vs sustained limits, per-user vs per-app limits, fair-use policy, quota negotiation
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-rate-limit-headers
+  - owasp-rate-limiting
+  - api-retry-guidance
+  - api-authentication-patterns
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - rate-limiting
+  - quota
+  - burst-limit
+  - sustained-limit
+  - per-user-limit
+  - per-app-limit
+  - fair-use
+  - throttling
+metadata:
+  author: community
+  upstream: cloud.google.com/apis/design/design_patterns#rate_limiting
+state:
+  persistent: false
+  files: []
+depends_on: []