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":"[Truncated]","amber":"[Truncated]","red":"[Truncated]"},"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  POSTHOG_PROJECT_ID 
/env  POSTHOG_ENVIRONMENT_ID