hamster-posthog-dashboards
Use this skill whenever the user asks to review, analyse, investigate, duplicate, or build a PostHog dashboard for Hamster Studio. Drives the workflow that turns a dashboard ID (or a request to build one) into a snapshot, an analysis report, and prioritised follow-ups. Captures the doc structure (`posthog-reports/`, `posthog-snapshots/`, `posthog-insights-scope.md`, `posthog-insights-progress.md`, `posthog-events-inventory.md`) and the scripts in `packages/glass-box/scripts/`.
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- hamster-posthog-dashboards
- version
- 1.0.0
- description
- Use this skill whenever the user asks to review, analyse, investigate, duplicate, or build a PostHog dashboard for Hamster Studio. Drives the workflow that turns a dashboard ID (or a request to build one) into a snapshot, an analysis report, and prioritised follow-ups. Captures the doc structure (`posthog-reports/`, `posthog-snapshots/`, `posthog-insights-scope.md`, `posthog-insights-progress.md`, `posthog-events-inventory.md`) and the scripts in `packages/glass-box/scripts/`.
03 SKILL.md 正文
hamster-posthog-dashboards
This skill is the contract between Claude and the PostHog dashboard analysis system in Hamster Studio. When the user references a dashboard ID, asks to "review," "investigate," "build," "duplicate," or "compare" a dashboard, or asks to spawn a follow-up analysis, follow the patterns below.
When to invoke
- "Review dashboard
<id>" / "look at dashboard<id>" / "what's in<id>?" - "Pull data from
<id>" / "compare against the spec" / "is this dashboard right?" - "Investigate
<finding>from the LLM cost dashboard" - "Duplicate dashboard
<id>to dev" / "promote this dashboard to prod" - "Build a new dashboard for
<topic>" - "What's our LLM cost looking like?" (implies pulling current data + writing/updating a report)
When NOT to invoke
- The user is talking about Mixpanel or Segment dashboards — this skill is PostHog-specific.
- The user is asking about analytics event instrumentation in code (use
hamster-analyticsinstead). - The user wants raw event-level data for one user to debug a bug — use the glass-box
PostHogClientdirectly viapackages/glass-box/replay/utils/posthog_client.pyrather than going through this skill's report workflow.
The doc structure (read before doing anything)
Five surfaces, each with one job:
| Surface | Purpose | Path |
|---|---|---|
| Spec | What dashboards we want, with PostHog AI prompts | docs/architecture/posthog-insights-scope.md |
| Inventory | Typed catalog + drift | docs/architecture/posthog-events-inventory.md |
| Status board | One row per dashboard with link to latest report | docs/architecture/posthog-insights-progress.md |
| Snapshots | Raw data — definitions + cached results from PostHog | docs/architecture/posthog-snapshots/<id>.{md,json} |
| Reports | Distilled analysis chains, per topic | packages/glass-box/data/posthog-reports/<topic>/<NNN>-<slug>.md |
Never put numbers or per-tile reviews in the spec or status board. They go in reports.
Never edit a snapshot file by hand. They are written by the inspector script.
Never edit a report after it has been issued (status action-items-issued or later). Write a new numbered report instead. Reports are append-only.
The full structure plus templates is documented in packages/glass-box/data/posthog-reports/README.md and the topic READMEs.
The scripts
Both live in packages/glass-box/scripts/ and use .env.<env> files populated by pnpm get-env-qa. Each needs POSTHOG_DASHBOARD_API_KEY (personal API key with dashboard:read, insight:read minimum; dashboard:write and insight:write for duplication) and POSTHOG_PROJECT_ID (or POSTHOG_PROD_PROJECT_ID).
inspect_posthog_dashboard.py — fetch + render
The primary tool. Pulls a dashboard via the dashboards API, which already returns each tile's cached computed result alongside the definition — so a single GET gives you both definitions and numbers. No HogQL execution needed.
cd packages/glass-box
uv run python scripts/inspect_posthog_dashboard.py --env <env> --dashboard-id <id>
Writes:
docs/architecture/posthog-snapshots/<id>.md— reviewable summary with HogQL results as markdown tables, Trends as per-series tables, Funnels as step-count tables. Definitions in collapsed<details>blocks.docs/architecture/posthog-snapshots/<id>.json— raw API response. Source of truth when extracting specific values;resultfield on each insight contains the cached numbers.
Flags:
--env <local|dev|tux|prod>(required)--dashboard-id <int>(required)--out <path>— override default md path--no-json— skip the.jsonsidecar (don't usually do this; the JSON is needed for value extraction)--no-results— definitions only, faster, smaller. Use for a sanity check before a full snapshot.--stdout— print to stdout instead of writing files. Use for quick eyeballing.
duplicate_posthog_dashboard.py — clone across environments
Recreates a dashboard (with all insight tiles) in a different PostHog project. Used to promote tux dashboards to prod, or to seed a new project. Idempotent — skips if a dashboard with the same name already exists in the target.
cd packages/glass-box
uv run python scripts/duplicate_posthog_dashboard.py \
--source <env> --target <env> --dashboard-id <id> [--target-name "..."] [--dry-run]
Limitations:
- Text tiles are skipped (warned).
- Tile layout is not replayed; PostHog falls back to default grid.
- Cross-project duplication recreates resources; the source dashboard is not modified.
What does NOT exist (yet — propose adding when needed)
- A "list dashboards in env X" command. Use the PostHog UI for discovery.
- A "search dashboards by name" command. Same.
- A "delete dashboard" command. Use the PostHog UI; investigation dashboards stay around.
- A direct HogQL execution helper for ad-hoc queries against a dashboard's underlying data. The
PostHogClientinpackages/glass-box/replay/utils/posthog_client.pyhas a.query(hogql)method — use it for one-off questions, not for tile data (tile data is already cached in the dashboard JSON).
The standard workflows
Workflow A — User gives Claude a new dashboard ID
- Run the inspector.
uv run python scripts/inspect_posthog_dashboard.py --env <env> --dashboard-id <id>frompackages/glass-box. - Read the snapshot. Open
docs/architecture/posthog-snapshots/<id>.mdand skim. Note the dashboard name, tile count, and which spec section it likely belongs to. - Identify the topic. Look at the dashboard name and tile content. Match against §1 of
posthog-insights-progress.md. If the dashboard maps to an existing topic (llm-cost,activation,monetization,tracking-quality, …), use that topic folder. If it doesn't, create a new topic folder underpackages/glass-box/data/posthog-reports/<topic>/with aREADME.mdbased on an existing one. - Determine the report number. Look in the topic folder for the highest existing
NNN-*.md. The new report isNNN+1. The first report in any chain is always001-baseline.md. - Write the report. Copy
packages/glass-box/data/posthog-reports/_TEMPLATE.mdinto the new file, fill in YAML frontmatter, then walk each tile and write findings. The frontmatterparent_reportisnonefor a baseline; it's the path to the previous report when a new one supersedes or extends it. - Update the topic README. Add a row to its "Reports" table; update the rolled-up "Open action items" with new P0/P1 entries.
- Update the status board. Edit
posthog-insights-progress.md§1 — update the row for the topic with the new report link, status, and P0/P1 counts. - If a finding implies a cross-cutting gap (instrumentation that affects multiple dashboards), add a row to
posthog-insights-progress.md§2 Cross-cutting instrumentation gaps.
Workflow B — User asks for a follow-up investigation
The user references a finding (e.g. "investigate F3 from llm-cost/001") or asks to "spawn a deeper look at X."
- Decide whether the investigation needs a new dashboard or just code reading. Code reading is cheaper — start there. Only spawn a dashboard if the question can't be answered from the code or existing snapshot.
- If code reading suffices: write a new numbered report in the same topic folder. Set
parent_reportto the originating report. Walk the code, document findings, propose actions. No new dashboard ID. - If a new dashboard is needed: ask PostHog AI to build it (use the spec doc's conventions block + a topic-specific prompt), wait for the user to provide the new dashboard ID, then run Workflow A. The new report's
parent_reportis the originating report. - Update the parent report's "Children" section to link to the new report.
- Update the topic README's investigation map — add the new report and any branches.
Workflow C — Dashboard revision applied
The user pasted Claude's revision prompt back into PostHog AI; the dashboard now has updated tiles.
- Re-snapshot. Same dashboard ID. The inspector overwrites the previous snapshot — that's fine; the prior analysis is preserved in the report.
- Decide: new report or update existing?
- If the revision materially changes the numbers (e.g. F1 in LLM cost/001 was a 5x understated headline — fixing it is material) → write a new report. Mark the previous report
supersededin its frontmatter and add the new path to itsChildrensection. - If the revision is cosmetic (axis label, decimal places) → update the existing report's "Decisions taken" section and bump the snapshot reference. Don't create a new report.
- Update the topic README and status board accordingly.
Workflow D — User asks to build a new dashboard for a topic that has no spec yet
- Don't invent a spec out of thin air. Push back to the user: "What's the question this dashboard should answer?" Get to a specific business question.
- Draft the §X spec section in
posthog-insights-scope.md. Use the existing §1.1–§1.4 as templates. Property reference, conventions block, exact tile prompt. - Have the user paste the prompt into PostHog AI and provide the resulting dashboard ID.
- Then run Workflow A to write the baseline report.
Workflow E — Promoting a dashboard tux → prod
- Confirm the dashboard is signed off — its latest report is
resolvedor all P0 items are closed. - Run the duplicator with
--dry-runfirst to see the plan. - Run for real. Note the new prod dashboard ID returned in the output.
- Update the topic README to record both IDs (active = prod, superseded = tux).
- Re-snapshot the new prod dashboard to capture its initial state. The first prod snapshot may have empty data because of ingestion lag — that's fine.
How to extract specific values from a snapshot JSON
When you need to compute something across tiles (e.g. "are Tile 18 and Tile 13 reporting the same total?"), don't re-render the markdown — go straight to the JSON.
import json
d = json.load(open('docs/architecture/posthog-snapshots/<id>.json'))
# Per tile:
for tile in d['tiles']:
insight = tile.get('insight') or {}
name = insight.get('name')
cols = insight.get('columns') # for HogQL tiles
result = insight.get('result') # for HogQL: list[list]; for Trends: list[dict]
last_refresh = insight.get('last_refresh')
src_kind = insight.get('query', {}).get('source', {}).get('kind')
For HogQL tiles, result is a list of rows; columns gives column names. For TrendsQuery tiles, result is a list of series dicts each with data, labels, days, count, aggregated_value, breakdown_value. For FunnelsQuery, the structure is similar but step counts live in count.
The report template — what each section is for
The full template is at packages/glass-box/data/posthog-reports/_TEMPLATE.md. Sections in priority order:
| Section | Job |
|---|---|
| YAML frontmatter | Machine-readable status, parent/child links, dashboard ID, env. |
| TL;DR | 2–3 sentences. The single conclusion. |
| Headline numbers | The 4–8 numbers that drive decisions. Not the full data dump. |
| Findings | Numbered (F1, F2, …) so other reports can reference them. Each has what / why / confidence / source tile. |
| Hypotheses | For medium- or low-confidence findings — list candidates and what would discriminate. |
| Actions | Code changes / dashboard revisions / new investigations / spec updates. Each with [P0/M] priority + effort tags. PostHog AI revisions include the exact prompt to paste. |
| Decisions taken | Append-only log. Useful when re-reading the chain. |
| Open questions | Things that need more data; if a question seeds a new investigation, link to its report. |
| Children | Reports spawned from this one. |
Common findings patterns and what they imply
These recur often enough to memorise.
| Pattern | What it usually means | Default action |
|---|---|---|
A breakdown chart shows only $$_posthog_breakdown_null_$$ and $$_posthog_breakdown_other_$$ |
Wrong breakdown property name, or the property is missing on most events | Verify property name in the JSON; fix in PostHog AI; if still broken, fall back to a HogQL table |
| Headline aggregate disagrees with a HogQL sum of the same data | TrendsQuery interval is set to a too-large bucket (month on -30d collapses to current month) |
Change interval to day or omit |
A HogQL tile coalesces a value to 'unknown' and 100% of rows show unknown |
The aliased property isn't being emitted at all (not just missing on some events) | Code-side fix on the OTel/event emission path; the dashboard is doing what it should |
$ai_generation event has distinct_id == $ai_trace_id |
Anonymous LLM call — context.userId wasn't passed to buildExperimentalTelemetry |
Plumb the user id; usually a withOperation or middleware gap |
| A typed event has zero call sites in apps but is in the catalog | Catalog drift — type was speculative or replaced. Decide retire vs wire up. | Update events inventory; either retire the type or implement |
Cross-references
- Property reference for
$ai_generationevents:docs/architecture/observability.md§2 +apps/ai/src/common/aisdk/sdk.tsbuildExperimentalTelemetry(). - Typed catalog:
packages/analytics/src/event-types.ts(source of truth) +docs/architecture/posthog-events-inventory.md(status of each). - Cost-emission migration debt:
gen_ai.cost.total_usd(horde) vsgen_ai.cost.total_tokens(apps/ai legacy, value is in USD). Tracked inposthog-insights-scope.md§1.4 conventions. - Skills you may invoke alongside this one:
hamster-analytics(for instrumentation patterns when a fix involves adding events),glass-box(for replay-based investigation against the same PostHog data).
Anti-patterns
- Editing an issued report retroactively to fix a finding. Append a new report or note in "Decisions taken." Never rewrite the analysis.
- Putting raw data tables in
posthog-insights-progress.md. That doc is a status board only. - Asking PostHog AI to build a dashboard without writing the spec section first. Push the user back to the spec.
- Re-running the inspector and committing the snapshot when no analysis was done. Snapshots are point-in-time; commit them only as part of a report.
- Skipping the topic README update when adding a report. The README is the chain index — out of date, the navigation breaks.
04 同仓库更多 Skills
writing-waterfall-requirements-documents
Write a waterfall requirements document: elicit, structure and review testable, traceable requirements, then baseline the specification before design.
writing-vision-and-values-statements
Write a V2MOM vision a reader can test and a ranked list of values that settles real tradeoffs, so the rest of the document has a clear anchor.
writing-system-prompts-for-claude
Write Claude prompts and CLAUDE.md files that supply exact inputs, scope the task, and define done so the first attempt can be checked.
writing-page-specific-website-copy
Website copywriting by page type: write homepage, landing page, pricing page and feature page copy that fits each page's visitor and single job.
writing-internal-press-releases
How to write an internal press release: the one-page working backwards press release that opens a PR/FAQ document before anything is built.
writing-email-sequences-that-sell
Email sequence copywriting for nurture and sales: give each email one job, write clear subject lines, and close with one specific call to action.