SKILL.md · 24000
destination (is_posthog_warehouse in external-data-destinations-list), the source may write there by
default, and attaching would stop its PostHog tables updating. If the user wants to keep them, call
external-data-sources-destinations-update with that same list before step 6: it makes the warehouse an
explicit link. Skip that call while any destination in external-data-destinations-list is paused, because it
would delete a hidden link to that destination. Tell the user instead. When destination_ids is empty, tell
the user the PostHog tables stop updating.
- Tables with their own destination override keep it and ignore the new source link. Call
external-data-schemas-destinations-retrievefor the source's tables. Those withinherits_from_source: falsewill not reach the new destination.
- Call
external-data-destinations-add-sourceswith the source ids. A source that has already synced sends only new rows to the destination. Offerresync: trueto copy the history, and say that a resync re-reads every row (including overridden tables that do not reach the new destination) and bills every destination the source writes to.
If a destination shows status: "failing" or "paused", run external-data-destinations-test-connection and relay
the message of the first failed step. Redshift has no test: relay latest_error from
external-data-destinations-retrieve instead. The test only reports. A paused destination stays paused until the user
fixes the problem and saves it on the warehouse destinations page.
Important notes
- Always validate creds with db-schema before create. The create endpoint will accept invalid creds and then fail
asynchronously — the source appears in the list with status
Errorand no tables. Skipping the validation step just pushes the failure into the background. - Present the table list before creating. Large databases may have hundreds of tables. Don't auto-select them all — row counts and relevance matter for billing. Let the user opt in explicitly.
- Don't invent schemas. Every entry in the
schemasarray must correspond to a real table from the db-schema response. You can't "also add an orders table" unless db-schema found one. - A new source syncs to the PostHog warehouse. That is the default and it needs no setup: a source nobody
configured destinations for writes here and nowhere else. Some projects can also send a source's tables to their
own database (
external-data-sources-destinations-retrieveshows where a source writes, when the feature is on for the project). Setting that up is a separate step (see "Sending a source to the user's own warehouse") and never something to do as part of creating a source — adding a destination to a source that has already synced leaves it holding none of the history until the tables are resynced, and a resync bills every destination the source writes to. - Prefix is load-bearing. It's part of every HogQL query the user will ever write against these tables. Pick something short, descriptive, and not already taken.
- Prefer the secure connect-link for any credentials. Use
data-warehouse-source-connect-linkso the user authenticates in their browser — the connect page renders the source's full connection form (OAuth and credential options alike) and stores the result without creating the source. Don't collect OAuth tokens or database passwords in chat; pass thecredential_idreference to setup — source creation always happens through setup, not the UI. (An already-connected OAuth integration can also be passed directly via its id key, e.g.{"hubspot_integration_id": 123}.) - Webhooks are a separate step after create. Setting
sync_type: "webhook"on a schema doesn't register the webhook — thecreate-webhookcall does. Always follow create → create-webhook → webhook-info for webhook-type schemas, and never leave a webhook schema dangling without registration (it just won't receive events). - Webhook support is source-specific and sparse. Currently only Stripe implements
WebhookSource. Don't promise webhooks for Hubspot, Salesforce, or Postgres — they'll use polling sync. - Row counts drive billing. Warehouse syncing is metered by rows synced. A chatty 500M-row events table synced
hourly is very different from a 10k-row dimension table synced daily. Flag large tables and offer longer sync
frequencies (
sync_frequency: "24hour") as the default.