backend--api skill

Overview

This skill applies the Agent OS standard for backend API design and implementation. It codifies conventions for routes, handlers, request/response shapes, error handling, and TypeScript types to ensure consistent, maintainable APIs across services. Use it to align backend code with the shared Agent OS expectations.

How this skill works

The skill inspects API code and project structure to validate adherence to the Agent OS backend API standard. It checks route organization, TypeScript typings, input validation, error propagation, response formats, and documentation markers. When discrepancies are found, it reports specific deviations and suggests corrective changes to match the standard.

When to use it

• Starting a new backend service or API surface in this codebase.
• Refactoring routes, controllers, or middleware to match organizational conventions.
• Adding or updating endpoint request/response types in TypeScript.
• Implementing consistent error handling and HTTP status semantics.
• Onboarding contributors to ensure consistent API patterns.

Best practices

• Define clear TypeScript request and response interfaces for each endpoint.
• Centralize error types and convert internal errors to well-defined HTTP responses.
• Validate inputs at the boundary (request layer) and keep handlers pure and testable.
• Keep route files focused and use consistent naming and folder structure.
• Document endpoints with concise comments or schema annotations that the standard recognizes.

Example use cases

• Add a new POST /items endpoint: create types for body and response, add validation, and ensure proper 201/4xx responses.
• Refactor scattered validation logic into a shared middleware that matches the standard's approach.
• Audit an existing service to find endpoints that return inconsistent error shapes and fix them to the canonical format.
• Introduce a new DTO and update endpoints to use the DTO types for both input validation and outgoing responses.