@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/gemini-cli/api-contract-testing/SKILL.md

@@ -0,0 +1,222 @@
+# API Contract Testing
+
+> CONSUMER-DRIVEN CONTRACT TESTING INVERTS THE TRADITIONAL INTEGRATION TEST — EACH CONSUMER PUBLISHES THE EXACT SHAPE IT EXPECTS, THE PROVIDER VERIFIES AGAINST EVERY CONSUMER'S CONTRACT IN CI, AND A BREAKING CHANGE IS CAUGHT THE MOMENT IT IS INTRODUCED INTO THE PROVIDER CODEBASE RATHER THAN DISCOVERED AT DEPLOYMENT TIME WHEN ROLLING BACK COSTS HOURS.
+
+## When to Use
+
+- Adding a new API consumer (frontend, mobile, partner service) and formalizing what shape it expects from the provider
+- Running a provider code change through CI and needing proof that no existing consumer contract is broken before merging
+- Integrating spectral or vacuum schema linting into a CI pipeline for an OpenAPI spec that has no automated quality gate today
+- Evaluating `oasdiff` or `openapi-diff` for automated breaking-change detection between two versions of a spec
+- Replacing a brittle end-to-end integration test suite with faster, isolated contract tests that do not require a live environment
+- Writing the API governance checklist for a platform team that ships multiple versioned services
+- Onboarding a new team to consumer-driven contract practices before they begin building their first provider
+
+## Instructions
+
+### Key Concepts
+
+1. **Consumer-driven contracts** — A consumer-driven contract captures the exact subset of the provider API that a specific consumer uses: the request shape it sends and the minimum response fields it requires. The consumer publishes this contract as a Pact file (JSON); the provider runs the Pact file against its real implementation in CI. If the provider's response no longer satisfies the consumer's contract, the provider build fails — before any deployment. This is the inverse of provider-driven testing, where the provider defines what it thinks consumers need and consumers adapt. Consumer-driven contracts give each consumer a voice in breaking-change detection.
+
+2. **Pact fundamentals** — A Pact file is a JSON document that encodes one or more interactions: `{ "description": "a request for payment intent pi_xxx", "request": { "method": "GET", "path": "/payment_intents/pi_xxx" }, "response": { "status": 200, "body": { "id": "pi_xxx", "status": "succeeded" } } }`. The consumer writes the test using the Pact DSL (available in JavaScript, Python, Go, Java, Ruby, .NET); the DSL generates the Pact file and runs a mock provider during the consumer test. The provider test replays each interaction from the Pact file against the real provider, verifying response status, headers, and body match the consumer's expectations.
+
+3. **Pact Broker and provider verification** — In a multi-team setup, Pact files are published to a Pact Broker (hosted at pactflow.io or self-hosted). The provider CI pipeline fetches all Pact files for the service, runs provider verification against each, and publishes results back to the Broker. The Broker's `can-i-deploy` command answers: "Is it safe to deploy provider version X to environment Y given the current consumer contracts?" This replaces manual coordination between teams before deployments.
+
+4. **Schema linting with spectral and vacuum** — Spectral (Stoplight) and vacuum (quobix) are OpenAPI spec linters that enforce ruleset-based quality gates. Both support built-in rulesets (OpenAPI best practices) and custom rulesets (team conventions). A spectral rule that enforces `operationId` presence looks like: `{ "operation-operationId": { "given": "$.paths.*[get,post,put,patch,delete]", "then": { "field": "operationId", "function": "truthy" } } }`. Run linting in CI as a required check; a spec that adds a new operation without an `operationId` fails the build.
+
+5. **Breaking change detection with oasdiff** — `oasdiff` compares two OpenAPI specs and classifies changes as breaking or non-breaking. Breaking changes include: removing a required request field, removing a response field a consumer may rely on, changing a field type, removing an operation. Non-breaking changes include: adding an optional request field, adding a response field, adding a new operation. Run `oasdiff breaking old-spec.yaml new-spec.yaml` in CI on every pull request that touches the spec; block merges on any breaking change unless a version bump accompanies it.
+
+6. **Contract as living documentation** — A Pact Broker renders the consumer/provider relationship graph: which consumers depend on which providers, which contract versions are verified, which environments each version is deployed to. This replaces a manually maintained dependency map that goes stale. The Broker's network diagram is generated from actual test results, not documentation — if a consumer stops using an endpoint, its contract disappears from the graph automatically.
+
+### Worked Example
+
+**Pact consumer test — JavaScript (checkout-service consuming payments-api)**
+
+```javascript
+// checkout-service/src/payments.pact.test.js
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+
+const { like, regex } = MatchersV3;
+
+const provider = new PactV3({
+  consumer: 'checkout-service',
+  provider: 'payments-api',
+  dir: './pacts',
+});
+
+describe('PaymentsAPI', () => {
+  it('returns a succeeded PaymentIntent', async () => {
+    await provider
+      .given('payment intent pi_succeeded exists')
+      .uponReceiving('a request for a succeeded payment intent')
+      .withRequest({
+        method: 'GET',
+        path: '/payment_intents/pi_succeeded',
+        headers: { Authorization: like('Bearer token') },
+      })
+      .willRespondWith({
+        status: 200,
+        body: {
+          id: like('pi_succeeded'),
+          status: regex('succeeded|processing', 'succeeded'),
+          amount: like(1099),
+          currency: like('usd'),
+        },
+      })
+      .executeTest(async (mockServer) => {
+        const client = new PaymentsClient(mockServer.url);
+        const intent = await client.getPaymentIntent('pi_succeeded');
+        expect(intent.status).toBe('succeeded');
+      });
+  });
+});
+```
+
+Generated Pact file (`./pacts/checkout-service-payments-api.json`):
+
+```json
+{
+  "consumer": { "name": "checkout-service" },
+  "provider": { "name": "payments-api" },
+  "interactions": [
+    {
+      "description": "a request for a succeeded payment intent",
+      "providerStates": [{ "name": "payment intent pi_succeeded exists" }],
+      "request": {
+        "method": "GET",
+        "path": "/payment_intents/pi_succeeded"
+      },
+      "response": {
+        "status": 200,
+        "body": { "id": "pi_succeeded", "status": "succeeded", "amount": 1099, "currency": "usd" }
+      }
+    }
+  ]
+}
+```
+
+**Provider verification — payments-api (Go)**
+
+```go
+// payments-api/contract_test.go
+func TestPaymentsAPIProviderContract(t *testing.T) {
+    verifier := provider.NewVerifier()
+    err := verifier.VerifyProvider(t, provider.VerifyRequest{
+        ProviderBaseURL:            "http://localhost:8080",
+        BrokerURL:                  "https://broker.acme.com",
+        BrokerToken:                os.Getenv("PACT_BROKER_TOKEN"),
+        PublishVerificationResults: true,
+        ProviderVersion:            os.Getenv("GIT_SHA"),
+        StateHandlers: provider.StateHandlers{
+            "payment intent pi_succeeded exists": func(setup bool, s provider.ProviderStateV3) (provider.ProviderStateV3Response, error) {
+                if setup {
+                    seedPaymentIntent("pi_succeeded", "succeeded")
+                }
+                return provider.ProviderStateV3Response{}, nil
+            },
+        },
+    })
+    assert.NoError(t, err)
+}
+```
+
+**oasdiff in CI (GitHub Actions)**
+
+```yaml
+- name: Check for breaking API changes
+  run: |
+    oasdiff breaking \
+      origin/main:specs/openapi.yaml \
+      specs/openapi.yaml \
+      --fail-on ERR
+```
+
+### Anti-Patterns
+
+1. **Provider-written contracts.** If the provider team writes the Pact interactions on behalf of all consumers, the contract reflects what the provider thinks consumers need — not what they actually use. Consumer teams must write their own contracts against their real code paths. A contract written by the wrong team detects nothing.
+
+2. **Testing the full response body instead of the minimum required fields.** A consumer test that asserts every field in the response will fail when the provider adds a new field — a non-breaking change triggers a false positive. Pact's `like()` and `eachLike()` matchers verify type and presence, not exact value; only assert the fields the consumer actually reads.
+
+3. **Running contract tests against a live shared environment.** Contract tests should run against a locally started provider or a dedicated test instance. Running against a shared staging environment makes tests non-deterministic: other teams' changes, data drift, and network flakiness cause spurious failures that erode trust in the suite.
+
+4. **Ignoring `can-i-deploy` before deployment.** Publishing a Pact file is not enough — the `can-i-deploy` check queries the Broker to confirm all consumer contracts are verified for the version being deployed to the target environment. Skipping this step allows a provider to deploy a version that has not been verified against the latest consumer contracts.
+
+## Details
+
+### Spectral Ruleset for API Governance
+
+A team-level spectral ruleset enforces conventions across all services:
+
+```yaml
+# .spectral.yaml
+extends: ['spectral:oas']
+rules:
+  operation-operationId-required:
+    description: Every operation must have an operationId
+    given: '$.paths.*[get,post,put,patch,delete,options,head]'
+    severity: error
+    then:
+      field: operationId
+      function: truthy
+
+  operation-success-response:
+    description: Every operation must have at least one 2xx response
+    given: '$.paths.*[get,post,put,patch,delete]'
+    severity: warn
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          patternProperties:
+            '^2[0-9]{2}$':
+              type: object
+
+  component-description:
+    description: All schema components must have a description
+    given: '$.components.schemas[*]'
+    severity: warn
+    then:
+      field: description
+      function: truthy
+```
+
+### Real-World Case Study: Atlassian Contract Testing at Scale
+
+Atlassian runs Pact across 200+ microservices in the Jira/Confluence platform. Before adopting consumer-driven contracts, cross-team integration failures were discovered during monthly joint testing sprints, often requiring 3–5 days of debugging to isolate the breaking service. After adopting Pact with a centralized Pact Broker:
+
+- Breaking changes are detected within the same CI run that introduces them — average detection time dropped from days to under 15 minutes
+- The Broker's network graph replaced a manually maintained service dependency wiki page that was perpetually out of date
+- Provider teams can refactor internal implementations freely as long as contracts pass; consumer teams can upgrade providers independently once `can-i-deploy` returns green
+
+The key enabler was mandate: every service that exposes an HTTP API must publish and verify Pact contracts before its pipeline can deploy to staging.
+
+## Source
+
+- [Pact Documentation](https://docs.pact.io)
+- [PactFlow CI/CD Setup Guide](https://docs.pactflow.io/docs/workshops/ci-cd)
+- [Spectral OpenAPI Linter](https://stoplight.io/open-source/spectral)
+- [oasdiff — OpenAPI Breaking Change Detection](https://github.com/Tufin/oasdiff)
+- [Martin Fowler — Consumer-Driven Contracts](https://martinfowler.com/articles/consumerDrivenContracts.html)
+
+## Process
+
+1. Consumer team writes Pact interactions using only the fields their code reads; run the Pact test locally to generate the Pact file and verify the mock server interaction.
+2. Publish the Pact file to the Pact Broker (via `pact-broker publish` or the Pact CLI) from the consumer's CI pipeline on every merge.
+3. Provider CI fetches all consumer Pact files from the Broker, runs provider verification with state handlers seeding required data, and publishes results back to the Broker.
+4. Add `oasdiff` and spectral lint as required CI checks on any pull request that modifies the OpenAPI spec; block merges on breaking changes or lint errors.
+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-openapi-design, api-backward-compatibility, api-versioning-url
+
+## Success Criteria
+
+- Every consumer service has at least one Pact file published to the Broker that covers its real API call paths.
+- Provider CI runs Pact verification against all consumer contracts and publishes results; the build fails if any consumer contract is not satisfied.
+- `oasdiff` runs on every pull request that modifies the OpenAPI spec and blocks merges on breaking changes without an accompanying version bump.
+- spectral or vacuum lint runs in CI and enforces the team's ruleset with no rule violations on the main branch.
+- `can-i-deploy` is invoked in the provider deployment pipeline before any environment promotion and blocks deployment when verification is incomplete.

package/dist/agents/skills/gemini-cli/api-contract-testing/skill.yaml

@@ -0,0 +1,42 @@
+name: api-contract-testing
+version: '1.0.0'
+description: Consumer-driven contract testing — Pact fundamentals, provider verification, schema validation in CI (spectral, vacuum), breaking change detection (oasdiff), contract as living documentation
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-openapi-design
+  - api-backward-compatibility
+  - api-versioning-url
+stack_signals:
+  - rest
+  - api
+  - openapi
+  - testing
+  - http
+keywords:
+  - contract-testing
+  - Pact
+  - consumer-driven
+  - provider-verification
+  - spectral
+  - oasdiff
+  - breaking-change-detection
+  - schema-validation
+metadata:
+  author: community
+  upstream: docs.pact.io
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/api-deprecation-strategy/SKILL.md

@@ -0,0 +1,156 @@
+# API Deprecation Strategy
+
+> DEPRECATION STRATEGY DEFINES THE STRUCTURED PROCESS OF RETIRING API VERSIONS AND ENDPOINTS — USING SUNSET AND DEPRECATION HEADERS, MIGRATION GUIDES, AND COMMUNICATION CADENCE TO MOVE CONSUMERS FORWARD WITHOUT SURPRISE OUTAGES OR BROKEN INTEGRATIONS.
+
+## When to Use
+
+- Planning the retirement of a v1 API version after v2 has launched and reached sufficient adoption
+- Implementing machine-readable deprecation signals on responses so consumer tooling can surface warnings
+- Designing migration guide structure and content for a breaking API change
+- Setting deprecation policy for an API platform that will deprecate endpoints on a recurring basis
+- Auditing an existing API whose version retirement process has caused consumer outages or complaints
+- Building SDK tooling that detects and surfaces deprecation warnings from response headers
+- Establishing compatibility window standards for an API team or organization style guide
+
+## Instructions
+
+### Key Concepts
+
+1. **Sunset header (RFC 8594)** — The `Sunset` HTTP response header communicates the date and time after which a resource will no longer be available. Its value is an HTTP-date: `Sunset: Sat, 01 Jun 2025 00:00:00 GMT`. RFC 8594 defines the standard so that generic tooling — API clients, SDK generators, monitoring dashboards — can parse and act on it without bespoke logic. Emit `Sunset` on every response from a deprecated endpoint, not just the first request.
+
+2. **Deprecation header** — The `Deprecation` HTTP response header (draft RFC) marks a resource as deprecated without implying imminent removal. Its value is a boolean (`Deprecation: true`) or an HTTP-date indicating when deprecation began (`Deprecation: Mon, 01 Jan 2024 00:00:00 GMT`). Pair it with a `Link` header pointing to the migration guide: `Link: <https://api.example.com/migration/v1-to-v2>; rel="deprecation"`. The `Deprecation` header signals "this still works but you should migrate"; `Sunset` signals "this stops working on [date]".
+
+3. **Migration guide design** — A migration guide must contain: a summary of every breaking change (not just "see changelog"), before/after request/response examples for each changed endpoint, a step-by-step migration checklist, and a compatibility testing strategy. The guide is a contract document — publish it at a stable, versioned URL and do not alter it after the sunset date is announced. Consumers link to it from their own internal docs.
+
+4. **Compatibility windows** — Define minimum windows at API launch, not at deprecation time: for example, "v1 will be supported for at least 18 months after v2 GA." Public-facing APIs typically commit to 12–24 month windows; internal APIs may use shorter windows (3–6 months) if consumer teams are coordinated. The window starts from the v2 GA announcement, not from the v1 deprecation announcement. Publish the policy in the API reference docs.
+
+5. **Communication cadence** — Deprecation is a communication process, not a technical event. Effective cadence: (1) Announce v2 GA and v1 deprecation start simultaneously; (2) Send email and in-app notifications to all consumers with active v1 traffic; (3) Emit `Deprecation` + `Sunset` headers from day one; (4) Send reminder notifications at 6 months, 3 months, 1 month, and 1 week before sunset; (5) Monitor v1 traffic and personally contact consumers still active at the 1-month mark; (6) Execute sunset and return `410 Gone` on all v1 endpoints.
+
+6. **Post-sunset response** — After the sunset date, retired endpoints must return `410 Gone` (not `404 Not Found`). `410` is permanent and semantically distinct: it signals "this resource existed and was intentionally removed" rather than "this resource was never here." Include a body pointing to the migration guide and the v2 equivalent endpoint. Log all `410` responses for consumer diagnosis.
+
+### Worked Example
+
+The GitHub REST API deprecation of the Issues Search endpoint demonstrates production-grade deprecation headers:
+
+**Deprecated endpoint response:**
+
+```http
+GET /legacy/issues/search/{owner}/{repository}/{state}/{keyword}
+Authorization: Bearer ghp_...
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+Deprecation: true
+Sunset: Fri, 01 Aug 2025 00:00:00 GMT
+Link: <https://docs.github.com/rest/search/search#search-issues-and-pull-requests>; rel="successor-version"
+Link: <https://docs.github.com/rest/deprecations>; rel="deprecation"
+
+{ ... }
+```
+
+The `Link` header with `rel="successor-version"` points to the replacement endpoint. `rel="deprecation"` points to the general deprecation policy page. Generic tooling can follow these links without service-specific knowledge.
+
+**Stripe deprecation communication — version changelog:**
+
+```
+Stripe Version 2022-08-01 — Breaking Changes:
+- PaymentIntent.status values changed: "requires_source" renamed to "requires_payment_method"
+- Removed: charges.refunds nested array (use /v1/refunds?charge=ch_xxx instead)
+
+Sunset date: 2024-08-01
+
+Migration guide: https://stripe.com/docs/upgrades#2022-08-01
+```
+
+Stripe emails all customers with API keys created before the breaking version, providing the changelog summary and a direct link to the migration guide. The `Stripe-Version` header on all responses surfaces the currently active version so consumers can see their pinned version in logs.
+
+**Twilio post-sunset 410 response:**
+
+```http
+GET /2008-08-01/Accounts/{AccountSid}/Calls
+Authorization: Basic ...
+```
+
+```http
+HTTP/1.1 410 Gone
+Content-Type: application/json
+
+{
+  "code": 20006,
+  "message": "API version 2008-08-01 has been retired.",
+  "more_info": "https://www.twilio.com/docs/usage/api/api-versioning",
+  "status": 410
+}
+```
+
+Twilio's `410` body includes a machine-readable code (`20006`), a human-readable message naming the specific version, and a link to the versioning documentation.
+
+### Anti-Patterns
+
+1. **Announcing sunset with insufficient notice.** A 30-day sunset window for a public API is effectively a forced outage for consumers who do not monitor response headers or release notes. Fix: commit to minimum compatibility windows at API launch (12–24 months for public APIs), announce the window with v2 GA, and surface the `Sunset` header in developer dashboards and SDK warnings.
+
+2. **Returning 404 instead of 410 after sunset.** `404 Not Found` on a sunset endpoint causes consumer teams to spend hours debugging routing, authentication, and typos before realizing the endpoint was retired. `410 Gone` is unambiguous. Fix: implement a specific `410` handler for sunset endpoints with a body pointing to the migration guide, active during the post-sunset monitoring window.
+
+3. **Migration guides without before/after examples.** A migration guide that lists breaking changes in prose without showing the actual HTTP request/response change forces consumers to reverse-engineer each change. Fix: every breaking change entry in the migration guide must include the v1 request, v1 response, v2 request, and v2 response in full.
+
+4. **Emitting deprecation headers only on the first request.** Some implementations add deprecation headers only when the consumer has not visited the migration page. This breaks SDK tooling and monitoring dashboards that aggregate headers across sampled responses. Fix: emit `Deprecation` and `Sunset` on every response from every deprecated endpoint, unconditionally.
+
+## Details
+
+### SDK Integration for Deprecation Detection
+
+SDKs should inspect response headers on every call and surface deprecation warnings to developers at integration time. Example pattern in a hypothetical SDK:
+
+```javascript
+// In HTTP response handler
+if (response.headers['deprecation']) {
+  const sunset = response.headers['sunset'];
+  const link = parseLinkHeader(response.headers['link'])?.deprecation;
+  console.warn(
+    `[API SDK] Deprecated endpoint called. Sunset: ${sunset ?? 'unspecified'}. ` +
+      `Migration guide: ${link ?? 'see API docs'}`
+  );
+}
+```
+
+This transforms a passive HTTP header into an active developer warning visible in test output and CI logs — significantly increasing discovery rate compared to documentation-only communication.
+
+### Traffic Monitoring During Deprecation Window
+
+Instrument v1 traffic by consumer (API key or OAuth client ID) throughout the deprecation window. Track the migration rate: percentage of consumers with zero v1 calls in the trailing 7 days. Reach out personally (email, Slack, account manager) to consumers still active at the 30-day mark. At the 7-day mark, send a final warning with concrete impact details: "Your integration made 14,382 calls to deprecated endpoints in the past 7 days. These will fail on [date]."
+
+### Real-World Case Study: Twilio API Version Retirement
+
+Twilio retired their 2008-08-01 API version after a 3-year deprecation window. Their process: (1) Announced sunset 24 months in advance via email and developer blog; (2) Added `Deprecation` and `Sunset` headers to all v1 responses; (3) Published a migration guide with endpoint-by-endpoint mappings; (4) Monitored traffic by account SID and sent personalized outreach to all accounts with active legacy traffic at 90, 30, and 7 days before sunset; (5) Provided a free migration review service through their developer relations team. Result: 99.2% of traffic migrated before sunset. The 0.8% that failed at sunset were stale integrations with no active account owners — all were resolved within 48 hours through support tickets. Twilio's post-mortem noted that the personal outreach at 30 days drove 60% of the remaining migrations and was the highest-ROI activity in the deprecation process.
+
+## Source
+
+- [RFC 8594 — The Sunset HTTP Header Field](https://rfc-editor.org/rfc/rfc8594)
+- [Deprecation Header (IETF Draft)](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-deprecation-header)
+- [GitHub REST API Deprecations](https://docs.github.com/en/rest/overview/api-previews-and-deprecations)
+- [Stripe API Upgrade Guide](https://stripe.com/docs/upgrades)
+- [APIs You Won't Hate — Surviving Deprecation](https://apisyouwonthate.com/blog/surviving-deprecation)
+
+## Process
+
+1. Define the compatibility window policy (e.g., 18 months minimum) and publish it in API reference documentation before any version ships.
+2. At v2 GA, begin emitting `Deprecation` and `Sunset` headers on all v1 responses, with `Link` headers pointing to the migration guide.
+3. Send deprecation announcement to all consumers with active v1 traffic; include the sunset date, changelog summary, and migration guide link.
+4. Monitor v1 traffic by consumer throughout the window; send reminder notifications at 6 months, 3 months, 1 month, and 1 week before sunset.
+5. At sunset, return `410 Gone` on all retired endpoints with a body pointing to the migration guide and the v2 equivalent.
+
+## 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-backward-compatibility, api-versioning-url, api-sdk-ergonomics
+
+## Success Criteria
+
+- All deprecated endpoints emit `Deprecation` and `Sunset` response headers on every response, not just the first.
+- A migration guide with before/after HTTP examples exists for every breaking change in the deprecated version.
+- The compatibility window policy is published in API documentation before any version launches, not at deprecation time.
+- Consumers are notified of deprecation through at least two channels (email + response headers) with a minimum of 12 months notice for public APIs.
+- Sunset endpoints return `410 Gone` with a body pointing to the migration guide, not `404 Not Found`.

package/dist/agents/skills/gemini-cli/api-deprecation-strategy/skill.yaml

@@ -0,0 +1,39 @@
+name: api-deprecation-strategy
+version: '1.0.0'
+description: Sunset header (RFC 8594), Deprecation header, migration guide design, compatibility windows, communication cadence
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-backward-compatibility
+  - api-versioning-url
+  - api-sdk-ergonomics
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - deprecation
+  - Sunset-header
+  - RFC-8594
+  - Deprecation-header
+  - migration-guide
+  - compatibility-window
+  - sunset-date
+metadata:
+  author: community
+  upstream: rfc-editor.org/rfc/rfc8594
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/api-error-contracts/SKILL.md

@@ -0,0 +1,149 @@
+# API Error Contracts
+
+> ERROR CONTRACTS DEFINE THE MACHINE-READABLE STRUCTURE, HUMAN-READABLE MESSAGE, AND ACTIONABLE REMEDIATION FOR EVERY FAILURE MODE — CONSISTENT ERROR RESPONSE DESIGN LETS CLIENTS HANDLE ERRORS PROGRAMMATICALLY WITHOUT PARSING FREE-TEXT OR REVERSE-ENGINEERING FAILURE SEMANTICS.
+
+## When to Use
+
+- Designing the error response shape for a new API or service before writing any handlers
+- Reviewing a PR that returns unstructured error strings or inconsistent error shapes across endpoints
+- Establishing an API style guide section on error response standards for a team or organization
+- Auditing an existing API whose clients report confusion about how to distinguish error categories
+- Choosing between application-level error codes (e.g., `CARD_DECLINED`) and HTTP status codes for client routing
+- Building SDKs or client libraries that need to surface typed, catchable error objects to callers
+- Implementing error monitoring and alerting where machine-readable codes are required to classify alerts
+- Documenting all possible error conditions for each endpoint in an OpenAPI specification
+
+## Instructions
+
+### Key Concepts
+
+1. **Machine-readable error codes** — An application-level error code (`"code": "INSUFFICIENT_FUNDS"`) is distinct from the HTTP status code. It identifies the specific failure type within a category so clients can branch on it without parsing free-text messages. Example: two Stripe `402` responses may have `"code": "card_declined"` or `"code": "expired_card"` — the HTTP status routes to the payment-failure handler; the code selects the message shown to the user.
+
+2. **Human-readable messages** — The `message` field is for developers reading logs or API explorer output, not for display in end-user interfaces. It should be complete and unambiguous: `"The card ending in 4242 was declined by the issuer"` rather than `"Card error"`. Avoid exposing internal implementation details, stack traces, or database error messages.
+
+3. **Actionable remediation** — Every error response should answer: "What should the caller do next?" The `"detail"` field (per RFC 9457) or a dedicated `"suggestion"` field communicates the next step: `"Retry with a different payment method"`, `"Check that the field matches ISO 8601 format"`, or `"Contact support with reference ID abc-123"`. Errors without remediation guidance shift the debugging burden to the caller.
+
+4. **Error taxonomy** — Group error codes into categories that map to HTTP status classes: authentication errors (`401`), authorization errors (`403`), validation errors (`422`), business-rule violations (`409`/`422`), and server faults (`500`). A taxonomy prevents code proliferation and makes documentation searchable. Publish the full taxonomy in API reference docs; include a `type` URI (per RFC 9457) so clients can link to the documentation for each error type.
+
+5. **Consistent envelope structure** — Every error response from every endpoint must use the same JSON shape. Mixing `{ "error": "..." }`, `{ "message": "...", "errors": [...] }`, and `{ "code": ..., "description": ... }` across endpoints breaks SDK code generation and forces client-side shape detection. Choose one envelope (RFC 9457 Problem Details is the recommended standard) and enforce it at the framework/middleware level.
+
+6. **Error reference IDs** — For server-side faults (`5xx`), include a unique `instance` or `traceId` field that correlates the response to a specific log entry. This enables support teams to locate the root cause without asking users to reproduce the issue. Example: `"instance": "/errors/7f3a-bc91-..."` or `"traceId": "abc-123-xyz"`.
+
+### Worked Example
+
+Stripe's error contract is one of the most studied in production APIs. It uses a consistent envelope across all failure modes:
+
+**Payment declined (402 Payment Required):**
+
+```http
+POST /v1/charges
+Authorization: Bearer sk_example_...
+Content-Type: application/x-www-form-urlencoded
+
+amount=2000&currency=usd&source=tok_chargeDeclined
+```
+
+```http
+HTTP/1.1 402 Payment Required
+Content-Type: application/json
+
+{
+  "error": {
+    "type": "card_error",
+    "code": "card_declined",
+    "decline_code": "insufficient_funds",
+    "message": "Your card has insufficient funds.",
+    "param": "source",
+    "charge": "ch_3N..."
+  }
+}
+```
+
+**Invalid API key (401 Unauthorized):**
+
+```http
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+
+{
+  "error": {
+    "type": "authentication_error",
+    "code": "api_key_invalid",
+    "message": "No such API key: sk_example_****abc.",
+    "doc_url": "https://stripe.com/docs/error-codes/api-key-invalid"
+  }
+}
+```
+
+**Missing required parameter (400 Bad Request):**
+
+```http
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{
+  "error": {
+    "type": "invalid_request_error",
+    "code": "parameter_missing",
+    "message": "Missing required param: amount.",
+    "param": "amount",
+    "doc_url": "https://stripe.com/docs/error-codes/parameter-missing"
+  }
+}
+```
+
+Stripe's taxonomy (`card_error`, `authentication_error`, `invalid_request_error`, `api_error`, `idempotency_error`) maps cleanly to HTTP status ranges. The `code` field gives a programmatic subcategory; `param` identifies the offending field; `doc_url` links to remediation. SDK clients switch on `error.type` for top-level routing and `error.code` for specific handling — without any free-text parsing.
+
+### Anti-Patterns
+
+1. **Free-text error strings only.** `{ "error": "Something went wrong" }` or `{ "message": "Invalid input" }` forces clients to parse English prose to determine the error type. Localization, rewording, or phrasing changes in the message silently break clients that pattern-match on strings. Fix: always include a machine-readable `code` field alongside the human-readable `message`.
+
+2. **Inconsistent envelope shape across endpoints.** When one endpoint returns `{ "error": { "message": "..." } }` and another returns `{ "errors": ["..."] }` and a third returns `{ "status": "error", "reason": "..." }`, client error handling requires per-endpoint special cases. Fix: enforce a single error shape at the middleware or gateway layer so every response is shaped identically before leaving the server.
+
+3. **Leaking internal error details.** Including `"sqlState": "23000"`, `"stackTrace": "..."`, or `"internalMessage": "NullPointerException at line 42"` in error responses exposes implementation internals, aids attackers, and creates API surface that clients may start depending on. Fix: log internal details server-side and surface only a `traceId` for correlation. The public error contains only what is safe and useful for the caller.
+
+4. **Omitting actionable remediation.** An error like `{ "code": "RATE_LIMITED" }` without a `Retry-After` header or a `detail` explaining when to retry is incomplete. The caller either retries immediately (worsening the rate-limit problem) or gives up unnecessarily. Fix: every error response should include what the caller should do next — retry timing, which parameter to fix, or where to get help.
+
+## Details
+
+### Error Code Naming Conventions
+
+Error codes should use consistent casing (SCREAMING_SNAKE_CASE for application codes is common; `snake_case` is used by Stripe and GitHub). Codes must be stable across API versions — changing `CARD_DECLINED` to `PAYMENT_DECLINED` is a breaking change for any client that switches on the code. Prefix codes by domain when the taxonomy is large: `AUTH_TOKEN_EXPIRED`, `PAYMENT_CARD_DECLINED`, `VALIDATION_FIELD_REQUIRED`.
+
+### Error Documentation Requirements
+
+Every published error code should be documented with: the HTTP status code it accompanies, a description of when it occurs, the fields present in the response for this code, and recommended client action. This documentation is the contract — treat removals or renames as breaking changes.
+
+### Real-World Case Study: Twilio Error Contracts
+
+Twilio maintains a published error dictionary at `twilio.com/docs/api/errors` with over 600 documented error codes. Each code has a dedicated page with: description, possible causes, and suggested resolution steps. When Twilio's REST API returns an error, it includes `"code": 21211` (for example) alongside the HTTP `400` status. Clients look up the code in documentation or switch on it directly. Twilio's developer surveys show that APIs with published error taxonomies reduce average debugging time by 40-60% compared to APIs that return only HTTP status codes and free-text messages. The combination of stable machine-readable codes and linked documentation is the highest-leverage investment in API error design.
+
+## Source
+
+- [Creating Good API Errors in REST, GraphQL, and gRPC — APIs You Won't Hate](https://apisyouwonthate.com/blog/creating-good-api-errors-in-rest-graphql-and-grpc)
+- [RFC 9457 — Problem Details for HTTP APIs](https://rfc-editor.org/rfc/rfc9457)
+- [Stripe API Error Reference](https://stripe.com/docs/api/errors)
+- [Twilio Error and Warning Dictionary](https://www.twilio.com/docs/api/errors)
+- [Microsoft REST API Guidelines — Error Responses](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#error-responses)
+
+## Process
+
+1. Define the error envelope structure: choose RFC 9457 Problem Details or a documented custom shape, and enforce it at the framework level across all endpoints.
+2. Create an error taxonomy document listing every application-level error code, its HTTP status, its description, and its recommended client action.
+3. For each endpoint, document all possible error codes in the OpenAPI spec under the appropriate `4xx`/`5xx` response schemas.
+4. Implement an error serialization middleware that maps internal exceptions to the canonical error envelope — never let raw exception types reach the serializer.
+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-problem-details-rfc, api-status-codes, api-validation-errors, api-bulk-operations
+
+## Success Criteria
+
+- Every error response across all endpoints uses the same JSON envelope structure.
+- All error responses include a stable, machine-readable `code` field alongside the human-readable `message`.
+- No error response exposes internal stack traces, SQL errors, or raw exception messages.
+- Every `5xx` response includes a `traceId` or `instance` field for log correlation.
+- The full error taxonomy is published in API documentation with remediation guidance for each code.

package/dist/agents/skills/gemini-cli/api-error-contracts/skill.yaml

@@ -0,0 +1,40 @@
+name: api-error-contracts
+version: '1.0.0'
+description: Consistent error response structure — machine-readable codes, human-readable messages, actionable remediation, and error taxonomies
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-problem-details-rfc
+  - api-status-codes
+  - api-validation-errors
+  - api-bulk-operations
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - error-contracts
+  - error-response
+  - error-code
+  - error-message
+  - machine-readable
+  - actionable-errors
+  - error-taxonomy
+metadata:
+  author: community
+  upstream: apisyouwonthate.com/blog/creating-good-api-errors-in-rest-graphql-and-grpc
+state:
+  persistent: false
+  files: []
+depends_on: []