Agent Skills
› AjayIrkal23/agentic-mercy-10x
› api-contract-standards
api-contract-standards
GitHub定义后端API响应契约标准，涵盖成功/错误信封结构、列表元数据及端点意图分离。用于规范JSON格式、分页排序默认值及向后兼容性，确保前后端接口一致性。
Trigger Scenarios
定义或审查后端响应信封结构
审查列表端点契约（分页、过滤）
创建需符合契约约定的新API路由
评估可能破坏前端消费者的API变更
Install
npx skills add AjayIrkal23/agentic-mercy-10x --skill api-contract-standards -g -y
SKILL.md
Frontmatter
{
"name": "api-contract-standards",
"schema": 1,
"category": "general",
"surfaces": [
"general"
],
"triggers": {
"paths": [
"src\/schemas\/",
"src\/types\/"
],
"intents": [
"general"
],
"keywords": [
"api",
"apis",
"backend",
"boundaries",
"card",
"contract",
"contracts",
"creating",
"defined",
"defining",
"design",
"designing",
"endpoints",
"envelopes",
"error",
"establishing",
"frontend",
"graphql",
"guides",
"interface",
"list",
"metadata",
"module",
"modules",
"public",
"response",
"rest",
"reviewed",
"separation",
"shapes",
"stable",
"standards",
"summary",
"table",
"type",
"versioning"
]
},
"platforms": [
"linux",
"darwin",
"windows"
],
"token-cost": 642,
"description": "ALWAYS invoke when backend response envelopes, list metadata, error shapes, versioning, or the separation between table, card, and summary contracts are being defined or reviewed.",
"disable-model-invocation": false
}
Use When
- Defining or reviewing backend response envelope shapes (
data,meta,errorfields). - Reviewing list endpoint contracts (pagination metadata, filter keys, sort contracts).
- Any API change that could break existing frontend consumers (field renames, type changes, removals).
- Creating a new API route that must conform to the project's existing contract conventions.
- Reviewing versioning decisions or backward-compatibility boundaries.
Do Not Use
- For frontend-only implementation details (component state, local UI state).
- For reviewing Go/TS logic that does not touch public API response shapes.
- As a replacement for
backend-api-standardswhich covers route-level implementation rules.
API Contract Standards
Overview
This is the backend contract source of truth.
Use it when the public wire shape matters: success envelopes, error envelopes, list metadata, compatibility, and contract separation by endpoint intent.
Non-Negotiables
- Every endpoint returns JSON.
- Every response includes
success. - Success responses include
data. - Error responses use
error.codeand a safeerror.message. - List endpoints are paginated.
- Filtering, sorting, and pagination happen in the backend.
- Existing response keys do not change casually.
- Unknown query keys are rejected by default unless explicitly allowed.
Standard Success Envelope
{
"success": true,
"data": {},
"message": "",
"meta": {}
}
Standard Error Envelope
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Safe user-facing message",
"details": {}
}
}
Endpoint Intent Separation
Do not mix these contract types:
- table/list endpoints
- summary or KPI endpoints
- card/grid preview endpoints
If the UI needs a different intent, give it a dedicated contract instead of reusing a list shape for everything.
List Contract Defaults
Recommended defaults:
page = 1limit = 20maxLimit = 100sortBy = "createdAt"sortOrder = "desc"
List metadata should stay stable across domains.
Compatibility Rule
If a contract changes in a way that can break consumers, version it or plan a migration explicitly.
Combine With
backend-api-standardsfor query semantics.backend-error-handlingfor error taxonomy and centralized handling.service-layer-standardsfor thin-controller ownership boundaries.
References
- Use
references/full-guide.mdfor the longer strict version with more detailed endpoint intent and examples.
Version History
- 581d130 Current 2026-07-19 09:04
