@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/gemini-cli/api-status-codes/skill.yaml

@@ -0,0 +1,46 @@
+name: api-status-codes
+version: '1.0.0'
+description: Status code selection by scenario, common misuses (200 for errors, 404 vs 403, 400 vs 422), and response contract design
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-http-methods
+  - api-error-contracts
+  - api-problem-details-rfc
+  - api-rest-maturity-model
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - status-codes
+  - '200'
+  - '201'
+  - '204'
+  - '400'
+  - '401'
+  - '403'
+  - '404'
+  - '409'
+  - '422'
+  - '429'
+  - '500'
+  - '503'
+metadata:
+  author: community
+  upstream: developer.mozilla.org/en-US/docs/Web/HTTP/Status
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/api-validation-errors/SKILL.md

@@ -0,0 +1,174 @@
+# API Validation Errors
+
+> FIELD-LEVEL VALIDATION ERROR DESIGN — RETURNING ALL VALIDATION FAILURES IN A SINGLE RESPONSE WITH JSON POINTER PATHS AND PER-FIELD MESSAGES ELIMINATES THE ONE-ERROR-AT-A-TIME DEBUGGING LOOP AND GIVES CLIENTS ENOUGH INFORMATION TO HIGHLIGHT EVERY INVALID FIELD WITHOUT A SECOND REQUEST.
+
+## When to Use
+
+- Designing the validation error response for a form submission, resource creation, or bulk import endpoint
+- Reviewing a PR that returns `400` with a single error message for a request that may have multiple invalid fields
+- Choosing between `400 Bad Request` and `422 Unprocessable Entity` for semantic validation failures
+- Implementing field-level error display in a client application that consumes API validation responses
+- Building an API that mirrors JSON:API error object conventions or RFC 9457 validation extensions
+- Documenting the validation error schema for an OpenAPI specification
+- Designing error responses for a nested resource where invalid fields may be deep in the payload hierarchy
+- Auditing an existing API whose clients report that form validation requires multiple round-trips to surface all errors
+
+## Instructions
+
+### Key Concepts
+
+1. **Multi-field error arrays** — A single validation response should report all failing fields simultaneously, not just the first one encountered. The response body includes an array of error objects, each describing one invalid field: `"errors": [{ "pointer": "/email", ... }, { "pointer": "/birthdate", ... }]`. Stopping at the first failure creates a "whack-a-mole" experience where callers must submit, fail, fix, and resubmit for each field in turn.
+
+2. **JSON Pointer (RFC 6901)** — A standardized syntax for identifying a specific value within a JSON document. Pointers use `/` as a separator: `/user/email` identifies the `email` field inside a `user` object; `/items/0/price` identifies the `price` of the first element in an `items` array. In validation error responses, the `pointer` (or `source.pointer` in JSON:API) field identifies exactly which part of the request body failed validation — no ambiguity, no path string parsing.
+
+3. **`source/pointer` vs `source/parameter`** — JSON:API distinguishes two sources of validation error:
+   - `"source": { "pointer": "/data/attributes/email" }` — the error is in the request body, at a JSON Pointer location.
+   - `"source": { "parameter": "filter[status]" }` — the error is in a query parameter, not the body.
+     Use `pointer` for body fields, `parameter` for query string inputs. RFC 9457 extensions use `"pointer"` directly as a top-level extension field rather than nesting under `source`.
+
+4. **422 vs 400** — Use `400 Bad Request` for structurally malformed requests: unparseable JSON, missing `Content-Type`, invalid URL path parameters. Use `422 Unprocessable Entity` for requests that are syntactically valid but semantically invalid: a correctly parsed JSON body where `email` is not an email address, `end_date` precedes `start_date`, or a required field is present but empty. The distinction matters because `422` tells the client "your request reached the validation layer and failed there" — it is never retryable without changing the payload.
+
+5. **Per-field titles and details** — Each error object in the array should include a stable `title` (the validation rule that failed: `"Must be a valid email address"`) and an instance-specific `detail` (`"'not-an-email' is not a valid email address format"`). The `title` is reusable across occurrences of the same rule; `detail` adds the specific value that failed, making it debuggable without inspecting the original request.
+
+### Worked Example
+
+A Stripe-style account creation endpoint returning multi-field validation errors:
+
+**Request with multiple invalid fields:**
+
+```http
+POST /v1/accounts
+Authorization: Bearer sk_test_...
+Content-Type: application/json
+
+{
+  "email": "not-an-email",
+  "country": "XX",
+  "business_type": "individual",
+  "individual": {
+    "dob": {
+      "day": 32,
+      "month": 13,
+      "year": 1850
+    }
+  }
+}
+```
+
+```http
+HTTP/1.1 422 Unprocessable Entity
+Content-Type: application/problem+json
+
+{
+  "type": "https://api.example.com/errors/validation-failed",
+  "title": "Validation Failed",
+  "status": 422,
+  "detail": "3 fields failed validation. Correct the highlighted fields and resubmit.",
+  "instance": "/errors/correlation/a1b2-c3d4",
+  "errors": [
+    {
+      "pointer": "/email",
+      "title": "Must be a valid email address",
+      "detail": "'not-an-email' does not match the expected email format."
+    },
+    {
+      "pointer": "/country",
+      "title": "Must be a valid ISO 3166-1 alpha-2 country code",
+      "detail": "'XX' is not a recognized country code."
+    },
+    {
+      "pointer": "/individual/dob/day",
+      "title": "Day must be between 1 and 31",
+      "detail": "Received 32. Days in a month range from 1 to 31."
+    }
+  ]
+}
+```
+
+The `pointer` paths use RFC 6901 syntax: `/email` addresses the top-level field; `/individual/dob/day` drills into the nested `individual.dob.day` path. A client rendering a form can use each `pointer` to highlight the exact input that failed without any string parsing.
+
+**Query parameter validation error (400 Bad Request):**
+
+```http
+GET /v1/payments?status=unknownstatus&limit=abc
+```
+
+```http
+HTTP/1.1 400 Bad Request
+Content-Type: application/problem+json
+
+{
+  "type": "https://api.example.com/errors/invalid-query-parameter",
+  "title": "Invalid Query Parameter",
+  "status": 400,
+  "detail": "2 query parameters are invalid.",
+  "errors": [
+    {
+      "parameter": "status",
+      "title": "Must be one of: pending, succeeded, failed",
+      "detail": "'unknownstatus' is not a valid status value."
+    },
+    {
+      "parameter": "limit",
+      "title": "Must be an integer",
+      "detail": "'abc' cannot be parsed as an integer."
+    }
+  ]
+}
+```
+
+Query parameter errors use `"parameter"` instead of `"pointer"` because they are not in the request body.
+
+### Anti-Patterns
+
+1. **Returning a single error for the first failing field.** A form with 5 invalid fields returns only the first error. The user fixes it, resubmits, receives the second error, and so on for 5 round-trips. Fix: validate the entire request body, collect all errors, and return the full list in a single `422` response.
+
+2. **Using vague path strings instead of RFC 6901 pointers.** `"field": "individual.dob.day"` uses dot notation that requires parsing and breaks for array indices. `"field": "items[0].price"` uses a mix of dot and bracket notation with no standard. Fix: use RFC 6901 JSON Pointer syntax (`"/individual/dob/day"`, `"/items/0/price"`) — it is unambiguous, parseable by standard libraries, and consistent across implementations.
+
+3. **Returning `400` for semantic validation failures.** A request body that is valid JSON but contains an email address string that fails the email format check is not malformed — it passed JSON parsing. Returning `400` mixes structural errors with semantic ones, complicating client error routing. Fix: reserve `400` for structural failures (unparseable JSON, wrong Content-Type) and use `422` for any failure that occurs after successful parsing and type coercion.
+
+4. **Omitting the `pointer` for nested fields.** Returning `{ "field": "dob", "message": "Invalid date of birth" }` for a nested field fails to identify which level of nesting failed, and whether `dob.day`, `dob.month`, or `dob.year` is the problem. Fix: use the full JSON Pointer path to the failing field, however deep it is in the payload.
+
+## Details
+
+### JSON Pointer Encoding
+
+RFC 6901 defines two escape sequences for characters that conflict with the pointer syntax: `~0` represents a literal `~`, and `~1` represents a literal `/`. If a field name contains a slash — e.g., `"Content-Type"` — the pointer is `/Content~1Type`. This is rare in practice but important when generating pointers programmatically from field names.
+
+### Validation Error Design for Arrays
+
+For bulk operations or array inputs, the `pointer` must include the array index: `/items/2/quantity` identifies the `quantity` field of the third element (zero-indexed) in the `items` array. This is essential for bulk import endpoints where clients need to know which rows failed without re-matching errors to rows by field name.
+
+### Real-World Case Study: Shopify GraphQL Validation Errors
+
+Shopify's Admin API (both REST and GraphQL) returns structured validation errors with field paths. In the REST API, errors follow a `{ "errors": { "field_name": ["message"] } }` shape. In the GraphQL API, errors use the `userErrors` pattern: `{ "userErrors": [{ "field": ["lineItems", "0", "quantity"], "message": "Quantity must be greater than zero" }] }`. The `field` array is equivalent to a JSON Pointer path split on `/`. Shopify's developer documentation shows that APIs returning structured field-path errors report significantly fewer "which field caused the error?" support questions than APIs returning only top-level messages. The field path is the minimum information needed for a client to display inline validation feedback without guessing.
+
+## Source
+
+- [JSON:API — Error Objects](https://jsonapi.org/format/#error-objects)
+- [RFC 6901 — JavaScript Object Notation (JSON) Pointer](https://rfc-editor.org/rfc/rfc6901)
+- [RFC 9457 — Problem Details for HTTP APIs](https://rfc-editor.org/rfc/rfc9457)
+- [Shopify API — Error Handling](https://shopify.dev/docs/api/usage/response-codes)
+- [APIs You Won't Hate — Validation Errors](https://apisyouwonthate.com/blog/rest-api-error-choose-your-own-adventure)
+
+## Process
+
+1. Identify all inputs that require validation: request body fields, path parameters, query parameters, and headers.
+2. Run validation against all fields and collect the complete error list before constructing the response.
+3. Map each error to a `pointer` (for body fields using RFC 6901) or `parameter` (for query string inputs).
+4. Construct the `422` response with an `errors` array containing per-field `title` and `detail` entries.
+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-problem-details-rfc, api-error-contracts, api-bulk-operations, api-status-codes
+
+## Success Criteria
+
+- Validation responses include all failing fields in a single response, never just the first one.
+- Field paths use RFC 6901 JSON Pointer syntax (`/field/subfield/index`), not dot notation or custom path formats.
+- `422 Unprocessable Entity` is used for semantic validation failures; `400 Bad Request` is reserved for structural/parse failures.
+- Each error object includes a stable `title` (the rule) and an instance-specific `detail` (the offending value and why it failed).
+- Query parameter errors use a `parameter` field, not a `pointer` field.

package/dist/agents/skills/gemini-cli/api-validation-errors/skill.yaml

@@ -0,0 +1,40 @@
+name: api-validation-errors
+version: '1.0.0'
+description: Field-level validation error design — multi-field error arrays, JSON Pointer (RFC 6901) paths, source/pointer vs source/parameter, and 422 vs 400 choice
+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-error-contracts
+  - api-bulk-operations
+  - api-status-codes
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - validation-errors
+  - field-errors
+  - JSON-pointer
+  - RFC-6901
+  - '422'
+  - multi-error
+  - source-pointer
+metadata:
+  author: community
+  upstream: jsonapi.org/format/#error-objects
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/api-versioning-header/SKILL.md

@@ -0,0 +1,177 @@
+# API Versioning — Header
+
+> HEADER VERSIONING NEGOTIATES API VERSION THROUGH HTTP HEADERS RATHER THAN URI PATHS — IT KEEPS URIS CLEAN AND RESOURCE-CENTRIC WHILE ENABLING FINE-GRAINED BEHAVIORAL VERSIONING, VENDOR MEDIA TYPES, AND CONTENT-TYPE-LEVEL DIFFERENTIATION WITHOUT PROLIFERATING PATH PREFIXES.
+
+## When to Use
+
+- Designing a versioning strategy for an internal or partner API where URI cleanliness and REST purity are priorities
+- Implementing fine-grained behavioral versioning within a single major URL version (as Stripe does with `Stripe-Version`)
+- Publishing a hypermedia API where vendor media types (`application/vnd.company.v2+json`) carry version semantics
+- Migrating from URL versioning to header versioning and needing to understand content negotiation mechanics
+- Building an API gateway rule set that routes requests based on `Accept` or custom version headers
+- Evaluating tradeoffs between `Accept` header negotiation and a custom `API-Version` header for a new API platform
+- Auditing an existing API for version header consistency across SDKs and documentation examples
+
+## Instructions
+
+### Key Concepts
+
+1. **Accept header negotiation** — The standard HTTP mechanism for version negotiation uses the `Accept` header with a vendor media type: `Accept: application/vnd.github.v3+json`. The server inspects this header and returns the response formatted for the requested version. If the version is unsupported, the server returns `406 Not Acceptable`. This is true content negotiation per RFC 7231 — the client declares what it can accept, and the server selects the best match.
+
+2. **Vendor media types** — A vendor media type (IANA `vnd.` prefix) encodes the organization, resource type, and version in the `Content-Type` value: `application/vnd.company.resource.v2+json`. This is the most REST-pure versioning approach because the type itself carries the version, and a resource at `/users/42` can serve multiple representations via the same URI. Vendor types must be registered with IANA for public use, though the `vnd.` prefix convention is widely adopted without formal registration.
+
+3. **Custom version headers** — Many APIs use a custom header (`API-Version: 2024-01-01`, `Stripe-Version: 2023-10-16`, `X-GitHub-Api-Version: 2022-11-28`) rather than encoding the version in `Accept`. Custom headers are simpler to implement, easier to document, and avoid content negotiation complexity. The tradeoff: they are not standard HTTP and require consumers to know the header name. Stripe and GitHub both use custom headers for date-based fine-grained versioning.
+
+4. **Default version behavior** — Requests without a version header must have a defined behavior: serve the oldest supported version (for maximum compatibility) or serve the latest version (for minimum maintenance burden). Stripe defaults to each customer's first-used version, stored on the API key — a sophisticated approach that prevents silent breaking changes for long-lived integrations without requiring explicit header pinning.
+
+5. **Caching considerations** — Header-versioned responses require `Vary: Accept` or `Vary: API-Version` in the response to prevent CDN and proxy caches from serving the wrong version. Without `Vary`, a cache that stores a v1 response may return it to a v2 client. Most CDNs handle `Vary` on `Accept` poorly, leading to low cache-hit rates or disabled caching for header-versioned APIs. This is the primary operational argument for URL versioning on high-traffic public APIs.
+
+6. **Version discovery** — Unlike URL versioning where versions are visible in the path, header-versioned APIs must publish supported versions through documentation or a discovery endpoint. A common pattern is a `/versions` endpoint listing all supported versions, their status (active, deprecated, sunset), and their sunset dates. GitHub's REST API exposes this at `GET /versions`.
+
+### Worked Example
+
+GitHub uses a custom version header (`X-GitHub-Api-Version`) for fine-grained date-based versioning, overlaid on their URL-anchored REST API base:
+
+**Explicit version header request:**
+
+```http
+GET /repos/octocat/Hello-World
+Accept: application/vnd.github+json
+Authorization: Bearer ghp_...
+X-GitHub-Api-Version: 2022-11-28
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/vnd.github+json
+X-GitHub-Api-Version: 2022-11-28
+
+{
+  "id": 1296269,
+  "name": "Hello-World",
+  "full_name": "octocat/Hello-World",
+  ...
+}
+```
+
+**Unsupported version response:**
+
+```http
+GET /repos/octocat/Hello-World
+X-GitHub-Api-Version: 2009-01-01
+```
+
+```http
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{
+  "message": "Unsupported version: 2009-01-01",
+  "documentation_url": "https://docs.github.com/rest/overview/api-versions"
+}
+```
+
+**Stripe date-based version header:**
+
+```http
+POST /v1/payment_intents
+Authorization: Bearer sk_example_...
+Stripe-Version: 2023-10-16
+Content-Type: application/x-www-form-urlencoded
+
+amount=2000&currency=usd
+```
+
+Stripe stores the version used at API key creation as the default, so long-lived integrations never see unexpected behavioral changes. The `Stripe-Version` header can override this default for testing or migration. Each version is documented in Stripe's changelog at `stripe.com/docs/upgrades` with a complete list of behavioral differences.
+
+**Vendor media type (GitHub legacy v3):**
+
+```http
+GET /repos/octocat/Hello-World
+Accept: application/vnd.github.v3+json
+Authorization: Bearer ghp_...
+```
+
+GitHub's older `vnd.github.v3+json` vendor type embedded the version directly in the `Accept` header — true content negotiation. This was replaced by the `X-GitHub-Api-Version` header approach because custom headers are more predictable in proxies and CDN routing rules.
+
+### Anti-Patterns
+
+1. **Missing `Vary` header on cached responses.** A header-versioned API that returns identical `Cache-Control` headers without `Vary: API-Version` (or `Vary: Accept`) allows CDN and proxy caches to serve v1 responses to v2 clients. The bug is intermittent and environment-dependent — it passes local tests and fails in production under CDN. Fix: always include `Vary` on any response dimension that determines the representation.
+
+2. **Silently defaulting to latest version.** An API that silently serves the latest version when no version header is present will break existing clients when a new version ships. Fix: default to the oldest supported version (or the version pinned at key creation, as Stripe does) and document this behavior explicitly. Never let the default version change without a consumer-visible signal.
+
+3. **Undocumented custom header name.** Using `X-Api-Version` in one service, `API-Version` in another, and `App-Version` in a third makes SDK generation impossible and forces consumers to read per-service documentation for every integration. Fix: standardize on one custom header name across all services in an organization and document it prominently in the API style guide.
+
+4. **Ignoring `Accept` header errors.** Returning `200 OK` with the default version when the client requests an unsupported version (`Accept: application/vnd.company.v99+json`) silently ignores the client's intent. The client believes it is receiving v99 format but gets v1. Fix: return `406 Not Acceptable` with a body listing supported versions and their `Accept` values.
+
+## Details
+
+### Content Negotiation vs. Custom Headers: Decision Guide
+
+Use `Accept` header / vendor media types when: building a hypermedia API, strict REST compliance is required, or the API serves multiple representation formats (JSON, XML, MessagePack) that benefit from unified content negotiation.
+
+Use a custom version header (`API-Version`, `Stripe-Version`) when: the API only serves JSON, simplicity for SDK authors is prioritized, or the versioning policy is date-based rather than integer-based.
+
+Avoid mixing both approaches in the same API — consumers face combinatorial complexity debugging which header controls which behavioral dimension.
+
+### Version Discovery Endpoint
+
+Expose supported versions at a stable, unauthenticated endpoint:
+
+```http
+GET /versions
+```
+
+```json
+{
+  "supported": [
+    {
+      "version": "2024-01-15",
+      "status": "active",
+      "sunset": null
+    },
+    {
+      "version": "2022-11-28",
+      "status": "deprecated",
+      "sunset": "2025-06-01"
+    }
+  ],
+  "default": "2022-11-28"
+}
+```
+
+This enables tooling, SDK generators, and integration test suites to enumerate and test all supported versions programmatically.
+
+### Real-World Case Study: Stripe Version Pinning
+
+Stripe's header versioning model — where each API key stores the version at creation time as the default — has enabled them to maintain backward compatibility across hundreds of behavioral versions since 2013 without a single forced migration. When a new customer creates an API key today, they are pinned to the current version. When an existing customer with a 2015-era key makes a request without a `Stripe-Version` header, they receive 2015 behavior. Stripe's engineering team has documented that this model, combined with their version changelog and upgrade guide, reduces migration-related support tickets by an estimated 70% compared to APIs that default to latest. The cost is operational: each behavioral version must be maintained in the codebase indefinitely. Stripe mitigates this with a dedicated versioning team and a structured deprecation process that gates retirement on adoption metrics.
+
+## Source
+
+- [semver.org — Semantic Versioning Specification](https://semver.org)
+- [GitHub REST API Versions](https://docs.github.com/en/rest/overview/api-versions)
+- [Stripe API Upgrades and Versioning](https://stripe.com/docs/upgrades)
+- [RFC 7231 — HTTP/1.1 Semantics: Content Negotiation](https://rfc-editor.org/rfc/rfc7231#section-5.3)
+- [APIs You Won't Hate — Picking a Versioning Method](https://apisyouwonthate.com/blog/api-versioning-has-no-right-way)
+
+## Process
+
+1. Choose between `Accept`-based content negotiation and a custom version header; document the decision and its rationale in the API style guide.
+2. Define the default-version policy: oldest supported, latest, or key-pinned — and document it as a consumer-facing guarantee.
+3. Add `Vary: API-Version` (or `Vary: Accept`) to all version-negotiated responses before deploying behind a CDN or reverse proxy.
+4. Publish a `/versions` discovery endpoint listing supported versions, their status, and sunset dates.
+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-versioning-url, api-content-negotiation, api-backward-compatibility
+
+## Success Criteria
+
+- All version-negotiated responses include a `Vary` header for the version dimension to prevent cache collisions.
+- The default version behavior when no header is present is documented and tested as a consumer-facing guarantee.
+- A single, consistent version header name is used across all services in the organization.
+- A `/versions` discovery endpoint enumerates supported versions, their status, and sunset dates.
+- Requests specifying an unsupported version receive `406 Not Acceptable` with a list of valid values.

package/dist/agents/skills/gemini-cli/api-versioning-header/skill.yaml

@@ -0,0 +1,37 @@
+name: api-versioning-header
+version: '1.0.0'
+description: Accept header versioning (content negotiation), custom version headers (API-Version:), vendor media types (application/vnd.company.v2+json)
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-versioning-url
+  - api-content-negotiation
+  - api-backward-compatibility
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - header-versioning
+  - Accept-header
+  - vendor-media-type
+  - API-Version
+  - content-negotiation-versioning
+metadata:
+  author: community
+  upstream: semver.org
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/api-versioning-url/SKILL.md

@@ -0,0 +1,128 @@
+# API Versioning — URL Path
+
+> URL PATH VERSIONING EMBEDS THE API VERSION DIRECTLY IN THE URI (/v1/, /v2/) — IT TRADES CLEAN URI SEMANTICS FOR MAXIMUM VISIBILITY AND CACHEABILITY, MAKING IT THE DEFAULT CHOICE FOR PUBLIC APIs WHERE DEVELOPER EXPERIENCE AND REVERSE-PROXY ROUTING SIMPLICITY OUTWEIGH STRICT REST PURITY.
+
+## When to Use
+
+- Designing the versioning strategy for a new public API that will be consumed by third-party developers
+- Migrating a v1 API to v2 with breaking changes and needing simultaneous support for both versions
+- Setting API style guide policy for a team or organization that ships multiple services
+- Evaluating whether URL versioning or header versioning better fits your gateway and CDN routing model
+- Building an SDK where typed version-specific client classes improve generated code clarity
+- Routing different API versions to different backend services or microservice deployments
+- Communicating breaking changes to external consumers with explicit, copy-pasteable migration examples
+
+## Instructions
+
+### Key Concepts
+
+1. **Version prefix placement** — The version identifier belongs in the first path segment, immediately after the host: `https://api.example.com/v1/users`. Placing it deeper (`/users/v1`) breaks routing rules and makes wildcard proxying fragile. The prefix applies to the entire API surface under it — never to individual resources.
+
+2. **Major-only versioning** — URL versions track breaking changes only. Minor and patch changes (new optional fields, new endpoints, new query parameters) are additive and do not warrant a new version prefix. Incrementing the URL version for non-breaking changes wastes consumer migration effort and signals instability. Follow the rule: if existing clients break, bump the URL version; if they do not, they should not need to.
+
+3. **Simultaneous version support window** — Running v1 and v2 in parallel is operationally expected. Define a support lifecycle at launch: how long v1 is maintained after v2 ships, what SLA applies to each version, and when v1 enters maintenance-only mode. Stripe supports each API version indefinitely; GitHub runs two major versions concurrently; Twilio documents explicit sunset dates per version.
+
+4. **Version routing at the gateway** — URL versioning enables path-based routing at the API gateway, load balancer, or reverse proxy without any header inspection. A single nginx rule `location /v2/` routes to the v2 cluster. This simplicity is a primary reason URL versioning dominates public API design despite REST purists preferring header-based negotiation.
+
+5. **Migration timeline patterns** — Announce v2 at least 6 months before deprecating v1 for external consumers. Publish a migration guide listing every breaking change with before/after examples. Emit `Deprecation` and `Sunset` headers on v1 responses (see api-deprecation-strategy) so tooling can surface warnings automatically. Provide a changelog entry for each version at a stable URL (`/v1/changelog`).
+
+6. **Semantic versioning alignment** — URL versions align with semver's major version number. `/v1/` corresponds to semver `1.x.x`; `/v2/` to `2.x.x`. Minor increments (1.1, 1.2) are expressed through response body evolution (new optional fields, new endpoints) and documented in changelogs — never through new URL segments.
+
+### Worked Example
+
+Stripe's API is the canonical example of production URL versioning at scale. The base URL embeds the major version:
+
+**v1 request — list customers:**
+
+```http
+GET /v1/customers?limit=10
+Authorization: Bearer sk_example_...
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "object": "list",
+  "data": [ ... ],
+  "has_more": true,
+  "url": "/v1/customers"
+}
+```
+
+**Stripe's versioning model adds a second dimension:** request-date versioning via the `Stripe-Version` header, but the URL path `/v1/` remains fixed across all Stripe versions. This shows that URL versioning and header versioning are not mutually exclusive — the URL anchors the major API generation while the header gates fine-grained behavioral changes.
+
+**GitHub API URL versioning (REST v3 → REST API):**
+
+```http
+GET /v3/repos/octocat/Hello-World
+Accept: application/vnd.github.v3+json
+Authorization: Bearer ghp_...
+```
+
+GitHub migrated from `/v3/` implicit to the explicit REST API base. Their migration guide published all endpoint path changes with redirects from old paths, enabling clients to migrate incrementally.
+
+**Twilio API versioning:**
+
+```http
+POST /2010-04-01/Accounts/{AccountSid}/Messages
+Authorization: Basic ...
+Content-Type: application/x-www-form-urlencoded
+```
+
+Twilio uses a date-based URL version (`2010-04-01`) rather than an integer, which conveys stability and timestamp semantics — useful when the API is updated infrequently and date-anchored releases carry meaning for audit and compliance consumers.
+
+### Anti-Patterns
+
+1. **Versioning every minor change.** Creating `/v1/`, `/v2/`, `/v3/` for each additive field addition or new endpoint signals poor discipline and forces consumers into unnecessary migration work. URL versions should be rare, significant, and announce breaking changes. If you are on `/v7/` after two years, your versioning granularity is wrong.
+
+2. **Embedding version mid-path.** `GET /users/v2/profile` creates per-resource versioning that makes routing tables explode and makes it impossible to version the entire API coherently. Clients cannot construct a base URL for "the v2 API" — they must track per-resource versions. Always version at the root segment.
+
+3. **Silently breaking v1 during v2 development.** Running v1 and v2 from the same codebase with feature flags that silently alter v1 behavior is a contract violation. Version boundaries must be hard: a request to `/v1/` must behave identically to its original contract regardless of v2 development activity. Use separate deployments or strict branch-by-abstraction patterns.
+
+4. **No sunset timeline at launch.** Shipping v2 without announcing when v1 will be retired leaves consumers in limbo. They cannot prioritize migration work without a date. Publish a deprecation schedule with v2's launch, even if it is tentative.
+
+## Details
+
+### URI Pollution and the REST Purity Debate
+
+Strict REST theorists argue that versioning in the URI violates the principle that a URI identifies a resource, not a resource-at-a-point-in-time. Under this view, `/v1/users/42` and `/v2/users/42` are two different resources, but they represent the same underlying entity. The counter-argument from pragmatists (and most API teams): URI pollution is a minor aesthetic cost worth paying for the operational benefits of path-based routing, browser history clarity, and copy-pasteable URLs that are immediately interpretable by developers. The REST purity argument is correct in theory; URL versioning wins in practice for public APIs.
+
+### CDN and Caching Benefits
+
+URL versioning enables aggressive CDN caching by version prefix. A CDN rule can cache all `/v1/` responses with a long TTL while purging only `/v2/` on rollout. Header-versioned APIs require `Vary: Accept` or `Vary: API-Version` headers, which most CDNs handle poorly — resulting in cache fragmentation or disabled caching entirely. For read-heavy public APIs, this is a meaningful performance argument for URL versioning.
+
+### Real-World Case Study: Stripe Version Stability
+
+Stripe has maintained `/v1/` as its URL prefix since 2011 — over a decade — while making hundreds of breaking changes via their date-based `Stripe-Version` header. Their approach treats the URL prefix as the API generation (REST API vs. a hypothetical v2 with a fundamentally different paradigm) and the header as the fine-grained version. This two-tier model has allowed Stripe to serve customers using 2012-era API versions alongside customers using today's version from the same `/v1/` base path. The result: zero forced migration events for existing integrations, and a developer reputation that directly contributes to adoption. By contrast, Twilio has sunset multiple URL versions, requiring migration guides and support overhead that Stripe has avoided.
+
+## Source
+
+- [Stripe API Versioning](https://stripe.com/blog/api-versioning)
+- [GitHub REST API Versioning](https://docs.github.com/en/rest/overview/api-versions)
+- [Twilio API Versioning](https://www.twilio.com/docs/usage/api/api-versioning)
+- [APIs You Won't Hate — API Versioning Has No "Right Way"](https://apisyouwonthate.com/blog/api-versioning-has-no-right-way)
+- [Microsoft REST API Guidelines — Versioning](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#versioning)
+
+## Process
+
+1. Decide major-only URL versioning at the root path segment before any endpoint design begins; document this as a team standard.
+2. Define the version support lifecycle: simultaneous version count limit, maintenance-only window duration, and sunset timeline policy.
+3. At v2 launch, add `Deprecation` and `Sunset` response headers to all v1 endpoints pointing to the migration guide URL.
+4. Publish a breaking-change migration guide at a stable URL (`/changelog` or `/migration/v1-to-v2`) with before/after examples for every changed endpoint.
+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-versioning-header, api-backward-compatibility, api-deprecation-strategy, api-rest-maturity-model
+
+## Success Criteria
+
+- All API endpoints under a major version share a single URL prefix (e.g., `/v1/`) with no per-resource version segments.
+- URL version increments occur only on breaking changes; additive changes are deployed without a new version prefix.
+- A deprecation timeline is published simultaneously with any new major version launch.
+- v1 and v2 responses are independently routable at the gateway or reverse-proxy layer without header inspection.
+- A migration guide with before/after examples exists for every breaking change between versions.

package/dist/agents/skills/gemini-cli/api-versioning-url/skill.yaml

@@ -0,0 +1,39 @@
+name: api-versioning-url
+version: '1.0.0'
+description: URL path versioning (/v1/, /v2/) — when to use, URI pollution tradeoffs, major-only vs minor versioning, migration timeline patterns
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-versioning-header
+  - api-backward-compatibility
+  - api-deprecation-strategy
+  - api-rest-maturity-model
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - url-versioning
+  - path-versioning
+  - v1
+  - major-version
+  - semantic-versioning
+  - version-prefix
+metadata:
+  author: community
+  upstream: stripe.com/blog/api-versioning
+state:
+  persistent: false
+  files: []
+depends_on: []