create-integration

Create Custom Integration

Guide the user through creating a new custom integration — a wrapper around an external API or service that the workspace's agents can use.

What You're Building

A custom integration is a skill with the custom-int- prefix:

• Lives in .claude/skills/custom-int-{slug}/SKILL.md
• Gitignored (personal to the workspace, not shipped)
• Appears in the dashboard /integrations page under the "Custom Integrations" section
• Documents the env keys, auth method, and example calls so agents know how to use it

When to use

Use when the user wants to connect a new external API/service that isn't already in the core integration list (Stripe, Omie, Discord, Telegram, etc.). If the integration already exists as core (int-*), don't duplicate — extend or use the existing one.

Step 1: Understand the Integration

Ask the user (short, direct):

1. Display name — e.g., "Airtable", "Notion Databases", "Custom CRM". Human-readable.
2. Slug — kebab-case ID (e.g., airtable). Auto-suggest from display name, let them override. Must be [a-z0-9-]+ and not already taken.
3. Category — one of:
4. messaging (WhatsApp, Telegram, Discord, email)
5. payments (Stripe, Asaas, Pix, crypto)
6. crm (HubSpot, Salesforce, Pipedrive)
7. social (Instagram, LinkedIn, YouTube, TikTok)
8. productivity (Notion, Airtable, ClickUp, Linear)
9. other
10. Description — 1-2 sentences. What does this integration do? What would agents use it for?
11. Env keys — what environment variables are needed? Ex: AIRTABLE_API_KEY, AIRTABLE_BASE_ID. List names only (no values — the user adds those to .env later).
12. Auth method (optional, guides the SKILL.md template body) — bearer token, API key in header, OAuth, basic auth, none.
13. Base URL (optional) — the API's root URL. Helps generate example calls.

Step 2: Verify slug uniqueness

Check the existing integrations (core + custom) to make sure the slug isn't taken:

from dashboard.backend.sdk_client import evo
existing = evo.get("/api/integrations")
taken = [i["slug"] for i in existing]
if slug in taken or f"int-{slug}" in taken or f"custom-int-{slug}" in taken:
    # ask user for a different slug

Also grep the filesystem as a safety check:

ls .claude/skills/int-{slug} .claude/skills/custom-int-{slug} 2>/dev/null

Step 3: Call the API

Use from dashboard.backend.sdk_client import evo — auto-handles URL + auth.

import json
from dashboard.backend.sdk_client import evo
integration = evo.post("/api/integrations/custom", {
    "slug": "airtable",
    "displayName": "Airtable",
    "description": "Query and update Airtable bases. Use when agents need to read/write records in Airtable tables.",
    "category": "productivity",
    "envKeys": ["AIRTABLE_API_KEY", "AIRTABLE_BASE_ID"],
})
print(json.dumps(integration))

The backend creates .claude/skills/custom-int-{slug}/SKILL.md with a template that documents setup, env keys, and usage. Response shape matches the standard integration entry (with kind: "custom").

Step 4: Add env keys to .env

Remind the user to add the env keys to .env (locally) and, if deploying, to the production .env too:

AIRTABLE_API_KEY=<value>
AIRTABLE_BASE_ID=<value>

The dashboard shows the integration as "Not configured" until the env keys are set.

Step 5: Fill in the SKILL.md body

The backend creates a minimal template. The user (or an agent they delegate to) should flesh out the SKILL.md with:

• Auth details (how the API expects credentials)
• Base URL and common endpoints
• Example calls with from dashboard.backend.sdk_client import evo OR direct HTTP using requests / httpx
• Rate limits, quirks, response shapes

Offer to open the file for editing or to delegate to a specialist agent (e.g., @apex-architect for architecture review, @quill-writer for docs polish).

Step 6: Show what happens next

Explain to the user:

1. The integration now appears in /integrations → "Custom Integrations" section with a [Custom] badge
2. Agents can discover it via skill search (it's indexed as a skill)
3. Edit description/env keys anytime via the pencil icon on the card
4. Delete via the trash icon (removes the SKILL.md folder entirely)
5. The SKILL.md is gitignored — doesn't leak into the upstream repo

Notes

• If the user just wants to describe a local script (no external API), suggest create-routine or create-command instead.
• If the integration needs complex state (OAuth tokens, pagination cursors), recommend the user ask @apex-architect to design the adapter before filling in SKILL.md.
• Custom integrations share the same discoverability as core ones — mentioning them in an agent chat (@agent please call my airtable integration) works once the env is set.

Related: .claude/rules/integrations.md, .claude/rules/skills.md, create-agent, create-command.