How to use the API Integration Architect agent skill

What the skill makes the agent do

When the skill is active, the agent behaves like a senior integration engineer whenever you ask it to connect to an external API. It treats the API contract (schema, auth, rate limits, pagination) as the starting point and aims for resilience and observability by default.

The skill covers three kinds of task: designing an integration, implementing an API client, and debugging an existing integration. Each has its own procedure in the skill text.

• Design: asks discovery questions first, then outputs an architecture outline covering authentication, data flow, error handling, rate limit management and observability.
• Implement: generates a Python API client template built on httpx and asyncio, with retries and backoff, a concurrency limit and structured logs.
• Debug: walks through an eight-item checklist covering connectivity, authentication, request format, headers, rate limiting, response parsing, SSL/TLS and encoding.

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it. The skill is a single file, SKILL.md, so you need the folder that contains it. You can install it for yourself across projects or for one project only.

For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

You do not need a special command. Describe the integration in plain words and mention the API you want to connect to. The skill is written to ask for the API docs URL and the other discovery details before it writes code, so start with the goal.

Good requests name the service, the operations you need and any constraints you already know, such as a rate limit or an auth method. If you skip those, expect the agent to ask about them first.

• "Help me design an integration with the Stripe REST API to sync invoices. Use the architect approach."
• "Write a Python client for this GraphQL endpoint with retries and rate limit handling: [docs URL]"
• "My integration keeps getting 429 errors from the vendor. Walk me through debugging it."

Work through the discovery questions

For design tasks the skill asks these questions before writing code: which API and its docs URL, which operations are needed, the authentication method, rate limits, data volume, error handling requirements, and the environment (production, staging or dev).

Answering them up front gives you a better architecture. If you do not know an answer, say so and the agent can record it as an open item.

Use the architecture output and client template

The architecture output is a fixed template with sections for authentication, data flow, error handling, rate limit management and observability. The client template is a Python class named APIClient. It takes a base URL and API key, sends the key as a Bearer header, retries GET-type requests with backoff, honours a Retry-After header on 429 responses, and logs each request with a correlation ID.

Treat the generated code as a starting point. The skill notes that the code may differ from the template, so check it against the API's own documentation before you rely on it.

• The client rejects paths that are not same-origin relative paths such as /v1/items.
• Only GET, HEAD and OPTIONS requests are retried; other methods make one attempt.
• The concurrency cap is a semaphore limit on simultaneous requests, not a requests-per-second limit.

Safety notes before you run anything

The skill itself runs no scripts and makes no network calls. It is instruction text plus a code template. The code it helps you write, however, will make real requests with your credentials, so review it before running it against production.

The template passes API keys as bearer headers. The skill also says never to store secrets in code, and the agent may write code that needs careful secret handling. Keep keys in environment variables or a secret store, and use the narrowest scope the API allows. The debugging checklist mentions verify=False for testing SSL problems; use that only for local diagnosis, never in production.

• Requires Python with httpx and asyncio for the provided template; the generated code may differ.
• Requires credentials for the API you integrate, such as an API key or OAuth2 client.
• Do not put real keys in code or in prompts you share.

Tips for better results

Give the agent the real docs URL and the rate limit numbers from the vendor. The architecture and retry settings depend on them, and the skill checks X-RateLimit-* headers when debugging.

For debugging, paste the status code, response body and the request you sent (with secrets removed). The checklist runs in order, so the agent can usually find the failing step from that evidence.

• Start with the debugging checklist order: connectivity, auth, request format, headers, rate limits, parsing, TLS, encoding.
• For quick one-off scripts, skip the design phase and say so directly.
• Ask for the architecture outline first if the team needs a written design before coding.