---
title: "Service Integration Skill"
source: https://docs.autohand.ai/guides/skills/service-integration
---

# Service Integration Skill

Build reliable integrations with external APIs and services, handling authentication, data transformation, and error recovery while following API best practices.

## Skill Definition

Copy the following content into `.autohand/skills/service-integration/SKILL.md`:

``` yaml
---
name: service-integration
description: Build integrations with external services and APIs. Use for connecting third-party platforms, handling webhooks, implementing OAuth flows, and data synchronization.
allowed-tools: read_file write_file run_command http_request
---

# Skill: Service integration

## Purpose

Build reliable integrations with external APIs and services, handling authentication, rate limiting, data transformation, and error recovery. This skill focuses on creating maintainable integration code that gracefully handles the realities of distributed systems.

## When to use this skill

- Connecting to **third-party APIs** (Stripe, Twilio, Slack, GitHub, etc.).
- Implementing **OAuth 2.0 flows** or other authentication mechanisms.
- Building **webhook handlers** for incoming events.
- Creating **data synchronization** between your system and external services.
- Generating **typed API clients** from OpenAPI specifications.

## Inputs

- **API documentation**: endpoints, authentication methods, request/response schemas.
- **Integration requirements**: what data to sync, which events to handle, expected workflows.
- **Credentials**: API keys, OAuth client IDs, webhook secrets (stored in environment variables).
- **Error handling requirements**: retry policies, fallback behaviors, alerting thresholds.

## Out of scope

- Creating new **authentication providers** or identity systems.
- Modifying **production credentials** or secrets directly.
- Integrations that require **vendor contracts** or legal agreements.
- Building **real-time streaming** connections without proper infrastructure.

## Conventions

- Store all credentials in **environment variables**, never in code.
- Use the project's **HTTP client library** (axios, fetch, got, etc.) consistently.
- Implement **exponential backoff** for retries with jitter.
- Create **typed interfaces** for all API responses.
- Log all API calls with **request IDs** for debugging.

## Required behavior

1. Read the API documentation and understand rate limits before implementation.
2. Implement proper **authentication** (OAuth, API keys, JWTs) with token refresh.
3. Add **error handling** for all HTTP status codes (4xx, 5xx, network errors).
4. Transform data between **external schemas and internal models**.
5. Implement **idempotency** for operations that can be retried.
6. Add **logging and metrics** for monitoring integration health.

## Required artifacts

- **API client module**: encapsulated HTTP calls with proper typing.
- **TypeScript interfaces**: for all request/response types.
- **Integration tests**: with mocked API responses.
- **Error handling**: custom error classes for different failure modes.
- **Documentation**: setup instructions, required environment variables.

## Implementation checklist

1. Review API documentation and identify endpoints needed.
2. Set up authentication and verify credentials work.
3. Create typed interfaces for API payloads.
4. Implement the API client with error handling.
5. Add retry logic with exponential backoff.
6. Implement rate limiting and request throttling.
7. Add webhook signature verification (if applicable).
8. Write integration tests with mocked responses.
9. Add logging and monitoring hooks.

## Verification

Run the standard validation commands (tests, lint, type checks). In addition:

- Verify authentication works with **valid and expired tokens**.
- Test error handling for **rate limits and server errors**.
- Confirm webhook handlers **validate signatures** correctly.
- Check that **sensitive data is not logged**.

The skill is complete when:

- All integration tests pass with mocked responses.
- Authentication and token refresh work correctly.
- Error handling covers all expected failure modes.
- Rate limiting is respected.

## Safety and escalation

- If an integration involves **payment processing or financial data**, get explicit security review.
- If the API has **destructive operations** (delete, modify), add confirmation steps.
- If you encounter **undocumented API behavior**, document it and flag for review.
- Never log **API keys, tokens, or secrets** even in error messages.
- If rate limits are consistently hit, **escalate before implementing workarounds**.
```

## Example usage

``` bash
# Build a Stripe integration
autohand --skill service-integration --prompt "Create a Stripe integration for processing payments and managing subscriptions"

# Add webhook handling
autohand --skill service-integration --prompt "Add a webhook endpoint for Stripe events with signature verification"

# Connect to Salesforce
autohand --skill service-integration --prompt "Build a Salesforce integration to sync customer data from our database"

# Generate API client
autohand --skill service-integration --prompt "Generate a typed API client for the OpenAI API with retry logic"

# OAuth implementation
autohand --skill service-integration --prompt "Implement GitHub OAuth login with token refresh"
```