[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6MDA8529G2WBNPYWHM3Y3YQ":3,"skill-same:01M6MDA8529G2WBNPYWHM3Y3YQ":81},{"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":31,"publishedAt":52,"linkOnly":53,"markdownContent":54,"markdownBody":55,"frontMatter":56,"refName":57,"commitSha":58,"skillDirectory":59,"forksCount":60,"repositoryHtmlUrl":61,"repositoryHomepageUrl":62,"ownerHtmlUrl":63,"ownerBlogUrl":64,"ownerDescription":65,"updatedAt":66,"install":67,"resources":80},"01M6MDA8529G2WBNPYWHM3Y3YQ","api-contract-first",null,"Hard gate before implementing any API endpoint or service interface. Requires a written, reviewed contract (OpenAPI 3.x, protobuf, or GraphQL schema) before any implementation code is written. Prevents breaking changes, misaligned clients, and undocumented behaviour.","hashgraph-online\u002Fawesome-codex-plugins","hashgraph-online","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F160371962?v=4","01M6CNB6NRJVNNGN14TR01Q6D3","HOL (Hashgraph Online)","01M6JT1HSKKG9V68KQAQGBA7XP",1575,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FRBraga01\u002Fa-team\u002Fskills\u002Fapi-contract-first\u002FSKILL.md",[18,23,28],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",{"categoryNo":29,"categoryName":30,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000037","律师与法务",[32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51],"api contract first","contract first","first","api","contract","api contract","api endpoint","changes","implementing","interface","graphql schema","clients","protobuf","gate","implementation","schema","openapi","endpoint","GraphQL","code","2026-11-10 10:12:30",false,"---\nname: api-contract-first\ndescription: Hard gate before implementing any API endpoint or service interface. Requires a written, reviewed contract (OpenAPI 3.x, protobuf, or GraphQL schema) before any implementation code is written. Prevents breaking changes, misaligned clients, and undocumented behaviour.\n---\n\n# API Contract First\n\n## The Law\n\n```\nNO API IMPLEMENTATION WITHOUT A REVIEWED CONTRACT.\nWriting endpoints before the contract is building to a spec that doesn't exist.\nThe contract IS the spec. Code that matches it is correct. Code that doesn't is wrong.\n```\n\n## When to Use\n\nUse this skill before writing ANY of these:\n- A new REST endpoint\n- A new gRPC\u002Fprotobuf service method\n- A new GraphQL query, mutation, or subscription\n- A new event schema (Kafka, SQS, webhooks)\n- A new inter-service interface\n\n## The Contract Process\n\n### Step 1: Write the Contract\n\nChoose the format that matches the project's stack:\n\n**REST → OpenAPI 3.x**\n```yaml\n# docs\u002Fapi\u002Fopenapi.yaml\npaths:\n  \u002Forders:\n    post:\n      summary: Create a new order\n      requestBody:\n        required: true\n        content:\n          application\u002Fjson:\n            schema:\n              $ref: '#\u002Fcomponents\u002Fschemas\u002FCreateOrderRequest'\n      responses:\n        '201':\n          description: Order created\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: '#\u002Fcomponents\u002Fschemas\u002FOrder'\n        '400':\n          $ref: '#\u002Fcomponents\u002Fresponses\u002FValidationError'\n        '401':\n          $ref: '#\u002Fcomponents\u002Fresponses\u002FUnauthorized'\ncomponents:\n  schemas:\n    CreateOrderRequest:\n      type: object\n      required: [userId, items]\n      properties:\n        userId:\n          type: string\n          format: uuid\n        items:\n          type: array\n          minItems: 1\n          items:\n            $ref: '#\u002Fcomponents\u002Fschemas\u002FOrderItem'\n```\n\n**Events \u002F Async → AsyncAPI or JSON Schema**\n```yaml\n# docs\u002Fevents\u002Forder-created.yaml\nname: order.created\nversion: 1.0.0\npayload:\n  type: object\n  required: [orderId, userId, createdAt]\n  properties:\n    orderId: { type: string, format: uuid }\n    userId: { type: string, format: uuid }\n    createdAt: { type: string, format: date-time }\n```\n\n### Step 2: Contract Review Checklist\n\nBefore implementation begins, verify the contract satisfies all of these:\n\n**Naming & Consistency**\n- [ ] Resource names are nouns, plural (`\u002Forders` not `\u002FcreateOrder`)\n- [ ] Consistent casing throughout (snake_case for JSON fields, kebab-case for URL segments)\n- [ ] New names consistent with existing API vocabulary (don't introduce synonyms for existing concepts)\n\n**Completeness**\n- [ ] All error responses documented (at minimum: 400, 401, 403, 404, 422, 500)\n- [ ] All required vs optional fields explicitly marked\n- [ ] Field types, formats, and constraints defined (min\u002Fmax, pattern, enum values)\n- [ ] Pagination documented if the endpoint returns a collection\n\n**Versioning**\n- [ ] Breaking changes introduce a new version (`\u002Fv2\u002F`) — never modify `\u002Fv1\u002F` in a breaking way\n- [ ] A change is breaking if it: removes a field, changes a field type, makes an optional field required, changes status code semantics\n\n**Security**\n- [ ] Authentication requirement stated (which scheme: Bearer, API Key, session)\n- [ ] Authorisation scope documented (who can call this: any user, admin only, service-to-service)\n- [ ] Rate limits noted if applicable\n\n**Consumer Perspective**\n- [ ] The contract was designed for how clients need to use it — not how it's easiest to implement\n- [ ] A new team member could implement a client from this contract alone\n\n### Step 3: Get Contract Approved\n\nSave the contract file to `docs\u002Fapi\u002F` or `docs\u002Fevents\u002F`. The contract is reviewed before implementation begins — not after.\n\n**Approval gate:** the `planner` agent must reference the approved contract file in the implementation plan. If no contract file is referenced, the plan is not complete.\n\n### Step 4: Implement Against the Contract\n\nImplementation is correct when it matches the contract exactly. The contract is the source of truth — not the implementation.\n\nIf the implementation reveals that the contract needs to change:\n1. Update the contract first\n2. Re-review the changed section\n3. Then update the implementation\n\nNever silently diverge from the contract. Every divergence is a breaking change waiting to happen.\n\n### Step 5: Contract Tests\n\nWrite at least one contract test per endpoint that validates the actual response against the OpenAPI schema:\n\n```typescript\n\u002F\u002F [VALID] — tests the real implementation against the contract\nimport { validate } from 'openapi-validator'\nimport { spec } from '..\u002Fdocs\u002Fapi\u002Fopenapi.yaml'\n\ntest('POST \u002Forders response matches contract', async () => {\n  const response = await request(app).post('\u002Forders').send(validPayload)\n  const errors = validate(spec, '\u002Forders', 'post', response)\n  expect(errors).toHaveLength(0)\n})\n```\n\n## Rationalization Red Flags\n\nThese mean you are about to skip the contract step:\n- \"The endpoint is simple, I'll document it after\"\n- \"The client team knows what they're getting\"\n- \"We'll sort out the contract in the PR description\"\n- \"It's an internal API, nobody will break\"\n\nAll of these precede the same outcome: a client built on undocumented assumptions, followed by a breaking change that neither team sees coming.\n","# API Contract First\n\n## The Law\n\n```\nNO API IMPLEMENTATION WITHOUT A REVIEWED CONTRACT.\nWriting endpoints before the contract is building to a spec that doesn't exist.\nThe contract IS the spec. Code that matches it is correct. Code that doesn't is wrong.\n```\n\n## When to Use\n\nUse this skill before writing ANY of these:\n- A new REST endpoint\n- A new gRPC\u002Fprotobuf service method\n- A new GraphQL query, mutation, or subscription\n- A new event schema (Kafka, SQS, webhooks)\n- A new inter-service interface\n\n## The Contract Process\n\n### Step 1: Write the Contract\n\nChoose the format that matches the project's stack:\n\n**REST → OpenAPI 3.x**\n```yaml\n# docs\u002Fapi\u002Fopenapi.yaml\npaths:\n  \u002Forders:\n    post:\n      summary: Create a new order\n      requestBody:\n        required: true\n        content:\n          application\u002Fjson:\n            schema:\n              $ref: '#\u002Fcomponents\u002Fschemas\u002FCreateOrderRequest'\n      responses:\n        '201':\n          description: Order created\n          content:\n            application\u002Fjson:\n              schema:\n                $ref: '#\u002Fcomponents\u002Fschemas\u002FOrder'\n        '400':\n          $ref: '#\u002Fcomponents\u002Fresponses\u002FValidationError'\n        '401':\n          $ref: '#\u002Fcomponents\u002Fresponses\u002FUnauthorized'\ncomponents:\n  schemas:\n    CreateOrderRequest:\n      type: object\n      required: [userId, items]\n      properties:\n        userId:\n          type: string\n          format: uuid\n        items:\n          type: array\n          minItems: 1\n          items:\n            $ref: '#\u002Fcomponents\u002Fschemas\u002FOrderItem'\n```\n\n**Events \u002F Async → AsyncAPI or JSON Schema**\n```yaml\n# docs\u002Fevents\u002Forder-created.yaml\nname: order.created\nversion: 1.0.0\npayload:\n  type: object\n  required: [orderId, userId, createdAt]\n  properties:\n    orderId: { type: string, format: uuid }\n    userId: { type: string, format: uuid }\n    createdAt: { type: string, format: date-time }\n```\n\n### Step 2: Contract Review Checklist\n\nBefore implementation begins, verify the contract satisfies all of these:\n\n**Naming & Consistency**\n- [ ] Resource names are nouns, plural (`\u002Forders` not `\u002FcreateOrder`)\n- [ ] Consistent casing throughout (snake_case for JSON fields, kebab-case for URL segments)\n- [ ] New names consistent with existing API vocabulary (don't introduce synonyms for existing concepts)\n\n**Completeness**\n- [ ] All error responses documented (at minimum: 400, 401, 403, 404, 422, 500)\n- [ ] All required vs optional fields explicitly marked\n- [ ] Field types, formats, and constraints defined (min\u002Fmax, pattern, enum values)\n- [ ] Pagination documented if the endpoint returns a collection\n\n**Versioning**\n- [ ] Breaking changes introduce a new version (`\u002Fv2\u002F`) — never modify `\u002Fv1\u002F` in a breaking way\n- [ ] A change is breaking if it: removes a field, changes a field type, makes an optional field required, changes status code semantics\n\n**Security**\n- [ ] Authentication requirement stated (which scheme: Bearer, API Key, session)\n- [ ] Authorisation scope documented (who can call this: any user, admin only, service-to-service)\n- [ ] Rate limits noted if applicable\n\n**Consumer Perspective**\n- [ ] The contract was designed for how clients need to use it — not how it's easiest to implement\n- [ ] A new team member could implement a client from this contract alone\n\n### Step 3: Get Contract Approved\n\nSave the contract file to `docs\u002Fapi\u002F` or `docs\u002Fevents\u002F`. The contract is reviewed before implementation begins — not after.\n\n**Approval gate:** the `planner` agent must reference the approved contract file in the implementation plan. If no contract file is referenced, the plan is not complete.\n\n### Step 4: Implement Against the Contract\n\nImplementation is correct when it matches the contract exactly. The contract is the source of truth — not the implementation.\n\nIf the implementation reveals that the contract needs to change:\n1. Update the contract first\n2. Re-review the changed section\n3. Then update the implementation\n\nNever silently diverge from the contract. Every divergence is a breaking change waiting to happen.\n\n### Step 5: Contract Tests\n\nWrite at least one contract test per endpoint that validates the actual response against the OpenAPI schema:\n\n```typescript\n\u002F\u002F [VALID] — tests the real implementation against the contract\nimport { validate } from 'openapi-validator'\nimport { spec } from '..\u002Fdocs\u002Fapi\u002Fopenapi.yaml'\n\ntest('POST \u002Forders response matches contract', async () => {\n  const response = await request(app).post('\u002Forders').send(validPayload)\n  const errors = validate(spec, '\u002Forders', 'post', response)\n  expect(errors).toHaveLength(0)\n})\n```\n\n## Rationalization Red Flags\n\nThese mean you are about to skip the contract step:\n- \"The endpoint is simple, I'll document it after\"\n- \"The client team knows what they're getting\"\n- \"We'll sort out the contract in the PR description\"\n- \"It's an internal API, nobody will break\"\n\nAll of these precede the same outcome: a client built on undocumented assumptions, followed by a breaking change that neither team sees coming.\n",{"name":5,"description":7},"main","2b63f856ce19c2a797929cacabd9e0fc936812fa","plugins\u002FRBraga01\u002Fa-team\u002Fskills\u002Fapi-contract-first",491,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins","https:\u002F\u002Fhol.org\u002Fplugins\u002Fbest-codex-plugins","https:\u002F\u002Fgithub.com\u002Fhashgraph-online","https:\u002F\u002Fhol.org","Open-source standards and developer tools for interoperable AI agents: discovery, identity, communication, payments, privacy and security.","2026-11-14 14:06:13",{"source":8,"skillName":5,"commands":68,"prompt":78,"zipAvailable":79},[69,72,75],{"tool":70,"command":71},"npx","npx skills add hashgraph-online\u002Fawesome-codex-plugins --skill api-contract-first",{"tool":73,"command":74},"bunx","bunx skills add hashgraph-online\u002Fawesome-codex-plugins --skill api-contract-first",{"tool":76,"command":77},"pnpm","pnpm dlx skills add hashgraph-online\u002Fawesome-codex-plugins --skill api-contract-first","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FRBraga01\u002Fa-team\u002Fskills\u002Fapi-contract-first\u002FSKILL.md",true,[],[82,92,100,108,116,124],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":86,"licenseFileUrl":87,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":91},"01M7DV332YQMGD8WTRJ9DZQXTB","worktable-review-with-annotations","Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.","MIT","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":86,"licenseFileUrl":96,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":91},"01M7DV2YGHCZVBEB1AHYB6CGHE","worktable-find-and-synthesize-context","Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FSKILL.md",[],[],{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":86,"licenseFileUrl":104,"sourceHtmlUrl":105,"categories":106,"keywords":107,"publishedAt":91},"01M7DV2TQN1H11ME2SAF9MXN7V","worktable-create-or-update-docs","Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FSKILL.md",[],[],{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":86,"licenseFileUrl":112,"sourceHtmlUrl":113,"categories":114,"keywords":115,"publishedAt":91},"01M7DV2NE452NEA8TXATKSNAJH","worktable-create-or-manage-records","Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FSKILL.md",[],[],{"skillNo":117,"name":118,"nameZh":6,"description":119,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":86,"licenseFileUrl":120,"sourceHtmlUrl":121,"categories":122,"keywords":123,"publishedAt":91},"01M7DV2HENRBR2KSCVM064WH0Y","worktable-create-or-manage-interactive-html","Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\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":86,"licenseFileUrl":128,"sourceHtmlUrl":129,"categories":130,"keywords":131,"publishedAt":91},"01M7DV2CADR5R7RQFFYPNAGR9Y","worktable-collaborate-threads","Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FSKILL.md",[],[]]