API Integration Spec Writer
Turns a description of two systems that need to talk to each other into a complete integration spec — auth method, data flow, sync logic, and failure handling.
API Integration Spec Writer is a free AI skill for api & integration building. Turns a description of two systems that need to talk to each other into a complete integration spec — auth method, data flow, sync logic, and failure handling. It works with Claude, ChatGPT, Cursor and is ready to use out of the box.
About this skill
API Integration Spec Writer takes a plain description of two systems that need to be connected (e.g. 'sync new Shopify orders into our internal fulfillment system') and produces a full technical integration spec: authentication approach, data flow direction, field mapping, sync frequency/triggering logic, and failure/retry handling. It's built for developers and technical product managers who need to scope an integration project before writing code, ensuring nothing critical (like idempotency or rate limits) gets missed.
What it does
Given a description of two systems and the desired data flow, the skill outputs an integration spec covering authentication, data flow direction, field mapping, sync triggering logic, and failure/retry/idempotency handling.
What is included
- Authentication approach recommendation
- Data flow direction and field mapping
- Sync triggering logic (webhook vs polling) with rationale
- Idempotency and failure/retry handling
- Rate limit and error handling considerations
How to use it
1. Download the SKILL.md file 2. Upload it to a new Claude conversation 3. Describe the two systems and what data needs to flow between them 4. Receive a complete technical integration spec
Examples
We need new orders from Shopify to automatically create fulfillment records in our internal warehouse system.
INTEGRATION SPEC: Shopify → Internal Warehouse System AUTHENTICATION: Shopify Admin API using OAuth 2.0 access token scoped to read_orders; store token securely in secrets manager, not in code. DATA FLOW: One-directional, Shopify → Warehouse System (no write-back to Shopify needed for this use case). TRIGGERING LOGIC: Use Shopify's orders/create webhook rather than polling — lower latency, avoids unnecessary API calls against Shopify's rate limits. FIELD MAPPING: Shopify order.id → Warehouse.external_order_id Shopify order.line_items → Warehouse.fulfillment_items Shopify order.shipping_address → Warehouse.destination IDEMPOTENCY: Use Shopify order ID as a unique key in the warehouse system to prevent duplicate fulfillment records if the webhook fires more than once (Shopify webhooks are at-least-once delivery). FAILURE HANDLING: If warehouse system is unavailable, queue the webhook payload and retry with exponential backoff (e.g. 1min, 5min, 30min); alert on 3 consecutive failures. RATE LIMITS: Shopify Admin API allows 2 requests/second on standard plans — batch or queue if processing volume could spike during sales events.
FAQ
What is this skill for?
How do I install it?
Does it write the actual integration code?
Does it know the actual API details of specific platforms like Shopify or Salesforce?
How is this different from just listing what data needs to move?
Can it spec integrations between two custom internal systems, not just known platforms?
Related Skills
API Integration Specification Builder
Turn an integration idea into a developer-ready API specification with data mappings, authentication, workflows, errors, security, and tests.
API Data Sync and Conflict Resolution Architect
Design reliable data synchronization with ownership, mapping, change detection, ordering, conflicts, idempotency, reconciliation, recovery, and observability.
Webhook Reliability and Delivery Architect
Design reliable webhook systems with signatures, retries, ordering, idempotency, backpressure, observability, replay, and consumer contracts.
Related Prompts
Cross-App Data Sync & Deduplication
Design reliable one-way or two-way synchronization between business apps with field ownership, conflict rules, deduplication, replay safety, and reconciliation.
Third-Party API Build Brief Generator
Turn a desired external integration into a scoped implementation brief covering contracts, secrets, retries, idempotency, limits, and fallback behavior.
Multi-Agent Workflow Architect
Design a complete multi-agent system architecture for a complex task, including agent roles, handoff logic, failure handling, and human checkpoints.
Related Articles
How to Use AI for API Integration Planning
Learn how to use AI to plan API integrations, map endpoints, handle authentication, validate data, design webhooks, and prepare safe implementation steps.