/skill

API Connector Builder

Adapted from ECC. Full credit goes to the original author.

Use this skill to add an API link that feels native to the repo. Do not use it to build a general HTTP client.

Match the repo's rules for:

• File layout
• Config and secrets
• Login and auth
• Data types and field maps
• Errors and logs
• Retry and page rules
• Tests
• Setup and registry links
• Docs and examples

When to use it

Use this skill for requests like:

• "Build a Jira connector for this project."
• "Add a Slack provider that follows the current pattern."
• "Add support for this API."
• "Build a plugin that matches this repo."

Do not use it when the repo has no integration system and the user wants a new one. That task needs a wider design plan.

Rules

• Read the repo before you write code.
• Study at least two recent connectors when two exist.
• Use the newest active pattern. Old code may be out of date.
• Do not copy a vendor sample without fitting it to the repo.
• Do not make a new base class, registry, or config system unless the current design needs it.
• Build only the API parts the user needs.
• Finish all needed setup, tests, and docs. Do not stop at the HTTP code.
• Keep secrets out of code, tests, logs, and saved files.
• Do not add tracking, usage reports, or hidden network calls.
• Do not change old connector behavior unless the task asks for it.
• Ask before making a breaking config or data change.

Steps

1. Learn the repo style

Find the main connector folder and inspect at least two active connectors.

Write down:

• Folder and file names
• Main interface or base class
• Config shape and checks
• How secrets are loaded
• Auth flow
• Request and response types
• Data mapping rules
• Error types and messages
• Log style
• Timeout and retry rules
• Page handling
• Registry or import hooks
• Test names, mocks, and fixtures
• Docs and sample config

If only one connector exists, use it with the main app code and tests. If no connector exists, stop and tell the user that the repo has no clear pattern.

2. Set the scope

List the smallest useful API surface:

• Auth method
• Main data items
• Read actions
• Write actions
• Search or filter needs
• Page rules
• Rate limits
• Webhooks or polling
• Needed config fields

Do not add every vendor endpoint.

Check these cases when they apply:

• API keys, OAuth, or more than one auth mode
• Empty pages and missing page tokens
• Rate limit replies
• Timeouts and short network faults
• Bad JSON or missing fields
• Deleted or hidden records
• Partial batch failures
• Duplicate webhook events
• Webhook signature checks
• Token refresh and expired tokens
• Different API versions
• Test and live server URLs

3. Build the native layers

Use the same layers as nearby connectors. Common layers are:

• Config and checks
• Client and request code
• API types
• Field mapping
• Connector entry point
• Registry or discovery setup
• Tests
• Docs and sample config

Reuse shared request, retry, auth, and error tools from the repo. Do not copy them into the new connector.

Keep vendor data at the client edge. Map it into the repo's own types before the rest of the app uses it.

4. Handle errors with care

Follow the repo's error style.

At a minimum:

• Set a timeout.
• Retry only safe faults allowed by the repo.
• Honor rate limit wait data when the repo supports it.
• Do not retry bad auth or bad input without a clear reason.
• Keep the first useful error cause.
• Never put keys, tokens, or full secret headers in errors or logs.
• Make page loops stop when a token repeats or no progress is made.

For write calls, do not retry unless the call is safe to repeat or uses a unique request key.

5. Add tests

Match the repo's test tools and names.

Test:

• Valid config
• Missing or bad config
• Auth headers or token use
• One good request
• Data mapping
• More than one page
• Empty results
• API errors
• Rate limits or retries
• Timeouts
• Bad response data
• Registry discovery

Use mocks or the repo's test server. Do not call the real vendor API in tests.

Add webhook tests when used:

• Good signature
• Bad signature
• Duplicate event
• Missing fields

6. Check the full link

Run the same checks used by nearby connectors:

• Format
• Type check
• Unit tests
• Connector tests
• Build
• Registry or discovery check

Read the final change as a whole. It should look like it has always belonged in the repo.

Example

Task: "Add a GitHub issues connector."

1. Read the two newest connectors in the repo.
2. Find the shared client, config type, error type, and registry.
3. Set a small scope: list issues, get one issue, and create one issue.
4. Add token, owner, and repo to the normal config shape.
5. Use the shared HTTP and retry code.
6. Map GitHub issue data into the repo's issue type.
7. Follow link headers or page tokens using the repo's page style.
8. Add the connector to the current registry.
9. Test auth, mapping, pages, empty results, rate limits, and errors.
10. Update the same docs and sample config used by other connectors.

Do not add pull requests, comments, webhooks, or broad GitHub support unless the task needs them.

Common shapes

Provider style

providers/
  existing_provider/
    __init__.py
    provider.py
    config.py

Connector style

integrations/
  existing/
    client.py
    models.py
    connector.py

TypeScript plugin style

src/integrations/
  existing/
    index.ts
    client.ts
    types.ts
    test.ts

These are examples only. Use the repo's real shape.

Done checklist

• Matches a current connector pattern
• Has config checks
• Keeps secrets safe
• Has clear auth and error paths
• Follows repo rules for timeouts, retries, and pages
• Stops unsafe or endless retries
• Maps vendor data into repo types
• Has full registry or discovery setup
• Tests match the repo style
• Tests do not call the real API
• Old connector behavior still works
• Docs and examples are updated when the repo expects them
• No tracking or hidden network calls were added

Related skills

• backend-patterns
• mcp-server-patterns
• github-ops