SKILL.md

v1.0.0 · 2385 B · text/markdown

---
name: external-api-connector-guide
description: Use when a task needs to talk to an external SaaS API (Slack, GitHub, email, calendars, etc.) - a checklist for choosing auth strategy, scoping permissions, and handling failures safely
---

# External API Connector Guide

Wiring an agent up to a third-party API has predictable failure modes that
are easy to skip under time pressure. This skill is a checklist to run
before writing the integration code.

## Before writing any request code

1. **Check for an existing, official SDK/client library first** — hand-
rolled HTTP calls against a REST API tend to drift from the real
contract (pagination, rate limits, error shapes) that a maintained SDK
already handles correctly.
2. **Scope credentials to the minimum permission the task needs.** A
read-only task should never hold a write-capable token; a single-channel
Slack integration shouldn't request workspace-wide access.
3. **Never hardcode credentials or embed them in generated code** — read
from environment variables or a secrets manager, and confirm the
.gitignore actually excludes wherever they might land locally.

## Handling the request lifecycle

- **Rate limits are not exceptional cases** — assume they'll be hit and
handle 429s with backoff, not just a try/catch that surfaces an error to
the user.
- **Distinguish retryable failures (timeouts, 5xx, rate limits) from
permanent ones (4xx auth/validation errors)** — retrying a permanent
failure just wastes calls and can trigger stricter rate limiting.
- **Treat every external response as untrusted input** — validate shape
before using it, don't assume a documented schema is what actually comes
back.

## OAuth-specific

- Store refresh tokens securely, never in plaintext logs.
- Handle token expiry proactively (refresh before a call fails) rather than
reactively (catch the 401, then refresh, then retry) when the SDK
supports it — the reactive path still works but costs an extra round
trip on every expiry.

## When integrating multiple services

Keep each connector's auth/error-handling logic isolated per service rather
than one shared abstraction that has to accommodate every provider's
quirks — a shared interface for "call the external thing" is fine; a shared
implementation of auth/retry logic across genuinely different APIs usually
isn't.