@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/gemini-cli/api-retry-guidance/SKILL.md

@@ -0,0 +1,168 @@
+# API Retry Guidance
+
+> RETRY GUIDANCE SIGNALS CLIENTS WHEN AND HOW TO RETRY FAILED REQUESTS — CLASSIFYING ERRORS AS TRANSIENT OR PERMANENT, EMITTING Retry-After HEADERS, AND REQUIRING IDEMPOTENCY FOR SAFE RETRIES PREVENTS BOTH THUNDERING-HERD AMPLIFICATION AND UNNECESSARY REQUEST ABANDONMENT UNDER TEMPORARY LOAD.
+
+## When to Use
+
+- Designing rate-limiting responses that tell clients exactly when to retry
+- Reviewing a `503 Service Unavailable` response that lacks a `Retry-After` header
+- Choosing whether to return `429 Too Many Requests` or `503 Service Unavailable` for capacity-related refusals
+- Implementing exponential backoff with jitter in a client SDK or HTTP middleware
+- Classifying error responses in a client library as retryable vs. non-retryable
+- Building a job queue or background worker that must handle transient downstream failures
+- Documenting retry behavior expectations in an API style guide or SLA
+- Implementing circuit-breaker logic that needs authoritative signals from the server to open and reset
+
+## Instructions
+
+### Key Concepts
+
+1. **Transient vs. permanent errors** — A transient error is a temporary condition that may resolve without client-side changes: network timeout, service overload, brief database unavailability. A permanent error will not resolve on retry without action: invalid credentials, missing resource, malformed request. Retrying a permanent error wastes resources and delays diagnosis. Classifying errors correctly in the response allows clients to decide immediately whether to retry. As a rule: `4xx` errors (except `429`) are permanent — they require the client to change the request. `5xx` errors (except `501`) are potentially transient — the server, not the request, is the problem.
+
+2. **`Retry-After` header** — The HTTP standard header that tells clients when they may safely retry a request. It accepts two formats:
+   - **Integer (seconds):** `Retry-After: 60` — retry after 60 seconds from now.
+   - **HTTP-date:** `Retry-After: Fri, 11 Apr 2026 09:00:00 GMT` — retry after this absolute timestamp.
+     `Retry-After` is mandatory for `429 Too Many Requests` and strongly recommended for `503 Service Unavailable`. Servers that omit it on `429` responses leave clients to implement their own backoff, producing unpredictable retry storms.
+
+3. **Exponential backoff** — A retry strategy where the wait time doubles after each failed attempt: 1s, 2s, 4s, 8s, 16s, up to a configured maximum. Exponential backoff reduces the probability that all retrying clients hit the server at the same moment. The base interval and multiplier should be configurable. Backoff should respect the `Retry-After` header as a floor — never retry before the server-specified delay, regardless of the computed backoff value.
+
+4. **Jitter** — Randomization added to the backoff interval to desynchronize retry storms. Without jitter, all clients that received the same `429` at the same moment compute the same retry interval and submit simultaneously. With full jitter (`sleep(random_between(0, computed_backoff))`), retries are spread across the backoff window, dramatically reducing peak retry load. AWS's builders library recommends "decorrelated jitter" as the most effective pattern for high-concurrency workloads.
+
+5. **`429 Too Many Requests` vs `503 Service Unavailable`** — These are commonly confused:
+   - `429` — The server is healthy, but this client has exceeded its rate limit. The server can still serve other clients. The issue is client-specific. Retry after `Retry-After` elapses; the same client will succeed if the rate is respected.
+   - `503` — The server is temporarily unavailable to all clients. The issue is server-wide: maintenance, overload, deployment in progress. Retry after `Retry-After` elapses; success is not guaranteed even after waiting (the outage may continue). Use `503` for circuit-breaker open states; use `429` for rate limiting.
+
+### Worked Example
+
+AWS API Gateway rate-limiting and retry patterns in production:
+
+**Rate limit exceeded (429 with Retry-After):**
+
+```http
+GET /v1/metrics?start=2026-01-01&end=2026-04-01
+Authorization: Bearer tok_...
+```
+
+```http
+HTTP/1.1 429 Too Many Requests
+Content-Type: application/problem+json
+Retry-After: 30
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 0
+X-RateLimit-Reset: 1744271400
+
+{
+  "type": "https://api.example.com/errors/rate-limit-exceeded",
+  "title": "Rate Limit Exceeded",
+  "status": 429,
+  "detail": "You have exceeded 100 requests per minute. Retry after 30 seconds.",
+  "instance": "/errors/correlation/f1a2-b3c4",
+  "limit": 100,
+  "remaining": 0,
+  "reset": 1744271400
+}
+```
+
+The client reads `Retry-After: 30` and waits at least 30 seconds. `X-RateLimit-Reset` provides the absolute timestamp for clients that prefer UTC synchronization. The body echoes the policy for logging and debugging.
+
+**Service temporarily unavailable (503 with Retry-After):**
+
+```http
+HTTP/1.1 503 Service Unavailable
+Content-Type: application/problem+json
+Retry-After: 120
+
+{
+  "type": "https://api.example.com/errors/service-unavailable",
+  "title": "Service Temporarily Unavailable",
+  "status": 503,
+  "detail": "The service is undergoing scheduled maintenance. Expected recovery in 2 minutes.",
+  "instance": "/errors/correlation/d5e6-f7a8"
+}
+```
+
+**Exponential backoff with jitter (pseudo-code):**
+
+```python
+import random, time
+
+def retry_with_backoff(fn, max_attempts=5, base_delay=1.0, max_delay=60.0):
+    for attempt in range(max_attempts):
+        response = fn()
+        if response.status_code not in (429, 503):
+            return response  # success or permanent error — stop retrying
+
+        # Respect server-specified Retry-After as a floor
+        retry_after = float(response.headers.get("Retry-After", 0))
+
+        # Compute exponential backoff with full jitter
+        computed = min(base_delay * (2 ** attempt), max_delay)
+        jittered = random.uniform(0, computed)
+
+        wait = max(retry_after, jittered)
+        time.sleep(wait)
+
+    raise MaxRetriesExceeded(f"Failed after {max_attempts} attempts")
+```
+
+The critical line is `wait = max(retry_after, jittered)` — the server's `Retry-After` is always respected as a minimum, and jitter is added on top of it to desynchronize concurrent retrying clients.
+
+### Anti-Patterns
+
+1. **Omitting `Retry-After` from `429` responses.** Without `Retry-After`, clients have no authoritative signal for when to retry. Common outcomes: aggressive retrying every few hundred milliseconds (worsening the rate-limit breach), or backing off so conservatively that legitimate requests are delayed for minutes. Fix: always include `Retry-After` on `429` responses, set to the actual reset window in seconds.
+
+2. **Retrying `4xx` errors other than `429`.** A `400`, `401`, `403`, `404`, or `422` response will not succeed on retry without a change to the request. Retrying them wastes quota, delays error propagation, and produces confusing logs. Fix: only retry on `429` (rate limit) and `5xx` (server fault) responses. All other `4xx` codes should surface as immediate errors to the caller.
+
+3. **Exponential backoff without jitter.** Synchronized backoff (all clients waiting exactly 2, 4, 8 seconds) produces retry bursts at each interval boundary. If 1000 clients all received `503` at the same moment, they will all retry at T+2s, T+4s, T+8s — each interval triggers a new overload spike. Fix: add randomized jitter to desynchronize the retry distribution across the backoff window.
+
+4. **Using `503` for per-client rate limiting.** Returning `503 Service Unavailable` when a specific client exceeds its rate limit misleads other clients (and monitoring systems) into thinking the server is globally down. It also prevents clients from distinguishing "my rate limit" from "server outage" — different actions are required. Fix: use `429` for client-specific rate limits and `503` for server-wide unavailability.
+
+## Details
+
+### Idempotency Requirement for Safe Retries
+
+Retrying a request that is not idempotent may produce duplicate side effects: a charge processed twice, a message sent twice, a record created twice. Before implementing retry logic, classify the endpoint:
+
+- **Safe and idempotent:** `GET`, `HEAD`, `OPTIONS` — retry freely.
+- **Idempotent by HTTP semantics:** `PUT`, `DELETE` — retry is safe if the server implements idempotency correctly.
+- **Not inherently idempotent:** `POST` — requires explicit idempotency keys (see `api-idempotency-keys`) to retry safely.
+
+Clients must never retry a `POST` without an idempotency key unless the server documents that the endpoint is safe to re-invoke (e.g., a pure query wrapped in POST).
+
+### Circuit Breaker Integration
+
+Server-side `Retry-After` signals can drive client-side circuit breakers. When consecutive `503` responses arrive with `Retry-After` headers, the circuit breaker should open for at least the server-specified duration. When the `Retry-After` window expires, a single probe request determines whether to close the circuit. This prevents the thundering-herd problem where all clients simultaneously probe the recovering service.
+
+### Real-World Case Study: Stripe Retry Design
+
+Stripe's client libraries implement a retry strategy that the Stripe engineering team has published: up to 2 automatic retries on `429` and `5xx` responses, with exponential backoff starting at 0.5 seconds and capped at 2 seconds, with `Retry-After` honored as a floor. Stripe found in production analysis that the combination of (a) emitting accurate `Retry-After` values, (b) client jitter, and (c) idempotency keys on all mutating requests reduced duplicate charge incidents by over 95% compared to client implementations that retried blindly on any error. The key insight: the server's `Retry-After` signal is the coordination mechanism that transforms a retry storm into a smooth recovery curve.
+
+## Source
+
+- [Timeouts, Retries, and Backoff with Jitter — AWS Builders' Library](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/)
+- [RFC 9110 — HTTP Semantics, Section 10.2.3 (Retry-After)](https://rfc-editor.org/rfc/rfc9110#section-10.2.3)
+- [Stripe — Error Handling and Retries](https://stripe.com/docs/error-handling)
+- [Google Cloud — Exponential Backoff](https://cloud.google.com/storage/docs/retry-strategy)
+- [Microsoft Azure — Transient Fault Handling](https://learn.microsoft.com/en-us/azure/architecture/best-practices/transient-faults)
+
+## Process
+
+1. Classify all error responses as transient (`429`, `5xx`) or permanent (`4xx` except `429`) and document the classification in the API reference.
+2. Add `Retry-After` headers to all `429` responses, set to the actual rate-limit reset window in seconds.
+3. Add `Retry-After` headers to `503` responses when the expected recovery time is known; omit when the outage duration is unknown.
+4. Ensure all `POST` endpoints that may be retried support idempotency keys (see `api-idempotency-keys`).
+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-rate-limit-headers, api-idempotency-keys, api-status-codes, api-error-contracts
+
+## Success Criteria
+
+- All `429` responses include a `Retry-After` header set to the rate-limit reset window in seconds.
+- `429` is used for client-specific rate limits; `503` is used for server-wide unavailability — never interchanged.
+- Client retry logic only retries on `429` and `5xx` responses; `4xx` errors (except `429`) are surfaced immediately.
+- Retry implementations include jitter to desynchronize concurrent retry storms.
+- Non-idempotent `POST` endpoints require idempotency keys before retries are safe.

package/dist/agents/skills/gemini-cli/api-retry-guidance/skill.yaml

@@ -0,0 +1,41 @@
+name: api-retry-guidance
+version: '1.0.0'
+description: Retry-After headers, exponential backoff signals, transient vs permanent error classification, 429 vs 503 semantics, and idempotency requirement for safe retries
+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
+  - api-idempotency-keys
+  - api-status-codes
+  - api-error-contracts
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - retry-guidance
+  - Retry-After
+  - exponential-backoff
+  - transient-error
+  - permanent-error
+  - '429'
+  - '503'
+  - jitter
+metadata:
+  author: community
+  upstream: aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/api-sdk-ergonomics/SKILL.md

@@ -0,0 +1,194 @@
+# API SDK Ergonomics
+
+> AN ERGONOMIC SDK REMOVES EVERY DECISION A DEVELOPER SHOULD NOT HAVE TO MAKE — METHOD NAMES THAT READ AS SENTENCES, PAGINATION THAT ITERATES WITHOUT MANUAL CURSOR MANAGEMENT, TYPED EXCEPTIONS THAT DISTINGUISH RETRIABLE ERRORS FROM PERMANENT ONES, AND RETRY LOGIC BUILT IN BY DEFAULT — SO THE DEVELOPER'S FIRST WORKING INTEGRATION TAKES MINUTES AND THE SDK STAYS INVISIBLE IN PRODUCTION.
+
+## When to Use
+
+- Designing the public client library API for a new platform or SaaS product
+- Auditing an existing SDK for usability problems: opaque error types, manual pagination, inconsistent method naming, or missing retry logic
+- Choosing between typed exceptions and error objects for representing API errors in a typed language
+- Adding auto-pagination helpers to an SDK that currently forces callers to manage cursors manually
+- Writing the SDK design guide for a developer platform team that ships clients in multiple languages
+- Reviewing a pull request that introduces a new resource type and needs idiomatic method names for CRUD operations
+- Evaluating an SDK against a competitor (e.g., Stripe vs. Braintree) for developer experience reference
+
+## Instructions
+
+### Key Concepts
+
+1. **Method naming: verb-noun in idiomatic form** — SDK methods should read as imperative sentences: `client.payments.create(...)`, `client.invoices.list(...)`, `client.customers.get(id)`, `client.subscriptions.cancel(id)`. The verb names the action (create, list, get, update, delete, cancel, archive); the noun names the resource (the namespace or class the method lives on). Avoid generic names like `send()`, `fetch()`, `call()`, or `execute()` — they say nothing about intent. In object-oriented languages, resource classes act as namespaces: `stripe.PaymentIntents.Create(params)` in Go, `stripe.payment_intents.create(params)` in Python. The naming convention must be consistent across all resources; inconsistency (some using `retrieve`, others using `get`) forces developers to consult documentation for every resource.
+
+2. **Pagination helpers: auto-cursor iteration** — An API that uses cursor-based pagination should not expose cursor management to the caller. The SDK wraps the raw paginated endpoint in an iterator or async generator that fetches the next page transparently when the caller exhausts the current page. In Python: `for invoice in client.invoices.list(customer='cus_xxx'):` fetches page 1, then page 2 when the iterator is exhausted, and so on. The caller never sees a cursor, a `has_more` flag, or a `next_page` token. Stripe's Python SDK (`.auto_paging_iter()`), GitHub's Octokit (`.paginate()`), and Twilio's Python SDK (`.stream()`) all implement this pattern. Expose the raw paginated method alongside the iterator for callers who need explicit page control.
+
+3. **Error surface: typed exceptions vs. error objects** — In strongly typed languages, API errors should be represented as a hierarchy of typed exceptions or error types, not as a generic `Error` with a string message. A base `ApiError` carries `status_code`, `error_code`, and `message`; subclasses specialize by category: `AuthenticationError` (401), `PermissionError` (403), `NotFoundError` (404), `RateLimitError` (429), `InvalidRequestError` (422), `ServiceUnavailableError` (5xx). Callers catch the specific type they can handle and let others propagate: `except stripe.RateLimitError: time.sleep(backoff); retry()`. An SDK that throws a single `ApiException` with a numeric status code forces callers to write switch statements on integers — a leaky abstraction that puts provider implementation details into every caller.
+
+4. **Retry built-ins** — Transient failures (rate limits, 503 Service Unavailable, network timeouts) should be retried automatically by the SDK with exponential backoff and jitter, not left to the caller. The default retry policy: up to 2 retries on `RateLimitError` (429) and `ServiceUnavailableError` (5xx) with 1s × 2^attempt + random jitter. Callers opt out via `max_retries=0`; power users override the policy. A request that requires explicit idempotency (POST with a side effect) should require an idempotency key from the caller before retrying — never silently retry non-idempotent requests. Document clearly which methods the SDK retries automatically and which require a caller-supplied idempotency key.
+
+5. **Discoverability** — An SDK is discoverable when a developer can find the right method without leaving their IDE. Design for discoverability: resource namespaces are the top-level entry points (`client.payments`, `client.customers`), method names match the operation names in the API reference, and parameter objects use named fields (not positional arguments) so autocomplete shows what is required. Include docstrings/JSDoc on every public method with the parameter names, types, return type, and a link to the API reference. A developer who can tab-complete their way to the first working call in under five minutes will not reach for a competitor SDK.
+
+6. **Idiomatic patterns per language** — The same SDK concept is expressed differently across languages. Pagination: Python uses a generator, Go uses an iterator struct with `Next() bool`, JavaScript uses an async iterator. Configuration: Python uses keyword arguments, Go uses a functional options pattern (`WithTimeout(10 * time.Second)`), Java uses a builder. Error handling: Python uses exceptions, Go uses `(result, error)` tuples, Rust uses `Result<T, E>`. An SDK that forces Go developers to use a Python-style exception pattern (panics) or forces Python developers to check error return values is fighting the language. Implement each language variant idiomatically; accept that the implementations diverge.
+
+### Worked Example
+
+**Stripe Python SDK — idiomatic patterns across all six concepts**
+
+```python
+import stripe
+
+# Configuration — idiomatic keyword arguments, not a config object
+stripe.api_key = "sk_example_..."
+client = stripe.StripeClient(api_key="sk_example_...", max_network_retries=2)
+
+# Method naming — verb-noun, resource namespaced
+# client.{resource}.{action}(params)
+intent = client.payment_intents.create(
+    params={
+        "amount": 1099,
+        "currency": "usd",
+        "automatic_payment_methods": {"enabled": True},
+    }
+)
+# → PaymentIntent(id='pi_3Nq...', status='requires_payment_method', amount=1099)
+
+# Typed error surface — catch the specific type you can handle
+try:
+    intent = client.payment_intents.confirm("pi_xxx", params={"payment_method": "pm_xxx"})
+except stripe.error.CardError as e:
+    # Permanent failure — user's card was declined, do not retry
+    handle_declined_card(e.user_message)
+except stripe.error.RateLimitError:
+    # Transient — SDK retried automatically, this is post-retry failure
+    enqueue_for_later()
+except stripe.error.AuthenticationError:
+    # Config error — wrong API key, alert ops immediately
+    alert_ops("invalid Stripe API key")
+# stripe.error.CardError, RateLimitError, AuthenticationError, PermissionError,
+# InvalidRequestError, APIConnectionError, APIError all inherit from stripe.error.StripeError
+
+# Auto-pagination — no cursor management in caller code
+for invoice in client.invoices.list(params={"customer": "cus_xxx"}).auto_paging_iter():
+    process_invoice(invoice)
+# SDK fetches page 1 (default limit 10), then fetches page 2 when exhausted, etc.
+# Caller never sees starting_after, has_more, or next page token
+
+# Built-in retry — SDK retries 429 and 5xx automatically (max_network_retries=2)
+# For POST with side effects, supply idempotency key so retry is safe
+intent = client.payment_intents.create(
+    params={"amount": 1099, "currency": "usd"},
+    options={"idempotency_key": f"create-intent-{order_id}"},
+)
+```
+
+**GitHub Octokit.js — auto-pagination with async iterator**
+
+```javascript
+import { Octokit } from '@octokit/rest';
+const octokit = new Octokit({ auth: 'ghp_token' });
+
+// Manual pagination — explicit page management (avoid this pattern)
+const page1 = await octokit.rest.issues.listForRepo({ owner: 'acme', repo: 'api', per_page: 100 });
+// caller must check page1.headers.link for next page cursor
+
+// Auto-pagination — SDK manages cursor transparently
+for await (const { data: issues } of octokit.paginate.iterator(octokit.rest.issues.listForRepo, {
+  owner: 'acme',
+  repo: 'api',
+  state: 'open',
+  per_page: 100,
+})) {
+  for (const issue of issues) {
+    processIssue(issue);
+  }
+}
+// Fetches all pages; caller iterates all issues without cursor logic
+```
+
+**Go functional options — idiomatic configuration**
+
+```go
+// stripe-go: functional options for per-request configuration
+params := &stripe.PaymentIntentCreateParams{
+    Amount:   stripe.Int64(1099),
+    Currency: stripe.String("usd"),
+}
+// Per-request option: idempotency key
+params.SetIdempotencyKey(fmt.Sprintf("create-intent-%s", orderID))
+// Per-request option: custom timeout
+params.Context = context.WithTimeout(ctx, 10*time.Second)
+
+intent, err := paymentintent.New(params)
+if err != nil {
+    var stripeErr *stripe.Error
+    if errors.As(err, &stripeErr) {
+        switch stripeErr.Code {
+        case stripe.ErrorCodeCardDeclined:
+            return handleDeclined(stripeErr.DeclineCode)
+        case stripe.ErrorCodeRateLimitExceeded:
+            return retryWithBackoff(...)
+        }
+    }
+    return err
+}
+```
+
+### Anti-Patterns
+
+1. **Positional parameters for resources with many fields.** `client.create_payment(1099, "usd", "pm_xxx", nil, nil, true, false)` requires counting argument positions to know what `nil` means. Named parameter objects or keyword arguments are mandatory for any method with more than two parameters; they enable tab-complete, make call sites self-documenting, and prevent positional errors when new optional fields are added.
+
+2. **Exposing raw HTTP response objects.** An SDK method that returns `{ status: 200, headers: {...}, body: { id: 'pi_xxx', ... } }` forces callers to unwrap the HTTP envelope on every call. The SDK should return the domain object (`PaymentIntent`) directly; HTTP metadata (request ID, rate limit headers) should be accessible via a sidecar method or response envelope wrapper, not as the primary return value.
+
+3. **Silent retry of non-idempotent requests.** Retrying a `POST /charges` without an idempotency key creates a duplicate charge. An SDK that silently retries all POST requests on 5xx is creating money-movement bugs in production. Retry only GET and DELETE automatically; require an explicit idempotency key for POST, PUT, and PATCH operations before including them in the automatic retry scope, or document clearly that POST retries are disabled by default.
+
+4. **One giant `client.request(method, path, params)` method.** Some SDKs expose a single generic method and document it as "flexible." This approach is an undifferentiated wrapper around HTTP — it provides no method naming, no type safety, no parameter validation, and no discoverability. Every caller must memorize path strings and HTTP verbs. Wrap specific operations in specific named methods even if the underlying implementation calls a shared HTTP layer.
+
+## Details
+
+### SDK as Product: Measuring Developer Experience
+
+SDK ergonomics is measurable. Time-to-first-call (TTFC) — the elapsed time from "I just installed the SDK" to "I have a working API response in my application" — is the primary metric. Stripe's internal target for TTFC on their Python SDK is under 10 minutes for a new developer with no prior Stripe experience. The design decisions that minimize TTFC:
+
+- Authentication is a single assignment (`stripe.api_key = "..."` or constructor parameter), not a five-step OAuth flow
+- The first operation a developer needs (`create` a resource) is the first method shown in the quickstart
+- Errors from the first call include the documentation URL for the specific error code, not just a numeric status
+
+A secondary metric is exception-to-fix time (ETFT): when a developer hits an error, how quickly can they understand and resolve it? Typed exceptions with human-readable `user_message` fields and documentation links reduce ETFT from hours to minutes.
+
+### Real-World Case Study: Stripe SDK Design Principles
+
+Stripe's engineering blog post "Designing robust and predictable APIs with idempotency" and their public SDK repositories document the principles behind the Stripe SDK experience. Key outcomes from their SDK design choices:
+
+- Auto-pagination on list methods eliminated a class of bug where developers fetched only the first page and processed incomplete data sets — Stripe's support logs showed this was among the top 5 developer errors before auto-pagination was introduced
+- Typed exceptions (`CardError`, `RateLimitError`) reduced the volume of "how do I handle a declined card" support tickets by making the answer discoverable from the exception type itself
+- Built-in retry with idempotency keys removed the need for the majority of developers to write their own retry logic, which historically was the most common source of duplicate-charge bugs
+
+The Stripe SDK design became the benchmark against which most API platform SDKs are evaluated, including Twilio, Plaid, and Braintree.
+
+## Source
+
+- [Stripe Developer Experience Blog — Payment API Design](https://stripe.com/blog/payment-api-design)
+- [Stripe Python SDK (github.com/stripe/stripe-python)](https://github.com/stripe/stripe-python)
+- [GitHub Octokit.js — Pagination](https://octokit.github.io/rest.js/v20#pagination)
+- [Stripe Go SDK — Functional Options Pattern](https://github.com/stripe/stripe-go)
+- [Joshua Bloch — API Design Matters (2006 Google TechTalk)](https://www.youtube.com/watch?v=aAb7hSCtvGw)
+
+## Process
+
+1. Define the resource namespace hierarchy (`client.payments`, `client.invoices`) and the method vocabulary (`create`, `list`, `get`, `update`, `delete`) before writing any implementation.
+2. Design the error type hierarchy from the API's error catalog: base error type, then subclasses per HTTP status category; ensure each subclass carries structured fields (`error_code`, `user_message`, `doc_url`).
+3. Implement auto-pagination iterators/generators for every list endpoint; expose the raw paginated method as a fallback but default to the iterator in quickstart examples.
+4. Add built-in retry with exponential backoff for 429 and 5xx on idempotent methods; require explicit idempotency keys before enabling retry for POST operations with side effects.
+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-deprecation-strategy, api-error-contracts, api-pagination-cursor, api-retry-guidance
+
+## Success Criteria
+
+- Every resource has a namespace (`client.{resource}`) and methods follow `{verb}{Resource}` or `client.{resource}.{verb}` naming with no generic verbs.
+- All list endpoints have an auto-pagination iterator that manages cursor state transparently; callers never write cursor-handling loops.
+- The error type hierarchy has at least one subclass per HTTP status category (4xx client, 429 rate limit, 5xx server); each subclass is separately catchable.
+- Built-in retry is enabled by default for GET and idempotent operations; POST retry requires an explicit idempotency key.
+- Every public method has a docstring with parameter names, types, return type, and a link to the API reference documentation.

package/dist/agents/skills/gemini-cli/api-sdk-ergonomics/skill.yaml

@@ -0,0 +1,43 @@
+name: api-sdk-ergonomics
+version: '1.0.0'
+description: Client library design — method naming (verb-noun), pagination helpers (auto-cursor iteration), error surface (typed exceptions vs error objects), retry built-ins, idiomatic patterns per language, discoverability
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-deprecation-strategy
+  - api-error-contracts
+  - api-pagination-cursor
+  - api-retry-guidance
+stack_signals:
+  - rest
+  - api
+  - sdk
+  - http
+  - client-library
+keywords:
+  - SDK-ergonomics
+  - client-library
+  - method-naming
+  - pagination-helpers
+  - typed-exceptions
+  - retry-built-in
+  - discoverability
+  - developer-experience
+metadata:
+  author: community
+  upstream: stripe.com/blog/payment-api-design
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/api-status-codes/SKILL.md

@@ -0,0 +1,196 @@
+# HTTP Status Codes
+
+> HTTP STATUS CODES ARE THE RESPONSE CONTRACT BETWEEN SERVER AND CLIENT — CORRECT CODE SELECTION ENABLES ERROR HANDLING, RETRY LOGIC, AND MONITORING WITHOUT PARSING RESPONSE BODIES. MISUSING STATUS CODES FORCES CLIENTS TO TREAT 200 OK AS AN AMBIGUOUS SIGNAL THAT MUST BE INSPECTED FOR HIDDEN FAILURES.
+
+## When to Use
+
+- Designing the response contract for a new API endpoint
+- Reviewing a PR that returns `200 OK` for validation errors or internal failures
+- Choosing between `404 Not Found` and `403 Forbidden` when a resource exists but access is denied
+- Deciding whether to return `200` or `204` after a successful mutation
+- Explaining why `422 Unprocessable Entity` is more appropriate than `400 Bad Request` for semantic validation failures
+- Selecting the correct code for rate limiting, service unavailability, and conflict scenarios
+- Building error monitoring dashboards that distinguish client errors (4xx) from server errors (5xx)
+- Implementing retry logic that behaves correctly for 429, 503, and 500 responses
+
+## Instructions
+
+### Key Concepts
+
+1. **1xx Informational** — Provisional responses sent before the final response. Rarely used in REST APIs. `100 Continue` is sent by servers to indicate that the initial part of a request was received and the client should proceed. `101 Switching Protocols` is used for WebSocket upgrades.
+
+2. **2xx Success** — The request was received, understood, and accepted. The three most important 2xx codes:
+   - `200 OK` — General success with a response body. Use for GET, PATCH, and PUT when returning the updated resource.
+   - `201 Created` — A new resource was created. Must include a `Location` header with the URL of the new resource. Use for POST and PUT-to-create.
+   - `204 No Content` — Success with no response body. Use for DELETE and PUT/PATCH when returning the resource is not needed.
+
+3. **3xx Redirection** — Further action is needed to complete the request. `301 Moved Permanently` redirects clients and updates bookmarks. `302 Found` (temporary redirect) does not update bookmarks. `304 Not Modified` is the conditional GET response — see `api-conditional-requests`. APIs should avoid redirects in normal operation flows; they complicate client retry logic.
+
+4. **4xx Client Error** — The request contained an error the client must fix before retrying. These are non-retryable without change. Key codes:
+   - `400 Bad Request` — Malformed syntax, invalid parameters, missing required fields.
+   - `401 Unauthorized` — No valid authentication credentials provided. The client should re-authenticate.
+   - `403 Forbidden` — Authentication succeeded but the caller lacks permission. Do not leak resource existence.
+   - `404 Not Found` — Resource does not exist at this URL, or the server is hiding its existence (use `403` if you want to reveal it exists).
+   - `409 Conflict` — Request conflicts with current resource state (e.g., duplicate creation, stale optimistic lock).
+   - `422 Unprocessable Entity` — Request is syntactically valid but semantically invalid (e.g., end date before start date).
+   - `429 Too Many Requests` — Rate limit exceeded. Must include `Retry-After` header.
+
+5. **5xx Server Error** — The server failed to fulfill a valid request. These are potentially retryable. Key codes:
+   - `500 Internal Server Error` — Unhandled exception or unexpected server failure. Do not expose stack traces.
+   - `502 Bad Gateway` — An upstream service returned an invalid response.
+   - `503 Service Unavailable` — The server is temporarily unable to handle requests. Should include `Retry-After`.
+   - `504 Gateway Timeout` — An upstream service did not respond in time.
+
+### Worked Example
+
+A GitHub REST API interaction demonstrating status code precision across a repository lifecycle:
+
+**Create a repository (POST → 201 Created):**
+
+```http
+POST /user/repos
+Authorization: Bearer ghp_...
+Content-Type: application/json
+
+{ "name": "my-project", "private": true }
+```
+
+```http
+HTTP/1.1 201 Created
+Location: https://api.github.com/repos/alice/my-project
+Content-Type: application/json
+
+{ "id": 123456, "name": "my-project", "full_name": "alice/my-project", ... }
+```
+
+**Create duplicate repository (422 Unprocessable Entity — GitHub's choice):**
+
+```http
+POST /user/repos
+Content-Type: application/json
+
+{ "name": "my-project", "private": true }
+```
+
+```http
+HTTP/1.1 422 Unprocessable Entity
+Content-Type: application/json
+
+{
+  "message": "Repository creation failed.",
+  "errors": [{ "resource": "Repository", "code": "custom", "field": "name",
+               "message": "name already exists on this account" }]
+}
+```
+
+Note: GitHub returns `422` rather than `409` for duplicate names — a documented choice that treats name uniqueness as a semantic constraint rather than a state conflict.
+
+**Fetch without credentials (401 Unauthorized):**
+
+```http
+GET /repos/alice/my-project
+```
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer realm="GitHub"
+Content-Type: application/json
+
+{ "message": "Requires authentication" }
+```
+
+**Fetch a private repo with wrong credentials (403 Forbidden):**
+
+```http
+GET /repos/alice/private-project
+Authorization: Bearer ghp_wrong_token
+```
+
+```http
+HTTP/1.1 404 Not Found
+```
+
+GitHub returns `404` (not `403`) to avoid leaking that the private repository exists — a security pattern called "security through obscurity on existence."
+
+**Rate limit exceeded (429 Too Many Requests):**
+
+```http
+HTTP/1.1 429 Too Many Requests
+Retry-After: 60
+X-RateLimit-Limit: 5000
+X-RateLimit-Remaining: 0
+X-RateLimit-Reset: 1714780800
+Content-Type: application/json
+
+{ "message": "API rate limit exceeded for ghp_..." }
+```
+
+### Anti-Patterns
+
+1. **Returning 200 OK for errors.** `{ "success": false, "error": "User not found" }` in a `200 OK` body breaks monitoring, alerting, and client error handling. 5xx/4xx rates in logs become meaningless. Clients must parse every body to detect failure. Fix: use the appropriate 4xx or 5xx code with an error body conforming to RFC 9457 (Problem Details) or `api-problem-details-rfc`.
+
+2. **Using 404 when 403 is correct.** If a resource exists and the caller lacks permission, returning `404` (to hide existence) is a security decision that should be explicit and documented — not a default. It prevents clients from distinguishing "wrong URL" from "wrong permissions." Use `403` when the existence of the resource is not sensitive. Use `404` only when existence itself must be concealed.
+
+3. **Using 400 for semantic validation errors.** `400 Bad Request` signals a malformed request (unparseable JSON, missing Content-Type, invalid URL parameter). Semantic failures — start date after end date, referenced resource does not exist, business rule violation — belong in `422 Unprocessable Entity`. This distinction helps clients route errors to the right handler: syntax errors (fix the request format) vs. semantic errors (fix the payload values).
+
+4. **Returning 500 for client-caused failures.** An API that throws a 500 when the request body contains unexpected values is a server bug, but returning 500 to the client incorrectly signals that the server is at fault. Validate inputs early, return 400/422 for client errors, and reserve 5xx for genuine server-side failures.
+
+## Details
+
+### The 401 vs 403 Distinction
+
+This distinction is frequently confused:
+
+- `401 Unauthorized` means the request lacks valid authentication. The `WWW-Authenticate` header tells the client how to authenticate. The fix: provide credentials.
+- `403 Forbidden` means authentication succeeded but authorization failed. The client is identified but not permitted. The fix: acquire the required permission or role.
+
+The naming is historical — "Unauthorized" was named before authentication and authorization were cleanly separated in practice.
+
+### 409 vs 422
+
+- `409 Conflict` — The request is valid but conflicts with the current state of the target resource. Use for optimistic concurrency failures (stale ETag), duplicate unique-key violations where idempotency is expected, or state machine violations (e.g., closing an already-closed order).
+- `422 Unprocessable Entity` — The request is syntactically and structurally valid but fails semantic validation. Use for business rule violations, cross-field validation failures, and references to non-existent related resources.
+
+### Real-World Case Study: Stripe Error Taxonomy
+
+Stripe's API maps all errors to HTTP status codes with machine-readable error codes in the body:
+
+- `400` for request parameter errors
+- `401` for invalid API keys
+- `402` for payment failures (a creative use of the rarely-used "Payment Required" code)
+- `403` for permission errors
+- `404` for non-existent resources
+- `409` for idempotency key reuse with different parameters
+- `429` for rate limits
+- `500/502/503` for Stripe infrastructure failures
+
+This precise taxonomy allows Stripe SDK clients to switch on `error.type` for business logic while using the HTTP status code for transport-level decisions (retry vs. no-retry). APIs that follow this pattern report 30-40% fewer support tickets related to error handling ambiguity.
+
+## Source
+
+- [MDN — HTTP Response Status Codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
+- [RFC 9110 — HTTP Semantics, Section 15](https://www.rfc-editor.org/rfc/rfc9110#section-15)
+- [RFC 9457 — Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457)
+- [RFC 6585 — Additional HTTP Status Codes (429)](https://www.rfc-editor.org/rfc/rfc6585)
+
+## Process
+
+1. Identify the outcome category: success (2xx), client error (4xx), or server error (5xx).
+2. For 2xx: choose `201 Created` + `Location` for resource creation, `204 No Content` for mutations with no return body, `200 OK` otherwise.
+3. For 4xx: distinguish authentication failure (401), authorization failure (403), not found (404), state conflict (409), semantic validation failure (422), and rate limiting (429). For 429 and 503, always include `Retry-After`.
+4. For 5xx: return `500` for unhandled server failures, `503` for intentional degraded-mode responses. Never expose stack traces or internal paths in 5xx bodies.
+5. Run `harness validate` to confirm skill files are well-formed.
+
+## 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-http-methods, api-error-contracts, api-problem-details-rfc, api-rest-maturity-model
+
+## Success Criteria
+
+- No endpoint returns `200 OK` for error conditions — all errors use appropriate 4xx or 5xx codes.
+- POST creation endpoints return `201 Created` with a `Location` header.
+- `401` and `403` are used for authentication vs. authorization failure respectively, with documented rationale for any security-through-obscurity `404` substitutions.
+- `429` responses include a `Retry-After` header; `503` responses include `Retry-After` when a recovery time is known.
+- `400` is reserved for malformed requests; semantic validation failures use `422 Unprocessable Entity`.