@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/cursor/api-resource-granularity/SKILL.md

@@ -0,0 +1,165 @@
+# Resource Granularity
+
+> Resource granularity determines how much data a single API resource exposes. Fine-grained resources are flexible but chatty; coarse-grained resources reduce round trips but over-fetch. The right granularity matches your clients' actual access patterns.
+
+## When to Use
+
+- Designing a new API and deciding how to scope each resource
+- Investigating mobile client performance issues caused by too many round trips (under-fetching)
+- Debugging slow API responses caused by returning too much data (over-fetching)
+- Evaluating whether to introduce a composite endpoint for a specific client use case
+- Reviewing a PR that adds an endpoint returning deeply nested objects
+- Deciding whether field selection (`?fields=`) is worth the complexity
+
+## Instructions
+
+### Key Concepts
+
+**Fine-grained resources** expose one concept per endpoint. Clients compose the data they need from multiple requests.
+
+```
+GET /users/42          → { id, name, email }
+GET /users/42/address  → { street, city, zip }
+GET /users/42/orders   → [ ... ]
+```
+
+**Coarse-grained resources** bundle related data into one response. Clients get more than they asked for, but in fewer round trips.
+
+```
+GET /users/42?include=address,recent-orders
+→ { id, name, email, address: {...}, recentOrders: [...] }
+```
+
+**The tradeoff:**
+
+| Dimension         | Fine-grained                           | Coarse-grained                     |
+| ----------------- | -------------------------------------- | ---------------------------------- |
+| Round trips       | Many (N+1 risk)                        | Few                                |
+| Response size     | Small                                  | Large                              |
+| Cache granularity | High (each resource cached separately) | Low (bundle invalidated as a unit) |
+| Evolvability      | Easy (change one resource)             | Harder (bundle evolves as a whole) |
+| Client fit        | Generic clients                        | Specific client use cases          |
+
+**Aggregation patterns:**
+
+1. **Composite resource.** A dedicated URL bundles related data for a common client need.
+
+   ```
+   GET /dashboard/user/42  → user + account summary + recent activity
+   ```
+
+   Suitable when a single client (e.g., mobile home screen) has a fixed, known data requirement.
+
+2. **Include/expand parameter.** The base resource optionally embeds related data.
+
+   ```
+   GET /orders/42?expand=customer,items
+   ```
+
+   Used by Stripe (`?expand[]=customer`) to let callers control depth without separate calls.
+
+3. **Field selection.** Sparse fieldsets reduce payload size without changing resource boundaries.
+   ```
+   GET /users/42?fields=id,name,email
+   ```
+   See `api-field-selection` for implementation detail.
+
+### Worked Example
+
+A mobile app displays a feed of posts. Each post needs author name, avatar, post text, and like count.
+
+**Fine-grained (chatty):**
+
+```
+GET /feed                   → [{ postId: 1 }, { postId: 2 }, ...]
+GET /posts/1                → { text, authorId, likeCount }
+GET /users/{authorId}       → { name, avatarUrl }
+... (repeated for each post)
+```
+
+On a feed of 20 posts, this is 41 requests. Mobile latency makes this unusable.
+
+**Coarse-grained (aggregated feed resource):**
+
+```
+GET /feed?limit=20
+→ {
+    items: [
+      {
+        post: { id: 1, text: "...", likeCount: 142 },
+        author: { id: 7, name: "Alice", avatarUrl: "..." }
+      },
+      ...
+    ],
+    nextCursor: "eyJpZCI6MjB9"
+  }
+```
+
+One request returns everything the client needs. The server joins the data efficiently; the client does not need multiple round trips.
+
+**Targeted aggregation, not wholesale bundling:**
+
+The feed resource is coarse-grained by design for its specific client. The `/posts/1` and `/users/7` endpoints remain fine-grained for other callers. Do not coarsen your entire API — create targeted aggregations for specific, well-understood access patterns.
+
+### Anti-Patterns
+
+1. **The "kitchen sink" resource.** `GET /users/42` returning profile, address, orders, invoices, activity log, and preferences in one response serves no client well — it over-fetches for every one of them. Build aggregations for specific use cases, not all-purpose mega-resources.
+
+2. **Fine-grained resources without any aggregation option.** A pure fine-grained API forces mobile clients into N+1 request chains. Always provide an aggregation path for your highest-traffic client workflows.
+
+3. **Aggregating data that changes on different cadences.** If user profile rarely changes but order list changes constantly, bundling them together destroys cache effectiveness. The bundle invalidates whenever either part changes. Keep fast-changing and slow-changing data in separate cacheable resources.
+
+4. **Using granularity to hide schema complexity.** If a coarse-grained endpoint returns a deeply nested structure with 30+ fields, the problem is schema complexity, not granularity. See `api-field-selection` to let callers request only what they need.
+
+## Details
+
+### The N+1 Problem in REST
+
+The N+1 problem originates in ORM query patterns (`db-n-plus-one-queries`) but manifests identically in REST APIs. A list endpoint returns N items; each item requires a separate request for related data — N+1 total requests.
+
+Mitigation strategies:
+
+- **Embed related data** in the collection response (`?expand=author`)
+- **Composite resource** that pre-joins the common access pattern
+- **Batch endpoint** that accepts multiple IDs: `GET /users?ids=1,2,3,7,9`
+
+### Stripe's Expand Pattern
+
+Stripe's API lets callers control expansion depth at request time:
+
+```
+GET /v1/charges/ch_abc?expand[]=customer&expand[]=payment_intent
+```
+
+The response embeds the full customer and payment intent objects instead of returning just their IDs. This balances fine-grained defaults with coarse-grained convenience, without requiring dedicated composite endpoints for every use case.
+
+### Real-World Case Study: Mobile App Optimization
+
+A travel booking app's hotel detail screen made 7 API calls on load: hotel info, photos, room types, availability, reviews, nearby attractions, and a policy summary. P95 load time was 4.2 seconds on 4G. The team introduced `GET /hotels/{id}/detail-bundle` — a server-side join returning all 7 data sets in one response. P95 dropped to 0.8 seconds. The individual endpoints remained unchanged for other clients. The bundle is cache-keyed on the hotel ID with a 5-minute TTL; the slower-changing policy and photos data accepts stale serving.
+
+## Source
+
+- Allamaraju, S. "RESTful Web Services Cookbook" O'Reilly (2010)
+- [Stripe API Expanding Responses](https://stripe.com/docs/api/expanding_objects)
+- [Microsoft REST API Guidelines — Composite Resources](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md)
+
+## Process
+
+1. List your API's top 3-5 client workflows (e.g., home screen load, order detail page, admin dashboard). Identify the data each workflow needs.
+2. Check for N+1 patterns: does the workflow require a list endpoint followed by per-item requests? If so, introduce an aggregation (composite resource, expand parameter, or batch endpoint).
+3. Audit existing coarse-grained endpoints for over-fetching: if most callers only use a subset of the response, add field selection or split the resource.
+4. Ensure slow-changing and fast-changing data are in separate cacheable resources; do not bundle them.
+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-resource-modeling, api-field-selection, api-nested-vs-flat, api-pagination-cursor
+
+## Success Criteria
+
+- High-traffic client workflows avoid N+1 request chains through aggregation, expand parameters, or batch endpoints.
+- Coarse-grained aggregations are purpose-built for specific use cases, not all-purpose mega-resources.
+- Fast-changing and slow-changing data are in separate cacheable resources.
+- Field selection (`?fields=`) or expand parameters are available on high-traffic list endpoints to control response size.

package/dist/agents/skills/cursor/api-resource-granularity/skill.yaml

@@ -0,0 +1,40 @@
+name: api-resource-granularity
+version: '1.0.0'
+description: Fine-grained vs coarse-grained resource design -- aggregation patterns and over-fetching tradeoffs
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-resource-modeling
+  - api-field-selection
+  - api-nested-vs-flat
+  - api-pagination-cursor
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - resource-granularity
+  - coarse-grained
+  - fine-grained
+  - aggregation
+  - over-fetching
+  - under-fetching
+  - composite-resource
+metadata:
+  author: community
+  upstream: stripe.com/docs/api/expanding_objects
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/api-resource-modeling/SKILL.md

@@ -0,0 +1,155 @@
+# Resource Modeling
+
+> REST APIs are organized around resources — nouns that represent things, not verbs that represent actions. Well-modeled resources produce URLs that are predictable, cacheable, and easy to understand without documentation.
+
+## When to Use
+
+- Designing a new API surface from scratch
+- Reviewing a PR that introduces new endpoints
+- Refactoring an RPC-style API toward resource orientation
+- Deciding how to expose a domain concept (user, order, invoice) via HTTP
+- Naming a URL for an operation that does not map cleanly to CRUD
+- Explaining to a team why `/getUsers` violates REST conventions
+
+## Instructions
+
+### Key Concepts
+
+**Resources are nouns, not verbs.** The HTTP method provides the verb. The URL identifies the thing being acted upon.
+
+| Wrong (verb in URL)     | Right (noun + method)           |
+| ----------------------- | ------------------------------- |
+| `POST /createUser`      | `POST /users`                   |
+| `GET /getOrder/42`      | `GET /orders/42`                |
+| `POST /deleteProduct/7` | `DELETE /products/7`            |
+| `POST /activateAccount` | `POST /accounts/42/activations` |
+
+**Resource identification rules:**
+
+1. **Use plural nouns for collections.** `/users` (collection), `/users/42` (member).
+2. **Use lowercase with hyphens, not camelCase or underscores.** `/order-items`, not `/orderItems` or `/order_items`. Hyphens are more readable in URLs and treated as word separators by search engines.
+3. **Do not include file extensions.** Use `Accept` headers for content negotiation, not `/users.json`.
+4. **Keep URLs stable.** Once published, changing a URL is a breaking change. Design carefully.
+
+**Mapping domain actions to resources:**
+
+Some operations resist simple noun mapping. Common strategies:
+
+| Domain Action       | Resource Strategy                    | Example                                 |
+| ------------------- | ------------------------------------ | --------------------------------------- |
+| Send a message      | Create a message resource            | `POST /messages`                        |
+| Activate an account | Create a sub-resource for the state  | `POST /accounts/42/activations`         |
+| Run a report        | Create a report resource             | `POST /reports` → `GET /reports/r99`    |
+| Search              | Use query parameters on a collection | `GET /products?q=widget&category=tools` |
+| Merge two records   | Model the merge as a resource        | `POST /record-merges`                   |
+
+The key insight: if you need to perform an action, model the _result_ of that action as a resource. An activation is not a verb — it is a resource whose existence represents the activated state.
+
+### Worked Example
+
+An e-commerce platform is adding order management endpoints. The team debates the URL structure:
+
+**Draft 1 (verb-centric):**
+
+```
+POST   /createOrder
+GET    /getOrder?id=42
+POST   /cancelOrder
+POST   /shipOrder
+GET    /listOrdersByCustomer?customerId=7
+```
+
+**Draft 2 (resource-centric, Level 2):**
+
+```
+POST   /orders                          → 201 Created, Location: /orders/42
+GET    /orders/42                       → 200 OK
+POST   /orders/42/cancellations        → 201 Created (models the cancellation event)
+POST   /orders/42/shipments            → 201 Created, Location: /orders/42/shipments/s1
+GET    /customers/7/orders             → 200 OK, paginated list
+```
+
+Draft 2 advantages:
+
+- `GET /orders/42` is cacheable. `GET /getOrder?id=42` may not be (depends on the proxy, but query-only GETs are less reliably cached).
+- Cancellation is modeled as a resource — you can later `GET /orders/42/cancellations` to audit who cancelled and why.
+- Shipment is a first-class resource — you can track it, update it, and link to it.
+
+**Handling non-CRUD actions — account verification:**
+
+A user clicks an email verification link. The action is "verify the email."
+
+Bad: `GET /verifyEmail?token=abc123` (side-effecting GET)
+Bad: `POST /verifyEmail` (verb URL)
+Good: `POST /email-verifications` with `{ "token": "abc123" }` — creates a verification record and triggers the state change as a side effect.
+
+Or if you must use a GET (for email link clicking convenience): acknowledge it violates GET safety and document it explicitly. This is a pragmatic exception, not a design template.
+
+### Anti-Patterns
+
+1. **Verbs in URIs.** `/api/v1/getUserProfile`, `/api/v1/updatePassword`, `/api/v1/deleteAccount` are RPC routes dressed as REST. Replace with `GET /users/42/profile`, `PUT /users/42/password`, `DELETE /users/42`.
+
+2. **Inconsistent plurality.** Mixing `/user/42` and `/orders` in the same API forces clients to memorize which resources are singular. Use plural everywhere.
+
+3. **Implementation details in URLs.** `/database/users/42` or `/v2/mysql/orders` leaks infrastructure. URLs should model the domain, not the implementation.
+
+4. **Using query parameters for resource identity.** `/orders?id=42` is a filter, not a resource address. The canonical address of an order is `/orders/42`. Query parameters are for filtering collections, not identifying members.
+
+5. **Deep nesting beyond two levels.** `/users/42/orders/7/items/3/variants/red` is brittle and hard to cache. See `api-nested-vs-flat` for when to flatten.
+
+## Details
+
+### Controller Resources (the Pragmatic Exception)
+
+Some actions genuinely cannot be modeled as nouns. REST literature calls these "controller resources" — they expose a procedural concept as a resource.
+
+Common examples:
+
+- `POST /emails/42/send` — sends a draft email (the sending is the event)
+- `POST /transactions/42/void` — voids a transaction (irreversible state transition)
+- `POST /search` — complex search with a body payload too large for a query string
+
+These are acceptable when the action has no natural noun form. Document them clearly in your OpenAPI spec with a note explaining why a controller pattern was chosen. See `api-openapi-design` for spec conventions.
+
+### Resource Naming in Practice: GitHub API
+
+GitHub's API (`api.github.com`) demonstrates resource modeling at scale:
+
+```
+GET  /repos/{owner}/{repo}           — repository resource
+GET  /repos/{owner}/{repo}/issues    — issues collection
+POST /repos/{owner}/{repo}/issues    — create issue
+GET  /repos/{owner}/{repo}/issues/42 — single issue
+POST /repos/{owner}/{repo}/issues/42/comments — comment on issue
+POST /repos/{owner}/{repo}/merges    — merge (controller resource)
+```
+
+Note that `/merges` is a controller resource — it creates the result of a merge operation. GitHub chose this over `POST /repos/{owner}/{repo}/pulls/7/merge` (which they also support) to make the action explicit.
+
+## Source
+
+- [REST API Tutorial — Resource Naming](https://restfulapi.net/resource-naming/)
+- Allamaraju, S. "RESTful Web Services Cookbook" O'Reilly (2010)
+- Masse, M. "REST API Design Rulebook" O'Reilly (2011)
+- [RFC 3986 — Uniform Resource Identifier](https://www.rfc-editor.org/rfc/rfc3986)
+
+## Process
+
+1. List the domain concepts your API exposes. Each concept is a candidate resource.
+2. Name each resource as a plural noun. Map create/read/update/delete to POST/GET/PUT or PATCH/DELETE.
+3. For actions that resist noun mapping, model the _result_ of the action as a sub-resource or controller resource.
+4. Validate URI structure: lowercase, hyphens, no verbs, no file extensions, no implementation details.
+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-resource-granularity, api-nested-vs-flat, api-rest-maturity-model, api-http-methods, api-filtering-sorting
+
+## Success Criteria
+
+- All URLs use plural nouns; no verbs appear in URI paths (controller resources are the documented exception).
+- Collections and members follow the pattern: `/resources` (collection), `/resources/{id}` (member).
+- Domain actions that cannot map to CRUD are modeled as sub-resources or controller resources, not verb URLs.
+- URI conventions are consistent across the entire API surface: lowercase, hyphen-separated, no file extensions.

package/dist/agents/skills/cursor/api-resource-modeling/skill.yaml

@@ -0,0 +1,40 @@
+name: api-resource-modeling
+version: '1.0.0'
+description: Nouns vs verbs in URI design, resource identification, and URL structure for REST APIs
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-resource-granularity
+  - api-nested-vs-flat
+  - api-rest-maturity-model
+  - api-http-methods
+  - api-filtering-sorting
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - resource-modeling
+  - URI-design
+  - nouns-vs-verbs
+  - resource-identification
+  - URL-structure
+  - REST
+metadata:
+  author: community
+  upstream: restfulapi.net/resource-naming
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/api-rest-maturity-model/SKILL.md

@@ -0,0 +1,215 @@
+# Richardson Maturity Model
+
+> The Richardson Maturity Model grades REST APIs on a four-level scale — from RPC-over-HTTP tunneling (Level 0) to full hypermedia controls (Level 3). Each level adds constraints that improve discoverability, cacheability, and client-server decoupling.
+
+## When to Use
+
+- Evaluating an existing API's design maturity before a major revision
+- Deciding how far to take REST constraints on a new project
+- Explaining to stakeholders why "JSON over POST" is not REST
+- Reviewing a PR that adds a new resource endpoint
+- Onboarding engineers to REST principles beyond CRUD
+- Choosing between resource-oriented and action-oriented URL design
+
+## Instructions
+
+### Key Concepts
+
+The model, described by Leonard Richardson and popularized by Martin Fowler, defines four levels:
+
+| Level | Name                | Characteristic                                    |
+| ----- | ------------------- | ------------------------------------------------- |
+| 0     | The Swamp of POX    | Single endpoint, HTTP as transport tunnel         |
+| 1     | Resources           | Separate URLs per resource                        |
+| 2     | HTTP Verbs          | Correct method semantics (GET, POST, PUT, DELETE) |
+| 3     | Hypermedia Controls | Responses include links to available next actions |
+
+Each level is strictly additive — Level 2 requires Level 1, Level 3 requires Level 2.
+
+**Level 0 — The Swamp of POX (Plain Old XML/JSON)**
+
+A single endpoint handles all operations. The HTTP method is irrelevant; the payload specifies the action.
+
+```http
+POST /api
+Content-Type: application/json
+
+{ "action": "getUser", "userId": 42 }
+```
+
+```http
+POST /api
+Content-Type: application/json
+
+{ "action": "deleteUser", "userId": 42 }
+```
+
+This is RPC tunneled over HTTP. There is no distinction between safe and unsafe operations. Caching is impossible (all POST). Errors arrive as `200 OK` with an error payload.
+
+**Level 1 — Resources**
+
+Each resource gets its own URL. Operations are still passed in the request body, but clients can now bookmark and reason about individual resources.
+
+```http
+POST /users/42
+Content-Type: application/json
+
+{ "action": "get" }
+```
+
+Improvement: resource identity is in the URL. Still not exploiting HTTP method semantics.
+
+**Level 2 — HTTP Verbs**
+
+This is the practical REST target for most production APIs. HTTP methods carry semantic meaning, and status codes communicate outcomes.
+
+```http
+GET /users/42
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{ "id": 42, "name": "Alice", "email": "alice@example.com" }
+```
+
+```http
+DELETE /users/42
+```
+
+```http
+HTTP/1.1 204 No Content
+```
+
+```http
+POST /users
+Content-Type: application/json
+
+{ "name": "Bob", "email": "bob@example.com" }
+```
+
+```http
+HTTP/1.1 201 Created
+Location: /users/43
+```
+
+GET is safe (no side effects) and idempotent. DELETE is idempotent. POST creates a new resource and returns `201 Created` with a `Location` header. Errors use 4xx/5xx status codes — not `{ "status": "error" }` in a 200 body.
+
+### Worked Example
+
+A medical appointment booking API at each level:
+
+**Level 0:**
+
+```http
+POST /appointmentService
+{ "action": "bookAppointment", "date": "2024-03-15", "doctorId": "d7" }
+
+POST /appointmentService
+{ "action": "cancelAppointment", "appointmentId": "a42" }
+```
+
+**Level 1:**
+
+```http
+POST /doctors/d7/appointments
+{ "action": "book", "date": "2024-03-15" }
+
+POST /appointments/a42
+{ "action": "cancel" }
+```
+
+**Level 2:**
+
+```http
+POST /doctors/d7/appointments
+Content-Type: application/json
+{ "date": "2024-03-15", "patientId": "p99" }
+→ 201 Created, Location: /appointments/a43
+
+DELETE /appointments/a42
+→ 204 No Content
+```
+
+**Level 3:**
+
+```json
+GET /appointments/a43
+→ 200 OK
+{
+  "id": "a43",
+  "date": "2024-03-15",
+  "status": "confirmed",
+  "_links": {
+    "self": { "href": "/appointments/a43" },
+    "cancel": { "href": "/appointments/a43", "method": "DELETE" },
+    "reschedule": { "href": "/appointments/a43/reschedule", "method": "POST" },
+    "doctor": { "href": "/doctors/d7" }
+  }
+}
+```
+
+The Level 3 response tells the client what actions are available without out-of-band documentation. A client following the links never needs to construct URLs manually.
+
+### Anti-Patterns
+
+1. **Claiming Level 2 while returning errors in 200 bodies.** `{ "error": true, "message": "Not found" }` with status `200 OK` is a Level 0 behavior regardless of URL structure. Use 404 with a problem details body. See `api-status-codes` and `api-error-contracts`.
+
+2. **Skipping Level 2 to chase Level 3.** Teams sometimes invest in hypermedia before establishing correct HTTP semantics. The return on Level 2 (cacheability, safe methods, standard tooling) is far larger than Level 3 for most APIs. Level 3 adds cost — implement it only when clients demonstrably benefit from link-driven navigation.
+
+3. **Verbs in URLs at Level 2.** `/users/42/delete` is Level 1 behavior with a Level 2 URL structure. The method already carries the verb: `DELETE /users/42`.
+
+4. **Treating the model as a score to maximize.** Most production APIs should target Level 2. Level 3 has genuine cost (response size, client complexity, cache invalidation) and genuine benefit (evolvability, discoverability) — the benefit must justify the cost for your specific API.
+
+## Details
+
+### Why Level 2 Is the Right Default
+
+The majority of public APIs — Stripe, GitHub, Twilio — operate at Level 2. Level 2 unlocks:
+
+- **Caching:** GET responses are cacheable by default. POST/PUT/DELETE are not. CDNs and browsers use this.
+- **Idempotency:** DELETE and PUT are idempotent — retrying on network failure is safe.
+- **Tooling:** OpenAPI, Postman, curl, and every HTTP client understand method semantics.
+- **Observability:** Log analysis and rate limiting by method is trivial at Level 2.
+
+### When Level 3 Is Worth It
+
+Hypermedia controls pay off when:
+
+- The set of valid next actions depends on server-side state (workflows, state machines)
+- Clients are long-lived and must tolerate URL changes without redeployment
+- You are building a public API with many third-party integrators and need evolvability
+
+GitHub's API returns `_links` on pull requests pointing to merge, review, and comment endpoints. The client discovers available actions from the response rather than hardcoding URLs.
+
+### Real-World Case Study: Internal RPC Masquerading as REST
+
+A fintech platform built an "API" with a single `/execute` endpoint accepting `{ "command": "transferFunds", ... }`. Every call was a POST. Every response was `200 OK` (including failures). Logging could not distinguish reads from writes. A CDN sat in front and cached nothing. Migrating to Level 2 — separate resource URLs, correct methods, proper status codes — reduced error detection time from minutes (polling logs) to milliseconds (5xx alerts), and CDN hit rate increased from 0% to 61% by making GET /accounts/:id cacheable.
+
+## Source
+
+- [Martin Fowler — Richardson Maturity Model](https://martinfowler.com/articles/richardsonMaturityModel.html)
+- Richardson, L. & Ruby, S. "RESTful Web Services" O'Reilly (2007)
+- Fielding, R.T. "Architectural Styles and the Design of Network-based Software Architectures" (2000)
+- [RFC 9110 — HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110)
+
+## Process
+
+1. Identify the current maturity level of your API: single endpoint (0), multiple URLs (1), correct HTTP verbs and status codes (2), hypermedia links (3).
+2. If at Level 0 or 1, migrate to Level 2: assign each resource a dedicated URL, map actions to HTTP methods, and replace error-in-200 patterns with 4xx/5xx responses.
+3. Evaluate whether Level 3 is justified: if client navigation depends on server state or URL stability is a maintenance burden, add `_links` to responses following the HAL or JSON:API conventions.
+4. 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-hateoas, api-resource-modeling, api-http-methods, api-status-codes
+
+## Success Criteria
+
+- The API uses separate URLs per resource (Level 1 minimum).
+- HTTP methods carry correct semantics: GET is safe, DELETE and PUT are idempotent, POST creates (Level 2).
+- Error conditions return appropriate 4xx/5xx status codes, not `200 OK` with an error payload.
+- Level 3 hypermedia controls are adopted only when client navigation depends on server-side state or URL evolvability is a documented requirement.

package/dist/agents/skills/cursor/api-rest-maturity-model/skill.yaml

@@ -0,0 +1,39 @@
+name: api-rest-maturity-model
+version: '1.0.0'
+description: Richardson Maturity Model levels 0-3 -- evaluating and advancing REST API design maturity
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-hateoas
+  - api-resource-modeling
+  - api-http-methods
+  - api-status-codes
+stack_signals:
+  - rest
+  - api
+  - http
+keywords:
+  - richardson-maturity-model
+  - REST
+  - maturity-levels
+  - hypermedia
+  - HTTP-verbs
+  - resource-oriented
+metadata:
+  author: community
+  upstream: martinfowler.com/articles/richardsonMaturityModel.html
+state:
+  persistent: false
+  files: []
+depends_on: []