Index of every page on this site: llms.txt
All skills
posthog avatar

/documenting-warehouse-sources

@028173b official
by posthogposthog/posthog41k stars
3,718
Run it yourself

Write or update the user-facing posthog.com documentation for a PostHog Data warehouse import source. Use when adding a new source doc, fixing an inconsistent or stub source doc, or standardizing the docs at contents/docs/cdp/sources. Covers the canonical template, shared snippets, the auto-rendered <SourceParameters /> and <SourceTables /> components, frontmatter, and the docsUrl/slug rule that prevents 404s.

Use this Skill: https://skilld.dev/gh/posthog/posthog/documenting-warehouse-sources

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈111 tokens for metadata: the name and description. ≈1.6k when used: this file.

Description uses 5.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈445 characters, or 5.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Documenting Data warehouse sources

User-facing source docs live in the posthog.com repo (not this one) at contents/docs/cdp/sources/<slug>.md, served at both /docs/cdp/sources/<slug> and /docs/data-warehouse/sources/<slug>. This skill defines the one consistent shape every source doc must follow. Pair it with /implementing-warehouse-sources when shipping a new source.

Assume a sibling posthog.com checkout (e.g. ../posthog.com).

The two things the website renders for you

You do not hand-write connection fields or the table list — both come from the public_source_configs API the site fetches at build time, mirrored into the doc via MDX components:

  • <SourceParameters /> renders the connection/config form fields from get_source_config.fields.
  • <SourceTables /> renders the Supported tables reference (table name, description, sync method, incremental field, primary key) from the source's get_documented_tables().

<SourceTables /> only has data when the source opts in by setting lists_tables_without_credentials = True on its source class (only valid when get_schemas iterates a static endpoint catalog with no I/O — see /implementing-warehouse-sources). Otherwise it renders a generic "discovered from your account" note. If a table is missing or its description is thin, fix the source code (settings.py endpoints + canonical_descriptions.py), not the doc — the doc just renders what the API returns, so the code stays the single source of truth.

Frontmatter

---
title: Linking <Source> as a source
sidebar: Docs
showTitle: true
availability: { free: full, selfServe: full, enterprise: full }
sourceId: <SourceKey> # MUST equal the source key (SourceConfig.name), e.g. ActiveCampaign, Stripe
---

sourceId is what links the doc to its API config (icon, fields, tables). Get it wrong and the doc renders with no <SourceParameters /> / <SourceTables /> data. It must be a real source key, the SourceConfig.name of the source (PascalCase, e.g. ActiveCampaign, not Active Campaign).

sourceId also drives the release-status callout and the nav badge: posthog.com reads the source's releaseStatus from the API and renders them itself. Don't add a status snippet, a status callout, or "this source is in beta" text, and don't set beta: in frontmatter — posthog.com CI rejects all of them.

Canonical template

---
title: Linking <Source> as a source
sidebar: Docs
showTitle: true
availability: { free: full, selfServe: full, enterprise: full }
sourceId: <EnumValue>
---

import SourceSetupIntro from "../_snippets/source-setup-intro.mdx"
import SyncModes from "../_snippets/sync-modes.mdx"
import TroubleshootingLink from "../_snippets/dw-troubleshooting-link.mdx"

One or two sentences: what this connector syncs and the typical use case.

## Prerequisites

Account tier / admin rights / API access the user needs before they can connect.

## Adding a data source

<SourceSetupIntro />

List the specific credentials this source needs and exactly where to get them (link to the provider's
dashboard). For sources with more than one auth method, use `###` subsections (mirror Stripe's
"Option 1 / Option 2").

## Sync modes

<SyncModes />

Add any source-specific recommendation here (e.g. "use webhooks for Stripe").

## Configuration

<SourceParameters />

## Supported tables

<SourceTables />

## Troubleshooting

Source-specific errors and fixes (optional but encouraged), then:

<TroubleshootingLink />

Essential sections (every source)

Intro → Prerequisites → Adding a data source → Sync modes → Configuration → Supported tables → Troubleshooting.

Optional sections (when applicable)

Webhooks (real-time sync), CDC (databases), Column selection, Row filters, Inbound IP addresses (<InboundIpAddresses />), data-type handling, known limitations, ERD/relationships. Reference implementations already in the repo: Stripe (SaaS + webhooks), Postgres (database + CDC), ClickHouse (database). Don't invent sections the source doesn't need.

Shared snippets

Reuse these instead of re-writing the same prose (they live in contents/docs/cdp/_snippets/):

  • source-setup-intro.mdx — the standard "Adding a data source" steps.
  • sync-modes.mdx — sync-mode summary linking to the canonical explanation.
  • dw-troubleshooting-link.mdx — the troubleshooting/support footer.
  • inbound-ip-addresses.mdx — IP allowlist table for DB sources.
  • feedback-questions.mdx — feedback/FAQ footer.

.md source docs support MDX import (e.g. convex.md, mongodb.md), so you don't need to rename to .mdx to use snippets — but .mdx is fine too. CalloutBox, ProductScreenshot, SourceParameters, and SourceTables are global components — no import needed.

docsUrl / slug rule (prevents 404s)

The website derives the doc slug from the source's docsUrl (its last /docs/cdp/sources/<slug> segment), so these three must agree:

  1. The doc filename: <slug>.md.
  2. The source's docsUrl in get_source_config: https://posthog.com/docs/cdp/sources/<slug>.
  3. (implicitly) the listing link — now derived from docsUrl, so it follows automatically.

Use kebab-case for multi-word slugs (active-campaign, not activecampaign). After writing or renaming a doc, run the audit from this (posthog) repo:

python manage.py audit_source_docs --docs-dir ../posthog.com/contents/docs/cdp/sources

It fails if any source docsUrl points at a missing file or any doc's sourceId isn't a real source. Renaming a published doc also needs a 301 in posthog.com/vercel.json for both /docs/cdp/sources/* and /docs/data-warehouse/sources/*.

Checklist

  • Frontmatter sourceId matches the source key (SourceConfig.name) exactly
  • Intro, Prerequisites, Adding a data source, Sync modes, Configuration, Supported tables, Troubleshooting
  • No status snippet, callout, or beta: frontmatter (posthog.com renders them from releaseStatus)
  • Shared snippets used instead of bespoke prose
  • <SourceParameters /> and <SourceTables /> present (don't hand-write fields or the table list)
  • If the rendered table list is empty/thin and the source is fixed-schema, enrich its code (lists_tables_without_credentials, settings.py, canonical_descriptions.py) — see /implementing-warehouse-sources
  • Filename, docsUrl, and slug all agree (kebab-case)
  • audit_source_docs passes

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts4mo3 checks · Risk SAFE
  • Gen Agent Trust Hub4mo

    This skill provides standardized templates and instructions for documenting PostHog data warehouse sources. It utilizes MDX components and a local audit script for validation. No security concerns were identified.

  • Socket4mo

    No alerts

  • Snyk4mo

    Risk: LOW · No issues

Signed by skilld at 028173b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago

README badge

README badge for posthog/posthog/documenting-warehouse-sources