Agent Skills
› AjayIrkal23/agentic-mercy-10x
› frontend-response-handling
frontend-response-handling
GitHub处理前端API集成，包括成功响应解析、标准化错误处理及后端驱动的分页排序查询。适用于涉及异步数据层、API模块及列表页面的开发场景，确保前后端契约一致与数据层职责分离。
Trigger Scenarios
需要解析前端API成功响应时
处理网络或传输失败并标准化错误时
实现后端驱动的分页、过滤和排序逻辑时
开发基于API的列表或表格页面时
Install
npx skills add AjayIrkal23/agentic-mercy-10x --skill frontend-response-handling -g -y
SKILL.md
Frontmatter
{
"name": "frontend-response-handling",
"schema": 1,
"category": "frontend",
"surfaces": [
"frontend"
],
"triggers": {
"paths": [
"\/api-client",
"\/api\/",
"\/auth\/",
"\/guard\/",
"\/login\/",
"api.js",
"api.ts",
"protected",
"session"
],
"intents": [
"frontend"
],
"keywords": [
"api",
"backend",
"backend-driven",
"behavior",
"calls",
"conform",
"contracts",
"error",
"errors",
"fetch",
"flows",
"frontend",
"frontend-response-handling",
"handle",
"handling",
"have",
"implementing",
"instead",
"layer",
"layers",
"limit",
"list",
"list\/query",
"must",
"needs",
"normalization",
"normalize",
"normalized",
"page",
"parse",
"parsing",
"prefer",
"query",
"raw",
"response",
"responses",
"sdk",
"sortby",
"sortorder",
"success",
"success\/error",
"work",
"wrappers",
"yet"
]
},
"platforms": [
"linux",
"darwin",
"windows"
],
"token-cost": 792,
"description": "ALWAYS invoke when frontend API work needs success parsing, normalized error handling, or backend-driven list, filter, sort, and pagination behavior.",
"disable-model-invocation": false
}
Frontend Response Handling
Overview
This is the canonical frontend API integration skill.
It combines backend-driven list/query behavior with success-envelope parsing and normalized error handling.
Use When
- Touching
src/api/**,src/apis/**, thunks, async query layers, or API-backed list/table screens. - Adapting frontend code to an existing backend contract.
- Normalizing transport failures into frontend-safe errors.
Do Not Use
- Pure visual work.
- General module layout without async data.
- Backend-side query validation or DB strategy.
Owns
- Parsing success envelopes.
- Normalizing frontend-safe error objects.
- Backend-driven list/query behavior on the frontend.
- Layer responsibilities between component, store/query layer, API module, and API client.
Contract Lock First
- Read the relevant frontend API docs and existing API client/types/pattern file. Use repo-local docs to confirm whether the repo standard is
src/api/**orsrc/apis/**. - Inspect backend
route -> schema -> controller -> service. - Lock request keys, success envelope, error envelope, and pagination metadata before coding.
Success Rules
Expected backend success envelope:
{
"success": true,
"data": {},
"message": "",
"meta": {}
}
- API modules must parse the envelope explicitly.
- Return typed domain data, not raw transport objects.
- Use an adapter if the backend still exposes a legacy shape.
Error Rules
Expected backend error envelope:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Safe message",
"details": {}
}
}
Frontend normalized error shape:
type NormalizedApiError = {
code: string
message: string
statusCode: number
details?: Record<string, unknown>
isRetryable: boolean
}
- Map timeout, network, and unknown failures to stable fallback codes.
- Never leak raw transport or internal backend details to UI.
Backend-Driven Query Rules
- The query object is the single source of truth.
- Filters, sort, and pagination update query state only.
- Any meaningful query change triggers a refetch.
- Reset page when filter/search changes invalidate the current page.
- Never do client-side filtering or pagination for server datasets.
Layer Boundaries
- API layer: call backend, parse success, normalize and throw typed errors.
- Store/query layer: map normalized results into user-facing state and messages.
- Component/page layer: render state only; no raw
error.responseor raw payload parsing.
Workflow
- Lock the contract first.
- Implement the API adapter once.
- Normalize errors once.
- Wire query-driven state.
- Verify loading, empty, error, and success states together.
References
- Use
references/api-module-template.mdfor a reusable API module template. - Use
frontend-server-data-patternswhen the main question is screen-level query-state design.
Completion Checklist
- Backend contract was verified before implementation.
- Success envelope is parsed explicitly.
- Query behavior is backend-driven.
- One normalized error shape is used.
- No raw internal errors leak to UI.
Version History
- 581d130 Current 2026-07-19 09:08
