api-envelope-pattern
Standard API envelope pattern for all responses (success/list/error). Wraps data in consistent structure with sys metadata, automatic payload compaction (30-40% reduction), timestamp injection. Triggers on "formatEntity", "formatEntityList", "formatErrorEntity", "API", "route handler", "dal".
npx skills add majiayu000/claude-skill-registry --skill api-envelope-pattern --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# API Envelope Pattern ALL API responses MUST use standard envelope pattern. NEVER return raw Convex docs or plain data. Consistent structure enables mobile clients, monitoring, caching. ## Standard Envelope Structure Every response wrapped in `ApiResponse<T>`: ```typescript // Success (single entity) { status: "success", sys: { entity: "conversation", id: "j97...", timestamps?: { created: "2024-01-15T10:30:00.000Z", updated: "2024-01-15T12:45:00.000Z", retrieved: "2024-01-15T13:00:00.000Z" } }, data: { ... } // Compacted data (nulls/empty removed) } // List response { status: "success", sys: { entity: "list" }, data: [ { sys: { entity: "conversation", id: "j97..." }, data: { ... } } ] } // Error response { status: "error", sys: { entity: "error" }, error: "Resource not found" // or { message, code, details } } ``` ## Entity Formatters Use these helpers from `@/lib/utils/formatEntity`: ### formatEntity (Single Item) ```typescript // From convex/api/dal/conversations.ts return formatEntity(conversation, "conversation", conversation._id); // Auto-injects timestamps from Convex _creationTime + updatedAt // Compacts data (removes null/undefined/empty) ``` ### formatEntityList (Arrays)
- Standard Envelope Structure
- Entity Formatters
- formatEntity (Single Item)
- formatEntityList (Arrays)
- formatErrorEntity (Errors)
- Compact Utility (30-40% Payload Reduction)
- Timestamp Injection
- DAL Layer Pattern
- Route Handler Pattern
- Error Handling Middleware
- Frontend Unwrapping
- Type Definitions
- Key Files
- Common Mistakes
What does the api-envelope-pattern skill do?
Standard API envelope pattern for all responses (success/list/error). Wraps data in consistent structure with sys metadata, automatic payload compaction (30-40% reduction), timestamp injection. Triggers on "formatEntity", "formatEntityList", "formatErrorEntity", "API", "route handler", "dal".
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill api-envelope-pattern --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.