api-connector-builder
0Build a new API connector or provider by matching the target repo's existing integration pattern exactly. Use when adding one more integration without inventing a second architecture.
237,82236,1220Updated 6d ago
General
Quick InstallView Source
git clone https://github.com/affaan-m/ECC.gitOverview
About This Skill
--- name: api-connector-builder description: Build a new API connector or provider by matching the target repo's existing integration pattern exactly. Use when adding one more integration without inventing a second architecture. metadata: origin: ECC direct-port adaptation version: "1.0.0" --- # API Connector Builder Use this when the job is to add a repo-native integration surface, not just a generic HTTP client. The point is to match the host repository's pattern: - connector layout - config schema - auth model - error handling - test style - registration/discovery wiring ## When to Use - "Build a Jira connector for this project" - "Add a Slack provider following the existing pattern" - "Create a new integration for this API" - "Build a plugin that matches the repo's connector style" ## Guardrails - do not invent a new integration architecture when the repo already has one - do not start from vendor docs alone; start from existing in-repo connectors first - do not stop at transport code if the repo expects registry wiring, tests, and docs - do not cargo-cult old connectors if the repo has a newer current pattern ## Workflow ### 1. Learn the house style Inspect at least 2 existing connectors/providers and map: - file layout - abstraction boundaries - config model - retry / pagination conventions - registry hooks - test fixtures and naming ### 2. Narrow the target integration Define only the surface the repo actually needs: - auth flow - key entities - core read/write operations - pagination and rate limits - webhook or polling model ### 3. Build in repo-native layers Typical slices: - config/schema - client/transport - mapping layer - connector/provider entrypoint - registration - tests ### 4. Validate against the source pattern The new connector should look obvious in the codebase, not imported from a different ecosystem. ## Reference Shapes ### Provider-style ```text providers/ existing_provider/ __init__.py provider.py config.py ``` ### Connector-style ```text integrations/ existing/ client.py models.py connector.py ``` ### TypeScript plugin-style ```text src/integrations/ existing/ index.ts client.ts types.ts test.ts ``` ## Quality Checklist - [ ] matches an existing in-repo integration pattern - [ ] config validation exists - [ ] auth and error handling are explicit - [ ] pagination/retry behavior follows repo norms - [ ] registry/discovery wiring is complete - [ ] tests mirror the host repo's style - [ ] docs/examples are updated if expected by the repo ## Related Skills - `backend-patterns` - `mcp-server-patterns` - `github-ops`
How to Use
[{"step":"Identify the target API and existing connector. Use [TARGET_API_NAME] and [EXISTING_CONNECTOR_NAME] in your prompt to specify which integration pattern to replicate.","tip":"Find the reference connector in your codebase (e.g., `github_connector.py` or `salesforce_connector.js`). Review its authentication, pagination, and error-handling logic."},{"step":"Gather the target API’s specifications. Provide [AUTH_TYPE] (e.g., OAuth2, API key), [BASE_URL_PATTERN] (e.g., `https://api.{company}.com/v2`), and [PAGINATION_METHOD] (e.g., cursor, offset) to the AI.","tip":"Check the API’s documentation for endpoints, rate limits, and required headers. For pagination, confirm whether it uses `after`/`before` cursors or `page`/`per_page` parameters."},{"step":"Specify the supported methods and edge cases. Include [SUPPORTED_METHODS] (e.g., `get_issues`, `create_issue`) and [ERROR_CASES] (e.g., 429 rate limits, 401 auth failures) to ensure the AI handles them correctly.","tip":"List methods you’ll use in your workflow (e.g., `get_users`, `update_ticket`). For errors, note status codes and expected retry behavior."},{"step":"Generate and validate the connector. Copy the AI’s output into your project, then test against the target API’s sandbox environment.","tip":"Compare the generated connector’s behavior with the reference connector using identical inputs. Verify pagination, authentication, and error handling match exactly."},{"step":"Integrate into your workflow. Replace the reference connector with the new one in your integration pipeline (e.g., Zapier, custom ETL, or CRM sync).","tip":"Use feature flags to roll out the new connector gradually. Monitor logs for mismatches in behavior (e.g., unexpected rate limits or missing fields)."}]
Setup & Installation
Quick Install
No install command available. Check the GitHub repository for manual installation instructions.
Alternative Install (Git Clone)
git clone https://github.com/affaan-m/ECC/tree/main/skills/api-connector-builderRequirements
- Claude Code or compatible AI agent
Quick Start Guide
1
Install the Skill
Copy the install command above and run it in your terminal.
2
Open Your AI Agent
Launch Claude Code, Cursor, or your preferred AI coding agent.
3
Try It Out
Use the prompt template or examples below to test the skill.
4
Customize
Adapt the skill to your specific use case and workflow.
Usage Examples
Prompt Template
Build an API connector for [TARGET_API_NAME] that exactly matches the integration pattern used in [EXISTING_CONNECTOR_NAME]. Use the same authentication method ([AUTH_TYPE]), base URL structure ([BASE_URL_PATTERN]), and pagination logic ([PAGINATION_METHOD]). Ensure the connector supports [SUPPORTED_METHODS] and handles [ERROR_CASES] identically to the reference connector. Provide the full implementation in [LANGUAGE_FRAMEWORK].
Example Output
Here’s a complete API connector for `Linear` (issue tracking) that replicates the integration pattern of our existing `GitHub` connector. Both use OAuth2 authentication with the same token refresh flow, paginate via cursor-based queries (with identical `after`/`before` parameters), and handle 429 rate limits by respecting `Retry-After` headers.
```python
import requests
from requests.auth import HTTPBasicAuth
from typing import Optional, Dict, List
class LinearAPIConnector:
def __init__(self, api_key: str, base_url: str = "https://api.linear.app/graphql"):
self.api_key = api_key
self.base_url = base_url
self.headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
def get_issues(self, after_cursor: Optional[str] = None) -> Dict:
"""Fetch issues with pagination matching GitHub's cursor pattern."""
query = """
query Issues($after: String) {
issues(first: 100, after: $after) {
edges {
node {
id
title
state
createdAt
}
cursor
}
pageInfo {
hasNextPage
endCursor
}
}
}
"""
variables = {"after": after_cursor} if after_cursor else {}
response = requests.post(
self.base_url,
json={"query": query, "variables": variables},
headers=self.headers
)
response.raise_for_status()
return response.json()
def handle_rate_limit(self, response: requests.Response) -> bool:
"""Check for 429 and retry after delay, identical to GitHub connector."""
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 60))
time.sleep(retry_after)
return True
return False
```
Key alignment points with the GitHub connector:
1. **OAuth2 Flow**: Uses `Bearer` token in headers (same as GitHub’s `token` header).
2. **Pagination**: Accepts `after` cursor and returns `pageInfo` with `hasNextPage`/`endCursor` (mirrors GitHub’s `pageInfo`).
3. **Error Handling**: Retries on 429 with `Retry-After` delay (no custom logic).
4. **Method Signatures**: `get_issues()` matches `get_issues()` in the GitHub connector, including optional `after_cursor`.
This ensures the Linear connector can replace the GitHub connector in our integration pipeline without architectural changes.Source repo
affaan-m/ecc
skills-collection
Find the right skills for your stack
Take a free 3-minute scan and get personalized AI skill recommendations.
Take free scan