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: - `messaging` (WhatsApp, Telegram, Discord, email) - `payments` (Stripe, Asaas, Pix, crypto) - `crm` (HubSpot, Salesforce, Pipedrive) - `social` (Instagram, LinkedIn, YouTube, TikTok) - `productivity` (Notion, Airtable, ClickUp, Linear) - `other` 4. **Description** — 1-2 sentences. What does this integration do? What would agents use it for? 5. **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). 6. **Auth method** (optional, guides the SKILL.md template body) — bearer token, API key in header, OAuth, basic auth, none. 7. **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: ```python 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: ```bash 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. ```python 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`.