# Posthog > Capture PostHog events, update person properties, read persons, inspect feature flags, test flag evaluation, and run bounded analytics queries through gateway-managed secrets. - Skill: `hybridaione/posthog` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add hybridaione/posthog` - Raw SKILL.md: https://api.skillmd.com/api/skills/hybridaione/posthog/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Data & Analytics - Author: HybridAIOne (https://skillmd.com/u/hybridaione) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/hybridaione/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 `` 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: ```bash /secret set POSTHOG_PROJECT_TOKEN /secret set POSTHOG_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: ```bash hybridclaw secret set POSTHOG_PROJECT_TOKEN "" hybridclaw secret set POSTHOG_PERSONAL_API_KEY "" hybridclaw env set POSTHOG_HOST "https://us.posthog.com" hybridclaw env set POSTHOG_INGEST_HOST "https://us.i.posthog.com" hybridclaw env set POSTHOG_PROJECT_ID "12345" hybridclaw env set POSTHOG_ENVIRONMENT_ID "12345" ``` Use the right regional hosts. For PostHog US Cloud, private API calls use `https://us.posthog.com` and capture calls use `https://us.i.posthog.com`. For EU Cloud, use `https://eu.posthog.com` and `https://eu.i.posthog.com`. For self-hosted deployments, use the self-hosted base URL for both when that is how the instance is exposed. ## Default Workflow 1. Use `plan` for natural-language requests when you need to classify read vs write risk before executing. 2. Run the bundled helper for live PostHog calls so request construction, gateway submission, credentials, and error interpretation stay in one place: ```bash node skills/posthog/posthog.cjs --format json run ... ``` 3. Use `http-request` only when you need to inspect the generated request or when a runtime exposes the built-in `http_request` tool but cannot run the helper against the gateway directly: ```bash node skills/posthog/posthog.cjs --format json http-request ... ``` 4. Pass only the emitted `httpRequest` object to the built-in `http_request` tool in that fallback path. Do not handcraft PostHog API calls from memory. 5. For amber operations, run `approval-plan` first, get explicit operator confirmation, then rerun the exact helper command with `--operator-grant`. 6. Keep capture payloads small and business-relevant. Do not send passwords, access tokens, full message bodies, contracts, or raw support transcripts as event/person properties. 7. If a live PostHog call returns 401 or 403, stop after that first failure and ask the operator to verify the matching stored credential and scopes. 8. If a private response is paginated and includes `next`, call the next URL only when the user needs another page. ## Command Contract Inspect the helper surface: ```bash node skills/posthog/posthog.cjs --help ``` Plan a request without contacting PostHog: ```bash node skills/posthog/posthog.cjs --format json plan "Show active flags for checkout" node skills/posthog/posthog.cjs --format json plan "Capture a trial_started event for user_123" ``` Build an approval plan for a capture write: ```bash node skills/posthog/posthog.cjs --format json approval-plan capture-event \ --event trial_started \ --distinct-id user_123 \ --properties-json '{"plan":"pro"}' ``` Capture a single event after explicit approval: ```bash node skills/posthog/posthog.cjs --format json run capture-event \ --event trial_started \ --distinct-id user_123 \ --properties-json '{"plan":"pro"}' \ --operator-grant node skills/posthog/posthog.cjs --format json http-request capture-event \ --event trial_started \ --distinct-id user_123 \ --properties-json '{"plan":"pro"}' \ --operator-grant ``` Update person properties after explicit approval: ```bash node skills/posthog/posthog.cjs --format json http-request identify-person \ --distinct-id user_123 \ --set-json '{"company":"Acme GmbH","plan":"pro"}' \ --operator-grant ``` Read persons: ```bash node skills/posthog/posthog.cjs --format json run list-persons \ --environment-id 12345 \ --search acme \ --limit 50 node skills/posthog/posthog.cjs --format json http-request get-person \ --environment-id 12345 \ --person-id 018f6c8f-... ``` Read feature flags and test evaluation: ```bash node skills/posthog/posthog.cjs --format json http-request list-feature-flags node skills/posthog/posthog.cjs --format json http-request get-feature-flag \ --flag-id 42 node skills/posthog/posthog.cjs --format json http-request test-feature-flag \ --flag-id 42 \ --distinct-id user_123 ``` Run an analytics query: ```bash node skills/posthog/posthog.cjs --format json http-request query \ --hogql "select event, count() from events where timestamp > now() - interval 7 day group by event order by count() desc limit 10" ``` Use `--query-json` for PostHog query payloads beyond HogQL: ```bash node skills/posthog/posthog.cjs --format json http-request query \ --query-json '{"kind":"TrendsQuery","series":[{"kind":"EventsNode","event":"$pageview"}]}' ``` Interpret a saved `http_request` error: ```bash node skills/posthog/posthog.cjs --format json explain-error --payload-file /tmp/posthog-error.json ```