API Integration Builder Agent Skill

---
name: api-integration-builder
description: Build or update a third-party API integration. Use for SDKs, REST or GraphQL clients, OAuth, webhooks, sync jobs, and external service migrations.
---

# API Integration Builder

## Discovery

1. Find and read the provider's current official documentation for the exact endpoint, SDK version, authentication method, limits, and error model.
2. Inspect existing repository clients, environment conventions, schemas, and test patterns.
3. Define the local contract before wiring provider-specific details into application code.

## Implementation

- Keep provider code behind a small typed adapter.
- Validate request inputs and parse responses at the boundary.
- Never expose server credentials to client code or logs.
- Set explicit timeouts. Retry only transient, idempotent operations with exponential backoff and jitter.
- Use idempotency keys for retried writes when the provider supports them.
- Handle pagination, rate limits, partial results, expired credentials, and provider error bodies.
- Verify webhook signatures against the raw body before parsing or acting.
- Make webhook and sync processing idempotent and safe to replay.
- Preserve the provider's request ID in structured logs when available.

## Tests

- Unit test the adapter's success, validation, auth failure, rate limit, timeout, malformed response, and provider failure paths.
- Use recorded fixtures or mocks at the network boundary; never call production in automated tests.
- Add a clearly documented sandbox smoke test when available.

## Handoff

- Document required environment variables without values.
- State API version assumptions, setup steps, verification, and operational risks.