[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6NPTBZW201WAV67HN2EEERB":3,"skill-same:01M6NPTBZW201WAV67HN2EEERB":103},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":34,"publishedAt":54,"linkOnly":55,"markdownContent":56,"markdownBody":57,"frontMatter":58,"refName":67,"commitSha":68,"skillDirectory":69,"forksCount":14,"repositoryHtmlUrl":70,"repositoryHomepageUrl":71,"ownerHtmlUrl":72,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":73,"install":74,"resources":87},"01M6NPTBZW201WAV67HN2EEERB","api-design",null,"REST API design — resource naming, HTTP methods, status codes, pagination, versioning, OpenAPI. Use when designing a new REST API, reviewing API contracts, writing OpenAPI\u002FSwagger documentation, or choosing pagination, versioning, or error-format strategies.","projectious-work\u002Fprocesskit","projectious-work","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F263889726?v=4","01M6N97TJJ118WQ35CHRV8RD0E","projectious.work","01M6N97TPWJPF0BMKYQ4PBY5W8",0,"MIT","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fengineering\u002Fapi-design\u002FSKILL.md",[18,23,26,31],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",{"categoryNo":32,"categoryName":33,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000032","设计师",[35,36,37,38,39,40,5,41,42,43,44,45,46,47,48,49,50,51,52,53],"api design","api","design","use","api contracts","rest api design","naming","codes","error","rest api","strategies","methods","work","versioning","openapi","REST","http","documentation","writing","2026-11-10 10:12:30",false,"---\nname: api-design\ndescription: |\n  REST API design — resource naming, HTTP methods, status codes, pagination, versioning, OpenAPI. Use when designing a new REST API, reviewing API contracts, writing OpenAPI\u002FSwagger documentation, or choosing pagination, versioning, or error-format strategies.\nmetadata:\n  processkit:\n    apiVersion: processkit.projectious.work\u002Fv2\n    id: SKILL-api-design\n    version: \"1.1.0\"\n    created: 2026-04-06T00:00:00Z\n    category: engineering\n---\n\n# API Design\n\n## Intro\n\nREST APIs follow well-established conventions: plural-noun resources,\nHTTP methods that match their semantics, correct status codes, cursor\npagination, URI versioning, and a consistent error envelope. Document\nthe contract in OpenAPI 3.1 with reusable components.\n\n## Overview\n\n### Resource naming\n\nUse plural nouns for collections (`\u002Fusers`, `\u002Forders`). Nest\nsub-resources to express ownership (`\u002Fusers\u002F{id}\u002Forders`) but cap\nnesting at three levels — go flat once the relationship is clear.\nAvoid verbs in URIs; the HTTP method is the verb. Use kebab-case for\nmulti-word segments (`\u002Fline-items`), lowercase only, no trailing\nslash, no file extensions.\n\nWhen CRUD doesn't fit, model the action as a sub-resource POST:\n`POST \u002Fv1\u002Forders\u002F{id}\u002Fcancel`, `POST \u002Fv1\u002Fusers\u002F{id}\u002Fverify-email`.\n\n### HTTP methods and status codes\n\nMap operations to methods consistently and return the right success\ncode:\n\n| Operation | Method | Success | Notes                  |\n|-----------|--------|---------|------------------------|\n| List      | GET    | 200     | Collection endpoint    |\n| Read      | GET    | 200     | Single resource        |\n| Create    | POST   | 201     | Return Location header |\n| Replace   | PUT    | 200     | Full replacement       |\n| Patch     | PATCH  | 200     | Partial update         |\n| Delete    | DELETE | 204     | No body                |\n\nGET is safe and idempotent. PUT and DELETE are idempotent. Never\nreturn 200 with an error payload — use the right 4xx\u002F5xx code.\n\n### Pagination\n\nDefault to **cursor-based** pagination. It is correct under concurrent\nwrites, scales to large datasets, and is what every serious API uses.\nReserve offset-based pagination for small, stable datasets where users\nneed to jump to page N.\n\n```json\n{\n  \"data\": [...],\n  \"pagination\": {\n    \"next_cursor\": \"abc123\",\n    \"has_more\": true\n  }\n}\n```\n\nCursors are opaque (base64-encoded). Clients must not parse them.\n\n### Filtering, sorting, versioning\n\n- Filter via query params: `GET \u002Forders?status=shipped&created_after=2025-01-01`.\n- Sort with `sort=`, prefix with `-` for descending: `?sort=-created_at,name`.\n- Version in the URI path for public APIs (`\u002Fv1\u002Fusers`). Use the\n  `Accept` header for internal APIs that need URL stability.\n- Within a version, only additive changes — never break clients.\n\n### Error responses\n\nUse one error envelope across every endpoint:\n\n```json\n{\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"Email is required.\",\n    \"details\": [\n      { \"field\": \"email\", \"reason\": \"required\" }\n    ],\n    \"request_id\": \"req_abc123\"\n  }\n}\n```\n\n`code` is machine-readable; `message` is human-readable; `details`\nholds per-field errors; `request_id` makes support tickets debuggable.\n\n### Rate limiting\n\nReturn rate-limit headers on every response, not just 429s:\n\n```\nX-RateLimit-Limit: 1000\nX-RateLimit-Remaining: 742\nX-RateLimit-Reset: 1672531200\n```\n\nReturn 429 Too Many Requests when the limit is exceeded.\n\n### OpenAPI 3.1\n\nDocument the API in OpenAPI 3.1. Extract shared schemas, parameters,\nand responses into `components\u002F` and `$ref` them everywhere. Define\nsecurity schemes globally with per-endpoint overrides for public\nroutes. See `references\u002Fopenapi-patterns.md` for the full skeleton\nincluding reusable parameters, responses, and security schemes.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Verbs in resource URIs.** `POST \u002FcreateOrder` or `GET \u002FgetUserById` bakes the HTTP method into the path, making the URL semantically redundant and breaking the REST constraint that the method alone describes the action. Use noun resources: `POST \u002Forders`, `GET \u002Fusers\u002F{id}`. When CRUD doesn't fit, model the action as a sub-resource: `POST \u002Forders\u002F{id}\u002Fcancel`.\n- **Unpaginated list endpoints shipped as \"we'll add it later.\"** A list endpoint that returns all records works fine in development with 50 records and fails spectacularly in production with 50,000. Pagination cannot be added to a stable API without a breaking change to the response shape. Every list endpoint must paginate from day one, with a default page size that makes the system safe.\n- **200 OK with an error payload.** Returning `{\"error\": \"not found\"}` with HTTP 200 means clients cannot use HTTP status codes to distinguish success from failure — they must parse every response body. Return 4xx or 5xx status codes that match the actual error so clients, proxies, monitoring systems, and retry logic all work correctly.\n- **Inconsistent error envelopes across endpoints.** Some endpoints return `{\"error\": \"...\"}`, others return `{\"message\": \"...\"}`, others return `{\"errors\": [...]}`. Clients must special-case every endpoint. Define a single error envelope before writing the first endpoint and apply it everywhere.\n- **Breaking changes inside a stable version.** Removing a field, renaming a field, or changing a field's type in a published API version breaks all clients that depend on it without any version signal. Within a version, only additive changes — new optional fields, new endpoints — are permitted. Breaking changes require a new version (`\u002Fv2\u002F`).\n- **Offset pagination shipped to production for large datasets.** `?page=5&limit=20` requires the database to scan and discard N rows for every page, performance degrades linearly, and concurrent writes cause rows to appear on multiple pages or be skipped. Use cursor-based pagination from the start on any endpoint that may return more than a few hundred rows.\n- **OpenAPI schemas duplicated inline instead of using `$ref`.** Copy-pasting a schema definition into every endpoint that uses it means a change to the `User` schema must be applied in a dozen places — and will inevitably drift. Define every reusable type in `components\u002Fschemas` and reference it everywhere with `$ref`.\n\n## Full reference\n\n### Status code reference\n\n| Code | Name                  | When to use                              |\n|------|-----------------------|------------------------------------------|\n| 200  | OK                    | GET \u002F PUT \u002F PATCH with response body     |\n| 201  | Created               | POST that creates a resource (+Location) |\n| 202  | Accepted              | Async operation started                  |\n| 204  | No Content            | DELETE success or empty PUT\u002FPATCH        |\n| 400  | Bad Request           | Malformed syntax, invalid JSON           |\n| 401  | Unauthorized          | Missing\u002Finvalid auth                     |\n| 403  | Forbidden             | Authenticated but lacks permission       |\n| 404  | Not Found             | Resource does not exist                  |\n| 405  | Method Not Allowed    | Method not supported for this endpoint   |\n| 409  | Conflict              | Duplicate or version conflict            |\n| 422  | Unprocessable Entity  | Valid syntax, semantic validation failed |\n| 429  | Too Many Requests     | Rate limit exceeded                      |\n| 500  | Internal Server Error | Unhandled exception                      |\n| 502  | Bad Gateway           | Upstream returned bad response           |\n| 503  | Service Unavailable   | Overloaded or in maintenance             |\n| 504  | Gateway Timeout       | Upstream timed out                       |\n\nThe full method-semantics table (idempotency, safety, body usage) is\nin `references\u002Frest-conventions.md`.\n\n### Standard error codes\n\nPair the HTTP status with a stable string code so clients can match\nwithout parsing prose:\n\n| Code                  | HTTP        | Description                |\n|-----------------------|-------------|----------------------------|\n| VALIDATION_ERROR      | 400 \u002F 422   | Field validation failed    |\n| AUTHENTICATION_ERROR  | 401         | Invalid or missing creds   |\n| AUTHORIZATION_ERROR   | 403         | Insufficient permissions   |\n| NOT_FOUND             | 404         | Resource does not exist    |\n| CONFLICT              | 409         | Resource state conflict    |\n| RATE_LIMITED          | 429         | Too many requests          |\n| INTERNAL_ERROR        | 500         | Unexpected server error    |\n\n### Cursor vs offset pagination\n\nCursor pagination is preferred because it survives concurrent writes:\ninserting a row at the start of an offset-paginated list shifts every\nsubsequent page and causes drift (duplicates and skips). The cursor\nencodes the position in the index, so new rows do not affect pages\nalready fetched. Use offset only when the dataset is small, stable,\nand users genuinely need to jump to \"page 47.\"\n\n### HATEOAS (when to bother)\n\nFor genuinely discoverable APIs, embed action links in responses:\n\n```json\n{\n  \"id\": \"order-123\",\n  \"status\": \"shipped\",\n  \"_links\": {\n    \"self\":   { \"href\": \"\u002Fv1\u002Forders\u002Forder-123\" },\n    \"cancel\": { \"href\": \"\u002Fv1\u002Forders\u002Forder-123\u002Fcancel\", \"method\": \"POST\" }\n  }\n}\n```\n\nIn practice, most internal and partner APIs skip HATEOAS because\nclients are written against an OpenAPI spec, not a discoverable graph.\nAdd it when the API is genuinely browsable (public, long-lived, many\nunknown clients) or you're following a strict HAL\u002FJSON:API standard.\n\n### OpenAPI component patterns\n\nDefine `components\u002Fschemas` for every entity, plus `UserCreate`-style\ninput variants that omit `readOnly` fields. Define\n`components\u002Fparameters` for shared query\u002Fpath params (cursor, limit,\npath id) and `components\u002Fresponses` for shared error responses\n(`Unauthorized`, `ValidationError`, `NotFound`). List endpoints use\n`allOf` to compose `PaginatedResponse` with the entity type. See\n`references\u002Fopenapi-patterns.md` for full YAML examples and security\nscheme definitions (Bearer JWT, API key, OAuth2).\n\n### Review checklist\n\nWhen reviewing an API design, verify:\n\n1. Plural-noun resources, no verbs in paths.\n2. HTTP methods match semantics (GET safe, PUT idempotent).\n3. Status codes are correct (201 + Location on create, 204 on delete).\n4. Errors use the standard envelope with machine-readable codes.\n5. Every list endpoint paginates (cursor preferred).\n6. Versioning strategy is explicit and consistent.\n7. Rate-limit headers on every response.\n8. OpenAPI 3.1 spec compiles, schemas are `$ref`-ed, no copy-paste.\n\n### Anti-patterns to avoid\n\n- Verbs in URIs (`\u002FgetUsers`, `\u002FcreateOrder`).\n- Singular collections (`\u002Fuser` instead of `\u002Fusers`).\n- Deep nesting beyond three levels.\n- 200 responses carrying error payloads.\n- Inconsistent error formats between endpoints.\n- Unpaginated list endpoints (\"we'll add pagination later\").\n- Breaking changes inside a stable version — bump the version.\n- Inline-duplicated schemas in OpenAPI instead of `$ref`.\n","# API Design\n\n## Intro\n\nREST APIs follow well-established conventions: plural-noun resources,\nHTTP methods that match their semantics, correct status codes, cursor\npagination, URI versioning, and a consistent error envelope. Document\nthe contract in OpenAPI 3.1 with reusable components.\n\n## Overview\n\n### Resource naming\n\nUse plural nouns for collections (`\u002Fusers`, `\u002Forders`). Nest\nsub-resources to express ownership (`\u002Fusers\u002F{id}\u002Forders`) but cap\nnesting at three levels — go flat once the relationship is clear.\nAvoid verbs in URIs; the HTTP method is the verb. Use kebab-case for\nmulti-word segments (`\u002Fline-items`), lowercase only, no trailing\nslash, no file extensions.\n\nWhen CRUD doesn't fit, model the action as a sub-resource POST:\n`POST \u002Fv1\u002Forders\u002F{id}\u002Fcancel`, `POST \u002Fv1\u002Fusers\u002F{id}\u002Fverify-email`.\n\n### HTTP methods and status codes\n\nMap operations to methods consistently and return the right success\ncode:\n\n| Operation | Method | Success | Notes                  |\n|-----------|--------|---------|------------------------|\n| List      | GET    | 200     | Collection endpoint    |\n| Read      | GET    | 200     | Single resource        |\n| Create    | POST   | 201     | Return Location header |\n| Replace   | PUT    | 200     | Full replacement       |\n| Patch     | PATCH  | 200     | Partial update         |\n| Delete    | DELETE | 204     | No body                |\n\nGET is safe and idempotent. PUT and DELETE are idempotent. Never\nreturn 200 with an error payload — use the right 4xx\u002F5xx code.\n\n### Pagination\n\nDefault to **cursor-based** pagination. It is correct under concurrent\nwrites, scales to large datasets, and is what every serious API uses.\nReserve offset-based pagination for small, stable datasets where users\nneed to jump to page N.\n\n```json\n{\n  \"data\": [...],\n  \"pagination\": {\n    \"next_cursor\": \"abc123\",\n    \"has_more\": true\n  }\n}\n```\n\nCursors are opaque (base64-encoded). Clients must not parse them.\n\n### Filtering, sorting, versioning\n\n- Filter via query params: `GET \u002Forders?status=shipped&created_after=2025-01-01`.\n- Sort with `sort=`, prefix with `-` for descending: `?sort=-created_at,name`.\n- Version in the URI path for public APIs (`\u002Fv1\u002Fusers`). Use the\n  `Accept` header for internal APIs that need URL stability.\n- Within a version, only additive changes — never break clients.\n\n### Error responses\n\nUse one error envelope across every endpoint:\n\n```json\n{\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"Email is required.\",\n    \"details\": [\n      { \"field\": \"email\", \"reason\": \"required\" }\n    ],\n    \"request_id\": \"req_abc123\"\n  }\n}\n```\n\n`code` is machine-readable; `message` is human-readable; `details`\nholds per-field errors; `request_id` makes support tickets debuggable.\n\n### Rate limiting\n\nReturn rate-limit headers on every response, not just 429s:\n\n```\nX-RateLimit-Limit: 1000\nX-RateLimit-Remaining: 742\nX-RateLimit-Reset: 1672531200\n```\n\nReturn 429 Too Many Requests when the limit is exceeded.\n\n### OpenAPI 3.1\n\nDocument the API in OpenAPI 3.1. Extract shared schemas, parameters,\nand responses into `components\u002F` and `$ref` them everywhere. Define\nsecurity schemes globally with per-endpoint overrides for public\nroutes. See `references\u002Fopenapi-patterns.md` for the full skeleton\nincluding reusable parameters, responses, and security schemes.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Verbs in resource URIs.** `POST \u002FcreateOrder` or `GET \u002FgetUserById` bakes the HTTP method into the path, making the URL semantically redundant and breaking the REST constraint that the method alone describes the action. Use noun resources: `POST \u002Forders`, `GET \u002Fusers\u002F{id}`. When CRUD doesn't fit, model the action as a sub-resource: `POST \u002Forders\u002F{id}\u002Fcancel`.\n- **Unpaginated list endpoints shipped as \"we'll add it later.\"** A list endpoint that returns all records works fine in development with 50 records and fails spectacularly in production with 50,000. Pagination cannot be added to a stable API without a breaking change to the response shape. Every list endpoint must paginate from day one, with a default page size that makes the system safe.\n- **200 OK with an error payload.** Returning `{\"error\": \"not found\"}` with HTTP 200 means clients cannot use HTTP status codes to distinguish success from failure — they must parse every response body. Return 4xx or 5xx status codes that match the actual error so clients, proxies, monitoring systems, and retry logic all work correctly.\n- **Inconsistent error envelopes across endpoints.** Some endpoints return `{\"error\": \"...\"}`, others return `{\"message\": \"...\"}`, others return `{\"errors\": [...]}`. Clients must special-case every endpoint. Define a single error envelope before writing the first endpoint and apply it everywhere.\n- **Breaking changes inside a stable version.** Removing a field, renaming a field, or changing a field's type in a published API version breaks all clients that depend on it without any version signal. Within a version, only additive changes — new optional fields, new endpoints — are permitted. Breaking changes require a new version (`\u002Fv2\u002F`).\n- **Offset pagination shipped to production for large datasets.** `?page=5&limit=20` requires the database to scan and discard N rows for every page, performance degrades linearly, and concurrent writes cause rows to appear on multiple pages or be skipped. Use cursor-based pagination from the start on any endpoint that may return more than a few hundred rows.\n- **OpenAPI schemas duplicated inline instead of using `$ref`.** Copy-pasting a schema definition into every endpoint that uses it means a change to the `User` schema must be applied in a dozen places — and will inevitably drift. Define every reusable type in `components\u002Fschemas` and reference it everywhere with `$ref`.\n\n## Full reference\n\n### Status code reference\n\n| Code | Name                  | When to use                              |\n|------|-----------------------|------------------------------------------|\n| 200  | OK                    | GET \u002F PUT \u002F PATCH with response body     |\n| 201  | Created               | POST that creates a resource (+Location) |\n| 202  | Accepted              | Async operation started                  |\n| 204  | No Content            | DELETE success or empty PUT\u002FPATCH        |\n| 400  | Bad Request           | Malformed syntax, invalid JSON           |\n| 401  | Unauthorized          | Missing\u002Finvalid auth                     |\n| 403  | Forbidden             | Authenticated but lacks permission       |\n| 404  | Not Found             | Resource does not exist                  |\n| 405  | Method Not Allowed    | Method not supported for this endpoint   |\n| 409  | Conflict              | Duplicate or version conflict            |\n| 422  | Unprocessable Entity  | Valid syntax, semantic validation failed |\n| 429  | Too Many Requests     | Rate limit exceeded                      |\n| 500  | Internal Server Error | Unhandled exception                      |\n| 502  | Bad Gateway           | Upstream returned bad response           |\n| 503  | Service Unavailable   | Overloaded or in maintenance             |\n| 504  | Gateway Timeout       | Upstream timed out                       |\n\nThe full method-semantics table (idempotency, safety, body usage) is\nin `references\u002Frest-conventions.md`.\n\n### Standard error codes\n\nPair the HTTP status with a stable string code so clients can match\nwithout parsing prose:\n\n| Code                  | HTTP        | Description                |\n|-----------------------|-------------|----------------------------|\n| VALIDATION_ERROR      | 400 \u002F 422   | Field validation failed    |\n| AUTHENTICATION_ERROR  | 401         | Invalid or missing creds   |\n| AUTHORIZATION_ERROR   | 403         | Insufficient permissions   |\n| NOT_FOUND             | 404         | Resource does not exist    |\n| CONFLICT              | 409         | Resource state conflict    |\n| RATE_LIMITED          | 429         | Too many requests          |\n| INTERNAL_ERROR        | 500         | Unexpected server error    |\n\n### Cursor vs offset pagination\n\nCursor pagination is preferred because it survives concurrent writes:\ninserting a row at the start of an offset-paginated list shifts every\nsubsequent page and causes drift (duplicates and skips). The cursor\nencodes the position in the index, so new rows do not affect pages\nalready fetched. Use offset only when the dataset is small, stable,\nand users genuinely need to jump to \"page 47.\"\n\n### HATEOAS (when to bother)\n\nFor genuinely discoverable APIs, embed action links in responses:\n\n```json\n{\n  \"id\": \"order-123\",\n  \"status\": \"shipped\",\n  \"_links\": {\n    \"self\":   { \"href\": \"\u002Fv1\u002Forders\u002Forder-123\" },\n    \"cancel\": { \"href\": \"\u002Fv1\u002Forders\u002Forder-123\u002Fcancel\", \"method\": \"POST\" }\n  }\n}\n```\n\nIn practice, most internal and partner APIs skip HATEOAS because\nclients are written against an OpenAPI spec, not a discoverable graph.\nAdd it when the API is genuinely browsable (public, long-lived, many\nunknown clients) or you're following a strict HAL\u002FJSON:API standard.\n\n### OpenAPI component patterns\n\nDefine `components\u002Fschemas` for every entity, plus `UserCreate`-style\ninput variants that omit `readOnly` fields. Define\n`components\u002Fparameters` for shared query\u002Fpath params (cursor, limit,\npath id) and `components\u002Fresponses` for shared error responses\n(`Unauthorized`, `ValidationError`, `NotFound`). List endpoints use\n`allOf` to compose `PaginatedResponse` with the entity type. See\n`references\u002Fopenapi-patterns.md` for full YAML examples and security\nscheme definitions (Bearer JWT, API key, OAuth2).\n\n### Review checklist\n\nWhen reviewing an API design, verify:\n\n1. Plural-noun resources, no verbs in paths.\n2. HTTP methods match semantics (GET safe, PUT idempotent).\n3. Status codes are correct (201 + Location on create, 204 on delete).\n4. Errors use the standard envelope with machine-readable codes.\n5. Every list endpoint paginates (cursor preferred).\n6. Versioning strategy is explicit and consistent.\n7. Rate-limit headers on every response.\n8. OpenAPI 3.1 spec compiles, schemas are `$ref`-ed, no copy-paste.\n\n### Anti-patterns to avoid\n\n- Verbs in URIs (`\u002FgetUsers`, `\u002FcreateOrder`).\n- Singular collections (`\u002Fuser` instead of `\u002Fusers`).\n- Deep nesting beyond three levels.\n- 200 responses carrying error payloads.\n- Inconsistent error formats between endpoints.\n- Unpaginated list endpoints (\"we'll add pagination later\").\n- Breaking changes inside a stable version — bump the version.\n- Inline-duplicated schemas in OpenAPI instead of `$ref`.\n",{"name":5,"metadata":59,"description":66},{"processkit":60},{"id":61,"created":62,"version":63,"category":64,"apiVersion":65},"SKILL-api-design",1775433600000,"1.1.0","engineering","processkit.projectious.work\u002Fv2","REST API design — resource naming, HTTP methods, status codes, pagination, versioning, OpenAPI. Use when designing a new REST API, reviewing API contracts, writing OpenAPI\u002FSwagger documentation, or choosing pagination, versioning, or error-format strategies.\n","main","7231f100e266e30d2c1699ecde5c00602471dc3c","src\u002Fcontext\u002Fskills\u002Fengineering\u002Fapi-design","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit","https:\u002F\u002Fprojectious-work.github.io\u002Fprocesskit\u002F","https:\u002F\u002Fgithub.com\u002Fprojectious-work","2026-11-11 23:24:18",{"source":8,"skillName":5,"commands":75,"prompt":85,"zipAvailable":86},[76,79,82],{"tool":77,"command":78},"npx","npx skills add projectious-work\u002Fprocesskit --skill api-design",{"tool":80,"command":81},"bunx","bunx skills add projectious-work\u002Fprocesskit --skill api-design",{"tool":83,"command":84},"pnpm","pnpm dlx skills add projectious-work\u002Fprocesskit --skill api-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fengineering\u002Fapi-design\u002FSKILL.md",true,[88,94,98],{"path":89,"resourceType":90,"resourceTypeDesc":91,"sizeBytes":92,"sourceHtmlUrl":93},"references\u002Fopenapi-patterns.md","REFERENCE","参考文档",6674,"https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fengineering\u002Fapi-design\u002Freferences\u002Fopenapi-patterns.md",{"path":95,"resourceType":90,"resourceTypeDesc":91,"sizeBytes":96,"sourceHtmlUrl":97},"references\u002Frest-conventions.md",5929,"https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fengineering\u002Fapi-design\u002Freferences\u002Frest-conventions.md",{"path":99,"resourceType":100,"resourceTypeDesc":101,"sizeBytes":14,"sourceHtmlUrl":102},"scripts\u002F.gitkeep","SCRIPT","脚本","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fengineering\u002Fapi-design\u002Fscripts\u002F.gitkeep",[104,111,118,124,149,169],{"skillNo":105,"name":106,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":110},"01M7665G2ED3624R3X93304265","standard-ui-design","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-ui-design\u002FSKILL.md",[],[],"2026-11-12 13:55:43",{"skillNo":112,"name":113,"nameZh":6,"description":114,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":115,"categories":116,"keywords":117,"publishedAt":110},"01M76651QTC6W0HJ4AFW2MMR3V","standard-agent-use","Company standard for working with AI agents. Use when deciding what to delegate to agents, capturing open work, keeping agent memory or knowledge notes, improving an agent workflow, or introducing agent work in a team or for a client.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-agent-use\u002FSKILL.md",[],[],{"skillNo":119,"name":120,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":121,"categories":122,"keywords":123,"publishedAt":110},"01M76650NN4T8P241021NBR64S","standard-agent-building","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-agent-building\u002FSKILL.md",[],[],{"skillNo":125,"name":126,"nameZh":6,"description":127,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":128,"categories":129,"keywords":133,"publishedAt":54},"01M6X5MTC89B4ZGXW3JVSQCPF8","skill-management","Manage Skill package manifests as v1 ontology entities.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fskill-management\u002FSKILL.md",[130],{"categoryNo":131,"categoryName":132,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[134,135,136,137,138,139,47,140,141,142,143,144,126,145,146,147,148],"management","skill management","ontology","v1","create","as","transition","get","manage","update","alpha","list","package","skill package","manifests",{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":156,"publishedAt":54},"01M6X5MCV74NHW5MEDNHZRF2C8","schema-management","Manage generated processkit schema contracts through deterministic MCP rebuild and inspection workflows.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fschema-management\u002FSKILL.md",[155],{"categoryNo":131,"categoryName":132,"taxonomyType":21,"taxonomyTypeDesc":22},[157,158,134,159,160,161,162,163,164,165,166,167,47,141,142,144,168],"schema","schema management","contract","rebuild","contracts","workflows","wed","generated","MCP","validation","deterministic","mode",{"skillNo":170,"name":171,"nameZh":6,"description":172,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":173,"categories":174,"keywords":175,"publishedAt":54},"01M6X5M5G6YJ96AMZGSCZJ1D13","proposition-management","Record claims, risks, beliefs, world facts, WSJF estimates, and assumptions through the Proposition interface.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fproposition-management\u002FSKILL.md",[],[176,134,177,178,138,179,180,181,47,141,182,183,143,184,144,185,186,187,188,189],"proposition management","proposition","interface","claims","record","world","creation","event","WSJF","index","updates","query","facts","log"]