suggesting-data-imports
Use when the user asks about revenue, payments, subscriptions, billing, CRM deals, support tickets, ad spend, production database tables, or other data PostHog does not collect natively — or wants to join or correlate PostHog product events with that external business data. Also use when a query fails because a table does not exist or returns no results for expected external data. The data warehouse can import from SaaS tools (Stripe, Hubspot, Zendesk, etc.), ad platforms, production databases (Postgres, MySQL, BigQuery, Snowflake), and other arbitrary data sources. Covers checking existing sources, identifying the right source type, and guiding the setup.
- Installs
- 208
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/posthog/ai-plugin --skill suggesting-data-imports- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads suggesting-data-imports automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Suggesting data imports
This skill helps identify when data the user needs lives outside PostHog and guides them toward importing it via the data warehouse. The key insight is recognizing the gap — then connecting it to the right source type.
What PostHog collects natively
PostHog collects product analytics events, persons, sessions, and groups via its SDKs. Additional products are available but must be enabled: session replay, feature flags, experiments, surveys, web analytics, error tracking, AI observability, conversations, logs, revenue analytics, workflows, CDP destinations, and batch exports. PostHog does not collect external business data like payments, subscriptions, CRM records, support tickets from other systems, or production database tables — that data must be imported via the data warehouse.
When to use this skill
- A HogQL query fails because a table doesn't exist
- The user asks about data from an external system (Stripe, Hubspot, Salesforce, etc.)
- The user wants to correlate PostHog analytics with business data (revenue, support tickets, CRM records, etc)
- The user asks "how do I get my X data into PostHog?"
- Analysis requires joining PostHog events with external data
- The user asks about exporting PostHog data for comparison elsewhere (in a google sheet, external warehouse, etc)
Workflow
1. Understand what data is missing
Listen for signals that the user needs external data:
- They mention a specific tool or system (Stripe, Hubspot, Zendesk, their production database, etc.)
- A query references a table that doesn't exist in PostHog
- They want to analyze something PostHog doesn't track natively (revenue, support tickets, CRM deals, etc.)
If a query failed, check the error — if it's "table not found" or similar, the data likely needs to be imported.
2. Check what's already connected
Call posthog:external-data-sources-list to see existing sources. The data might already be imported but the user doesn't know the table name or prefix.
If a source exists for the system they're asking about, call posthog:external-data-schemas-list to show the available tables. The data might be there but under a different name or prefix.
Also query system.information_schema.tables with posthog:execute-sql to see all queryable tables — the data might already be available as a view or joined table.
3. Identify the right source type
If the data isn't imported yet, call posthog:external-data-sources-wizard to see available source types — when
enumerating without source_type, pass fields: ['*.name', '*.caption'] to skip the large per-source config field
definitions. Match the user's need to a source:
Common patterns:
| User wants | Source type | Key tables |
|---|---|---|
| Revenue / payment data | Stripe, Chargebee, Shopify | charges, subscriptions, invoices, customers |
| CRM / sales pipeline | Hubspot, Salesforce, Attio | contacts, deals, companies |
| Support tickets | Zendesk | tickets, users, organizations |
| Product data from their DB | Postgres, MySQL, BigQuery, Snowflake, Redshift | user's own tables |
| Marketing / ads | Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads | campaigns, ad_groups, ads |
| Email marketing | Mailchimp, Klaviyo | campaigns, lists, subscribers |
| Project management | Linear | issues, projects |
| Error tracking (external) | Sentry | issues, events |
4. Suggest the import
Present the recommendation concisely:
- What source type to connect
- What tables would become available
- How this enables the analysis they want
Example: "Your Stripe data isn't in PostHog yet. If you connect a Stripe source, you'll get tables like charges, subscriptions, and customers that you can join with PostHog events to analyze revenue by user behavior."
5. Offer to set up the source
If the user wants to proceed, the fastest path is the one-step data-warehouse-source-setup tool (validate creds →
discover tables → sync defaults → create, in one call), with data-warehouse-source-connect-link to collect
credentials securely in the browser rather than in chat. For anything beyond the happy path (hand-picking tables,
non-default sync types, webhooks, CDC), hand off to the setting-up-a-data-warehouse-source skill, which covers
the full flow, sync-type selection, webhook registration, and prefix guidance. Do not duplicate that workflow here.
6. Show what's possible after import
Once connected, help the user write their first query joining PostHog data with the imported data. Use posthog:execute-sql to demonstrate.
Common join patterns:
- Join Stripe customers with PostHog persons on email:
SELECT * FROM stripe_customers sc JOIN persons p ON sc.email = p.properties.$email - Join CRM deals with events: correlate product usage with sales outcomes
- Join support tickets with session recordings: find recordings for users who filed tickets
Important notes
- Don't guess table names. Always check
system.information_schema.tables(viaposthog:execute-sql) andposthog:external-data-schemas-listbefore saying data doesn't exist. - Check prefixes. Imported tables are often prefixed (e.g.
stripe_chargesnotcharges). The user might not know the prefix. - Collect credentials securely. Use
data-warehouse-source-connect-linkto hand the user a browser link — it opens a minimal connect page rendering the source's full connection form (OAuth or credentials, whichever the source offers) that stashes the details temporarily without creating the source. Afterwards pass{"credential_id": <id>}(discovered viadata-warehouse-stored-credentials-list) todata-warehouse-source-setup— stored credentials are single-use and expire after 24 hours. Don't collect passwords or OAuth tokens in chat. - Not all systems are supported. If the user's system isn't in the wizard list, suggest using Postgres/MySQL as a bridge if they can export to a database, or mention that custom sources can be requested.
- Connecting a source also documents it. After the first sync, PostHog automatically generates semantic descriptions for the imported tables and columns (from the source database's own column comments where present, plus an LLM pass using the table relationships and the team's business context). Those descriptions surface in
system.information_schema.columns(query it withposthog:execute-sql), so once a source is connected the agent can reason about what each column means and how tables join — not just their names and types. Mention this when recommending an import: connecting the source is what makes the data answerable.
Related tools
posthog:external-data-sources-list: Check existing source connectionsposthog:external-data-schemas-list: Check what tables are already importedposthog:execute-sqloversystem.information_schema.*: See all queryable tables including viewsposthog:external-data-sources-wizard: Get available source types (passfields: ['*.name', '*.caption']when enumerating)posthog:data-warehouse-source-connect-link: Get a secure browser/OAuth link to collect credentialsposthog:data-warehouse-source-setup: One-step create (validate, discover tables, apply sync defaults, create)posthog:execute-sql: Run queries to demonstrate what's possible
Related skills
setting-up-a-data-warehouse-source: Full source creation workflow — hand off here once the user decides to connect a source
FAQ
What does the suggesting-data-imports skill do?
Use when the user asks about revenue, payments, subscriptions, billing, CRM deals, support tickets, ad spend, production database tables, or other data PostHog does not collect natively — or wants to join or correlate PostHog product events with that external business data. Also use when a query fails because a table does not exist or returns no results for expected external data. The data warehouse can import from SaaS tools (Stripe, Hubspot, Zendesk, etc.), ad platforms, production databases (Postgres, MySQL, BigQuery, Snowflake), and other arbitrary data sources. Covers checking existing sources, identifying the right source type, and guiding the setup.
How do I install suggesting-data-imports?
Run npx skills add https://github.com/posthog/ai-plugin --skill suggesting-data-imports in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/suggesting-data-imports/ (personal) or .claude/skills/suggesting-data-imports/ (project).
Which AI agents can use suggesting-data-imports?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is suggesting-data-imports safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains suggesting-data-imports?
It is published by posthog in posthog/ai-plugin, and it is an official skill from the maker of the technology it covers. It has 208 recorded installs.
More from posthog/ai-plugin
instrument-product-analytics
posthog/ai-plugin
Add PostHog product analytics events to track user behavior. Use after implementing new features or reviewing PRs to ensure meaningful user actions are captured. Also handles initial PostHog SDK setup if not yet installed.
instrument-feature-flags
posthog/ai-plugin
Add PostHog feature flags to gate new functionality. Use after implementing features or reviewing PRs to ensure safe rollouts with feature flag controls. Also handles initial PostHog SDK setup if not yet installed.
cleaning-up-stale-feature-flags
posthog/ai-plugin
Identify stale feature flags in a PostHog project and clean up the code that checks them. Use when the user wants to find, audit, or remove unused, fully rolled out, or abandoned feature flags, run a feature flag hygiene review or a weekly cleanup, reduce feature flag tech debt, or asks "which flags can I remove?". When the agent can read and edit a repository it performs the code cleanup itself: tested local changes, and one draft PR per flag when the user authorizes publishing. Agents without repository access generate a tailored cleanup prompt instead. Covers staleness detection, dependency checking, retained-path rules, and the code-first ordering. This skill does not archive or otherwise change a flag in PostHog.
auditing-experiments-flags
posthog/ai-plugin
Audit PostHog experiments and feature flags for configuration issues, staleness, and best-practice violations. Read when the user asks to audit, health-check, or review experiments or feature flags, check flag hygiene, or verify experiment setup.
querying-posthog-data
posthog/ai-plugin
Explains how to query PostHog data, defaulting to typed runners for supported product analytics. Read it before you write HogQL/SQL. Also read it before you call execute-sql against PostHog. Use it to find or aggregate PostHog entities. These entities include insights, dashboards, cohorts, feature flags, experiments, surveys, hog flows, warehouse data, and persons. Use it for trends, funnels, retention, lifecycle, paths, stickiness, web analytics, error tracking, logs, sessions, and LLM traces. Before you calculate a governed business or telemetry measure, check system.informationschema.metrics for an approved definition. Examples include MRR, activation, billable usage, active organizations, and failure rates. Use the approved definition before you derive a measure from raw events or use a typed domain tool. It also covers HogQL differences, system table schemas, functions, query examples, and schema discovery.
creating-experiments
posthog/ai-plugin
Guides agents through experiment creation: reading the project's setup with experiment-setup-context, defining the hypothesis, configuring rollout and bucketing, setting up analytics and running time, and reporting which choices are guesses. Delegates rollout decisions to configuring-experiment-rollout and metric setup to configuring-experiment-analytics. TRIGGER when: user asks to create a new experiment or A/B test, OR when you are about to call experiment-create. DO NOT TRIGGER when: user is updating an existing experiment, managing lifecycle, or only browsing experiments.
Popular data & databases skills
supabase-postgres-best-practices
supabase/agent-skills
Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pgcron, pgmq), vector/semantic search (pgvector), and restoring dumps (pgrestore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.
prisma-client-api
prisma/skills
Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".
prisma-database-setup
prisma/skills
Deprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.
prisma-cli
prisma/skills
Prisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.
prisma-postgres
prisma/skills
Deprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.
prisma-driver-adapter-implementation
prisma/skills
Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.