/posthog

name: posthog
description: "Capture PostHog events, update person properties, read persons, inspect feature flags, test flag evaluation, and run bounded analytics queries through gateway-managed secrets."
user-invocable: true
requires:
  bins:
    - node
credentials:
  - id: posthog-project-token
    kind: api_key
    required: true
    secret_ref:
      source: store
      id: POSTHOG_PROJECT_TOKEN
    scope: "PostHog public capture and flags endpoints on the configured ingestion host"
    how_to_obtain: "Open PostHog project settings and copy the project token. Set `POSTHOG_PROJECT_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set POSTHOG_PROJECT_TOKEN <token>` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set POSTHOG_PROJECT_TOKEN <token>`."
  - id: posthog-personal-api-key
    kind: bearer
    required: true
    secret_ref:
      source: store
      id: POSTHOG_PERSONAL_API_KEY
    scope: "PostHog private API for persons, feature flags, and query endpoints"
    how_to_obtain: "Create a PostHog personal API key with only the needed scopes. Set `POSTHOG_PERSONAL_API_KEY` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set POSTHOG_PERSONAL_API_KEY <key>` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set POSTHOG_PERSONAL_API_KEY <key>`."
config_variables:
  - id: posthog-host
    env: POSTHOG_HOST
    required: true
    scope: "PostHog app API host, for example https://us.posthog.com, https://eu.posthog.com, or a self-hosted base URL"
    how_to_obtain: "Use the base URL from your PostHog app and store it with `/env set POSTHOG_HOST \"https://us.posthog.com\"` or `hybridclaw env set POSTHOG_HOST \"https://us.posthog.com\"`."
  - id: posthog-ingest-host
    env: POSTHOG_INGEST_HOST
    required: true
    scope: "PostHog ingestion API host, for example https://us.i.posthog.com, https://eu.i.posthog.com, or a self-hosted base URL"
    how_to_obtain: "Use the ingestion host for your PostHog region and store it with `/env set POSTHOG_INGEST_HOST \"https://us.i.posthog.com\"` or `hybridclaw env set POSTHOG_INGEST_HOST \"https://us.i.posthog.com\"`."
  - id: posthog-project-id
    env: POSTHOG_PROJECT_ID
    required: true
    scope: "Numeric PostHog project id for private project APIs"
    how_to_obtain: "Find the numeric project id in PostHog project settings or API URLs, then store it with `/env set POSTHOG_PROJECT_ID \"12345\"` or `hybridclaw env set POSTHOG_PROJECT_ID \"12345\"`."
  - id: posthog-environment-id
    env: POSTHOG_ENVIRONMENT_ID
    required: false
    scope: "PostHog environment id for persons APIs when it differs from the project id"
    how_to_obtain: "Use the environment id shown in PostHog environment API URLs, then store it with `/env set POSTHOG_ENVIRONMENT_ID \"12345\"` or `hybridclaw env set POSTHOG_ENVIRONMENT_ID \"12345\"`. If omitted, pass `--environment-id` explicitly for persons calls."
metadata:
  hybridclaw:
    category: business
    short_description: "PostHog analytics, persons, and feature flag reads with guarded event writes."
    tags:
      - posthog
      - analytics
      - product-analytics
      - feature-flags
      - persons
      - hogql
    related_roadmap:
      - R21
      - R21.82
    issue: 1168
    stakes_tiers:
      green:
        - person-read
        - feature-flag-read
        - feature-flag-evaluation-test
        - insight-query
      amber:
        - event-capture
        - person-property-update
      red:
        - feature-flag-create-update-delete
        - person-delete
        - bulk-event-import
    escalation:
      writes: confirm-each
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_key: posthog

PostHog

Use this skill for PostHog product analytics work: event capture, person property reads and updates, feature flag inspection, feature flag test evaluation, and bounded insight/HogQL queries.

Scope

• capture a single product analytics event through the public capture endpoint
• update person properties with a guarded `$identify` capture event
• list and retrieve persons through the private persons API
• list and retrieve feature flag metadata
• test how a feature flag evaluates for a distinct id without changing the flag
• run private query API requests for HogQL, trends, funnels, retention, and

other PostHog query payloads

• classify common PostHog auth, permission, validation, and rate-limit errors
• measure skill run cost through normal HybridClaw `UsageTotals`

Out Of Scope

• creating, editing, rolling out, or deleting feature flags
• deleting persons or bulk deleting data
• bulk historical imports or migration-sized batch capture
• exporting large event/person tables on a schedule
• bypassing PostHog region, project, environment, or credential configuration

Credential Rules

PostHog has two credential rails:

• `POSTHOG_PROJECT_TOKEN` is the public project token used in capture payloads.
• `POSTHOG_PERSONAL_API_KEY` is a private bearer credential used for persons,

feature flags, and query endpoints.

Never paste either token into chat or helper arguments. The helper emits `<secret:POSTHOG_PROJECT_TOKEN>` inside capture JSON and `bearerSecretName: "POSTHOG_PERSONAL_API_KEY"` for private APIs, so the gateway injects credentials server-side.

Recommended setup order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set `POSTHOG_PROJECT_TOKEN` and `POSTHOG_PERSONAL_API_KEY`. 2. Browser `/chat` or TUI fallback:

/secret set POSTHOG_PROJECT_TOKEN <project-token>
/secret set POSTHOG_PERSONAL_API_KEY <personal-api-key>
/env set POSTHOG_HOST "https://us.posthog.com"
/env set POSTHOG_INGEST_HOST "https://us.i.posthog.com"
/env set POSTHOG_PROJECT_ID "12345"
/env set POSTHOG_ENVIRONMENT_ID "12345"

3. Local console fallback:

hybridclaw secre