integrate-anything

Files (3)

• LICENSE
• SKILL.md
• local.patch

SKILL.md (first lines)

# Self-Integration

Connect to external apps through the [Membrane](https://getmembrane.com) CLI.

## Activation and Composition

- Activate only when the task requires executing an external SaaS action and Membrane is available or explicitly requested.
- Defer explanation-only, SDK, direct API, and product-specific implementation work to a narrower vendor or integration skill.
- When composing with a vendor skill, use that skill to determine domain semantics or payload shape, but keep authentication and execution in Membrane.
- Before an ambiguous, destructive, or irreversible action, summarize the selected connection, target, and operation and obtain confirmation.

**Always route execution through Membrane.** Don't hit vendor APIs directly. Membrane proxies every request through an authenticated connection and injects the right auth headers — including transparent credential refresh.

**Never handle external-app credentials yourself.** OAuth tokens, API keys, refresh tokens — Membrane stores and manages them server-side. Pass a `connectionKey` (or `connectionId`) and the tools call the vendor on your behalf.

## Workflow

1. **Authenticate with Membrane** (one-time per machine).
2. **Ensure a connection** to the external app — find an existing one, reconnect a disconnected one, or create a new one.
3. **Use the connection** to run actions or call the app's API.

The rest of the skill is these three steps in detail.

## Authentication

```bash
npx @membranehq/cli login --tenant
```

`--tenant` gets a tenant-scoped token (workspace + customer) so you don't need to pass `--workspaceKey` and `--tenantKey` on every subsequent command.

The command opens a browser. In headless environments it prints an authorization URL — ask the user to open it, complete the flow, and paste the code back; finish with:

```bash
npx @membranehq/cli login complete <code>
```

Credentials are stored at `~/.membrane/credentials.json`. All later commands pick them up automatically.

If `npx` is awkward, install globally: `npm i -g @membranehq/cli@1.18.1` and use plain `membrane …`. Add `--json` to any command for machine-readable output.

## Step 1 — Get a connection

### 1a. Find an existing connection

```bash
npx @membranehq/cli connection list --json
```

Each connection carries `id`, `key`, `integrationKey`, `state`. Scan for the target app and branch on `state`:

- **`READY`** → use it. Skip to Step 2.
- **`CLIENT_ACTION_REQUIRED`** (disconnected, needs re-auth) → **reconnect the existing connection**, do NOT create a new one:

  ```bash
  npx @membranehq/cli connect --connectionId <id>
  ```

  Creating a fresh connection while the old one is `CLIENT_ACTION_REQUIRED` leaves orphaned records and breaks anything that referenced the old `connectionKey`. Always reconnect.
- **Multiple matches** (e.g. `slack-work` and `slack-personal`) → ask the user which to use. Don't guess.
- **No match** → create a new one (Step 1b).

### 1b. Create a new connection

By URL or domain — shortest path:

```bash
npx @membranehq/cli connection ensure "https://slack.com" --json
# also accepts a bare domain: "slack.com"
```

The URL is normalized to a domain and matched against known apps. If no app is found, one is created and a connector is built automatically.

To set a stable, human-readable key for later lookup (especially for multi-account setups like `slack-work` + `slack-personal`), set it after creation:

```bash
npx @membranehq/cli connection patch <id> --data '{"connectionKey":"slack-work"}'
```

For the explicit multi-connection case (creating a second connection to an app you already have connected), use `connect`:

```bash
npx @membranehq/cli connect --integrationKey slack \
  --connectionKey slack-personal --allowMultipleConnections
```

### 1c. Drive the connection to `READY`

After 1a's reconnect or 1b's create, read `state` and follow the state machine:

- **`READY`** — done. Move to Step 2.
- **`BUILDING`** — Membrane's builder agent is working. Wait:

  ```bash
  npx @membranehq/cli connection get <id> --wait --json
  ```

  `--wait` long-polls (up to `--timeout` seconds, default 30).
- **`CLIENT_ACTION_REQUIRED`** — the user or agent must do something. The `clientAction` object describes what:
  - `clientAction.type` — `"connect"` (auth flow) or `"provide-input"` (extra fields needed).
  - `clientAction.agentInstructions` (optional) — **follow these verbatim if present**. They tell the agent how to drive the provider side of the flow programmatically. Don't shortcut to "paste this URL" — the instructions exist because the agent is expected to handle it.
  - `clientAction.uiUrl` (optional) — a Membrane-hosted page where the user completes the action manually. Show this only when `agentInstructions` tells you to, or when no `agentInstructions` are present.
  - `clientAction.description` — human-readable summary.

  When the action requires writing data back to the connection (e.g. captured OAuth credentials, custom params):

  ```bash
  npx @membranehq/cli connection patch <id> --data '{"connectorParameters":{...},"input":{...}}'
  ```

  After the user completes their step, poll with `connection get <id> --wait --json` until `state` changes.
- **`CONFIGURATION_ERROR`** / **`SETUP_FAILED`** — surface the `error` field to the user. These are terminal — don't retry blindly.

## Step 2 — Use the connection

The fastest path to a real response is `act` with an inline dispatch. **No "create action → wait → run" ceremony required.**

`act` accepts exactly one of four dispatch styles:

From Kilo-Org/kilo-marketplace, Apache-2.0.

More from Kilo-Org/kilo-marketplace