Agent skill · software engineering · aiskillstore
api-organization
Explains the standardized API organization pattern for this codebase. Use when creating new API endpoints, API clients, or modifying existing API structure. Covers the 5-file system (endpoint-types, endpoints, api-client, admin-api-client, protected-endpoints), role-based access patterns (admin vs regular users), and TypeScript type safety across the API layer. All API code lives in src/lib/api/ following this exact pattern.
Why this skill is useful
Defines a specific 5-file API organization pattern and role-based access that enhances maintainability and type safety, which the AI wouldn't reliably generate on its own.
What it needs
Requires supabase account access. About 6k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
API Organization Pattern This skill defines the standardized API organization pattern used throughout this codebase. All external API integrations follow the same 5-file structure for consistency, type safety, and maintainability. When to Use This Skill Use this skill when: Creating new API endpoints or integrations Adding new API categories or domains Implementing role-based API access (admin vs regular users) Modifying existing API structure Setting up authentication for API calls Creating type-safe API wrappers Core Principles 1. Single Source of Truth - All API URLs defined once in endpoints.ts 2. Type Safety - Full TypeScript coverage from params to responses 3. Role-Based Access - Separate clients for regular vs admin endpoints 4. Centralized Auth - Authentication handled automatically by clients 5. DRY Code - Reusable client functions, no duplicate endpoint definitions The 5-File System All API code lives in src/lib/api/ with exactly these files: File Purposes 1. endpoint-types.ts Define all TypeScript interfaces for API data Organize types by domain (e.g., audiences, instances, membership) Include param types, response types, and request body DTOs Provide utility types for extracting types See references/endpoint-types-pattern.md for detailed structure. 2. endpoints.ts Define all API endpoint URLs in one place Organize by feature/domain matching types Use functions that accept parameters and return URLs Support environment variable base URLs See references/endpoints-pattern.md for detailed structure. 3. api-client.ts Generic API client with automatic authentication Error parsing and handling Support for GET, POST, PUT, DELETE methods Server-side only ('use server') See references/api-client-pattern.md for implementation. 4. admin-api-client.ts Admin-specific API client Role validation (Admin/SuperAdmin groups) Permission checking functions Throws AdminAuthError if unauthorized See references/admin-api-client-pattern.md for implementation. 5. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/api-organization