integration-connector-setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# Integration Connector Setup

Use this when the user asks to connect Slack, Telegram, Signal, Notion, Spotify,
Home Assistant, Weather, or Trello, or to inspect available connectors.

## Principles

- Treat setup as an in-conversation flow with exact next steps from the DB connector manifest.
- Never ask the user to paste bot tokens, app tokens, passwords, or API secrets into chat. Token fields must be env var names.
- Use `connect_gmail` from the Gmail connector skill for Gmail OAuth; this skill covers manual/pairing channel connectors.
- Use `connect_life_integration` for Notion, Home Assistant, Weather, and Trello. Pass only environment variable names for secret fields. Never search ambient environment variables or paste secret values into tool arguments.
- Use `connect_spotify` for Spotify PKCE. Its app client ID is non-secret, but an environment value may be used only when the user explicitly names that environment variable. Register the exact loopback redirect URI returned by Hexis; Spotify does not accept `localhost`.
- Be explicit when a capability is planned rather than available for a given provider.
- Historical backfill is local memory ingestion and needs explicit user approval, even when the provider access is read-only. Queue it only for a connected connector, after the user asks to import history.
- After config is written or the user says env vars are set, call `verify_channel_integration` so the DB records the connection only when the channel worker's config truth resolves.

## Flow

1. Call `integration_setup_status` for the requested connector or for all connectors if the user asks what can be connected.
2. Call `start_integration_setup` with the least capabilities matching the user's request.
3. If the user provides channel settings, call `configure_channel_integration` only with env var names for token fields and non-secret allowlists or URLs.
4. Call `verify_channel_integration` after the env/config values should be available.
5. Tell the user to start or restart `hexis-channels` only if verification succeeded and the adapter is not already running.
6. If the user asks to import history, call `start_connector_backfill` with the smallest useful scope — Slack needs a `channel_id`; Telegram, Signal, and Twitter/X take a local export/archive path (`export_path`/`import_path`).
7. Use `connector_backfill_status` for progress, and `control_connector_backfill` only when the user asks to pause, resume, or cancel a job.
8. For an everyday-life API connector, call its connect tool once without missing fields to surface the provider-specific setup card; verify only after the user chooses the credential references or default location.
9. Use `complete_spotify_connection` only when the automatic local callback did not finish. Use `revoke_life_integration` when the user asks to disconnect one of these providers.

From QuixiAI/Hexis, MIT.

More from QuixiAI/Hexis