Connection Setup Skill

Internal skill for managing app connection setup flows. Guides you through establishing connections to external services.

Connection Setup Guide

When helping users set up new skills that require app connections, follow this flow.

1. Check Existing Apps

List apps connected to this claw:

bridge apps list

2. Conduct Setup Conversation

Ask the user which setup method they prefer:

You create a new account using browser automation.

Pros: Fast, self-service
Cons: Requires payment method, may need verification codes
When to use: User wants you to handle everything

Manual Credentials

User provides username/password or API key.

Pros: Uses existing account
Cons: User must share credentials
When to use: User has existing account they want to use

1Password Retrieval

Retrieve credentials from password manager.

Check availability: op whoami
List vaults: op vault list --format json
Get item: op item get "Item Name" --vault VaultName --format json
When to use: Credentials already stored in 1Password

OAuth Flow

User authorizes via OAuth flow (if platform supports it). The Apps page provides one-click OAuth for Pipedream-backed services and select native integrations.

3. Execute Setup

Tell user what you'll do (e.g., "I'll sign up for a new Instacart account. I'll need a payment method.")
Use browser skill to navigate to signup page

bridge webhooks register email \
  --session-key "agent:${AGENT_ID}:dm:${USER_ID}" \
  --ttl 600 \
  --match-to "agent@workspace.workmate.ai" \
  --match-subject "verification|confirm|code"

Fill signup form and submit
Wait for webhook with verification code
Complete verification
Add payment from 1Password (if available) or ask user
Store the app (see step 4 below)

Manual Credentials Flow

Ask user: "Please provide your [Platform] email and password"
Receive credentials
Use browser to test login
Store the app (see step 4 below)

1Password Retrieval Flow

Check: op whoami
List vaults: op vault list
Search for item: op item list --vault Work | jq '.[] | select(.title | contains("Platform"))'
Get credentials: op item get "Platform Login" --vault Work --format json
Test credentials
Store the app (see step 4 below)

4. Store the App

When setup is complete, save the app via the bridge CLI. The JSON body follows the unified-apps create shape — the kind field discriminates:

bridge apps create --data '{
  "kind": "custom_keys",
  "slug": "instacart",
  "upstreamSlug": "instacart",
  "label": "Instacart",
  "scope": "private",
  "credentialFields": [
    { "name": "session_cookie", "value": "..." },
    { "name": "api_key", "value": "..." }
  ]
}'

Important:

Credential fields are encrypted automatically at rest.
kind is one of: custom_keys (API key / username+password), builtin_oauth (Google etc.), custom_mcp_oauth (custom MCP server), pipedream (broker-managed). For agent-driven signups, almost always custom_keys.
scope: "private" ties the app to the current claw's owner; scope: "team" shares with everyone on the team.
On a personal claw, omit scope to default to team. The current claw is auto-granted access.

5. Test the App

Verify credentials are present and OAuth tokens (if any) refresh:

bridge apps test instacart

Returns:

{
  "ok": true,
  "status": "ok",
  "message": "Credentials present"
}

If status is needs_attention, the app has no active credential — handle the error or retry setup.

6. Complete the Setup Attempt

At the end of setup, mark the attempt as complete using the SETUP_SESSION_KEY from the initial context message:

On success:

bridge skills complete --session-key "$SETUP_SESSION_KEY" --status success

On failure (e.g., user cancelled, credentials invalid):

bridge skills complete --session-key "$SETUP_SESSION_KEY" --status failed

This activates the skill for the user's team (on success) and records the outcome in the database.

Bridge CLI Reference

During setup, use these commands:

List apps: bridge apps list
Get app metadata: bridge apps get <slug>
Read credentials: bridge apps credentials <slug>
Create app: bridge apps create --data '{...}'
Test app: bridge apps test <slug>
Delete app: bridge apps delete <slug>

All credential data is automatically encrypted at rest.

User: "Set up Instacart for me"

Agent: "I'll sign up for a new Instacart account for you. I'll need a
payment method. Do you have a credit card in 1Password I can use?"

User: "Yes, use the Company Amex in the Work vault"

Agent:
1. Checks 1Password: `op item get "Company Amex" --vault Work`
2. Opens Instacart signup in browser
3. Registers webhook listener for verification email
4. Fills form with agent@workspace.workmate.ai
5. Waits for verification code (arrives via webhook)
6. Completes verification
7. Adds payment card from 1Password
8. Stores app: `bridge apps create --data '{"kind":"custom_keys","slug":"instacart","upstreamSlug":"instacart","label":"Instacart","credentialFields":[...]}'`
9. Tests it: `bridge apps test instacart`
10. Confirms: "✓ Instacart is set up and ready to use!"

Example: Manual Credentials

User: "I have an existing Notion account. Use that."

Agent: "I can use your existing Notion account. Please provide:
- Your Notion API key (from notion.so/my-integrations)"

User: "Here's the key: secret_..."

Agent:
1. Tests the API key with a simple Notion API call
2. Stores app: `bridge apps create --data '{"kind":"custom_keys","slug":"notion","upstreamSlug":"notion","label":"Notion","credentialFields":[{"name":"api_key","value":"secret_..."}]}'`
3. Confirms: "✓ Notion is connected!"

Example: 1Password Retrieval

User: "Use the GitHub token from 1Password"

Agent:
1. Checks: `op whoami` (confirms 1Password is available)
2. Lists: `op vault list` (shows Work, Personal)
3. Searches: `op item list --vault Work | grep -i github`
4. Finds "GitHub Personal Access Token" item
5. Gets credentials: `op item get "GitHub Personal Access Token" --vault Work`
6. Tests the token with a simple GitHub API call
7. Stores app: `bridge apps create --data '{"kind":"custom_keys","slug":"github","upstreamSlug":"github","label":"GitHub","credentialFields":[{"name":"api_key","value":"ghp_..."}]}'`
8. Confirms: "✓ GitHub is connected!"

Note: Slack is not set up through this skill. It uses a dedicated OAuth flow (/apps/slack/setup) and lives in the slack_connections table, not the unified apps table. The bridge will reject bridge apps create calls for slug slack.