posthog

Files (2)

• SKILL.md
• posthog.cjs

SKILL.md (first lines)

# 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:

```bash
/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:

```bash
hybridclaw secret set POSTHOG_PROJECT_TOKEN "<project-token>"
hybridclaw secret set POSTHOG_PERSONAL_API_KEY "<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 \

From HybridAIOne/hybridclaw, MIT.

More from HybridAIOne/hybridclaw