What it does
The headline of a signup funnel is the share of first visits that end in an activated account. When it drops, the useful question is which step broke: the landing page, the signup form or onboarding. The answer is almost always in the step-by-step rates, not the total.
Every Monday the agent runs the same funnel definition through PostHog's query API, puts last week next to the week before, and names the step that moved most. Marketing sees whether the traffic converted; product sees whether new accounts reached the first useful moment.
How it works
- 1
1Define the steps
Step 1 is
$pageviewon the marketing site (properties.$host = 'example.com'), step 2 your signup event (oftenuser signed up), step 3 your activation event, for exampleproject createdorteammate invited. 2Run the funnel
POST /api/projects/:project_id/query/with aFunnelsQuery: aseriesof threeEventsNodes, adateRangefrom last Monday to Sunday,funnelsFilter: {"funnelWindowInterval": 7, "funnelWindowIntervalUnit": "day"}andfilterTestAccounts: true.- 3
3Compare at the same age
Compare with the counts this skill saved last Monday, not with a fresh run of the week before: a fresh run gives that week seven more days to convert. Save this week's counts to a small JSON file for next time.
- 4
4Find the step that moved
Work out visit to signup, signup to activation and visit to activation for both weeks, and name the step whose conversion changed most relative to last week, with the counts behind it.
- 5
5Post the funnel
Headline: visit to activation in percent. Glance: each step's rate with its change, and the number of signups.
Post it to the board
With
BRIEFKIN_TOKENset, the agent sends the result as one card that updates in place every run. Without it, you get the report in the chat.
Install and run it
Pick your agent, where the data comes from and how to schedule it; the commands below follow.
Install the skill
One command. It puts the SKILL.md in ~/.claude/skills and in ~/.agents/skills, which Codex, Cursor, Gemini CLI, Copilot CLI and OpenCode read too.
shell
curl -fsSL https://briefkin.dev/skills/posthog-signup-funnel/install | shRun it
Ask Claude Code:
prompt
Run the posthog-signup-funnel skillOr paste the prompt instead of installing:
prompt
Using PostHog's query API, run a funnel for last Monday to Sunday: $pageview on example.com, then my signup event, then my activation event, with a 7-day conversion window and test accounts filtered out. Give me the count at each step and the step-to-step and overall conversion. Compare with the week before using the numbers you saved last Monday if you have them, since a fresh re-run of that week gives it extra days to convert. Tell me which step moved most, by how much, and where I should look first.Put it on a schedule
Mondays at 8:30, from cron on any machine where Claude Code is signed in:
crontab
30 8 * * 1 claude -p "Run the posthog-signup-funnel skill"Add it with
crontab -e. A laptop asleep at that time runs it when it wakes if you use launchd or Task Scheduler instead; GitHub Actions works for the API route.Send it to your board
Connect Briefkin once with
curl -fsSL https://briefkin.dev/install | shand every run lands on your board as a stat tile. How setup works
View the SKILL.mdRaw file
SKILL.md---
name: posthog-signup-funnel
description: "Every Monday: visit to signup to activation conversion from PostHog for last week, against the week before, and the step that dropped. Use when the user asks for this, or when it runs on a schedule."
---
# PostHog signup funnel
Every Monday: visit to signup to activation conversion from PostHog for last week, against the week before, and the step that dropped.
The headline of a signup funnel is the share of first visits that end in an activated account. When it drops, the useful question is which step broke: the landing page, the signup form or onboarding. The answer is almost always in the step-by-step rates, not the total.
Every Monday the agent runs the same funnel definition through PostHog's query API, puts last week next to the week before, and names the step that moved most. Marketing sees whether the traffic converted; product sees whether new accounts reached the first useful moment.
## Two ways to get the data
Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used.
## Route A: API or MCP server
### What you need
- A PostHog personal API key with `query:read` (in `POSTHOG_API_KEY`), the project ID and host, or a PostHog MCP server.
- The names of your signup and activation events, exactly as they appear in PostHog.
If something is missing, say what and stop; do not invent numbers.
### Steps
1. **Define the steps**: Step 1 is `$pageview` on the marketing site (`properties.$host = 'example.com'`), step 2 your signup event (often `user signed up`), step 3 your activation event, for example `project created` or `teammate invited`.
2. **Run the funnel** (PostHog): `POST /api/projects/:project_id/query/` with a `FunnelsQuery`: a `series` of three `EventsNode`s, a `dateRange` from last Monday to Sunday, `funnelsFilter: {"funnelWindowInterval": 7, "funnelWindowIntervalUnit": "day"}` and `filterTestAccounts: true`.
3. **Compare at the same age**: Compare with the counts this skill saved last Monday, not with a fresh run of the week before: a fresh run gives that week seven more days to convert. Save this week's counts to a small JSON file for next time.
4. **Find the step that moved**: Work out visit to signup, signup to activation and visit to activation for both weeks, and name the step whose conversion changed most relative to last week, with the counts behind it.
5. **Post the funnel**: Headline: visit to activation in percent. Glance: each step's rate with its change, and the number of signups.
## Route B: the browser
### What you need
- Signed in to PostHog with access to the project; saving the insight needs an editor role on it.
If something is missing, say what and stop; do not invent numbers.
### Steps
Start at https://us.posthog.com/. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears.
1. **Open a funnel**: PostHog URLs include the project ID, so start at the home page (`eu.posthog.com` for EU projects), pick the project, then open **Product analytics**, click **New** and choose the **Funnels** tab.
2. **Define the steps**: Step 1: `$pageview` with a filter **Host** equals `example.com`. Step 2: your signup event. Step 3: your activation event, for example `project created`. Set the **conversion window** to **7 days** and turn on **Filter out internal and test users**.
3. **Set the week**: In the date picker choose a custom range from last Monday to last Sunday. Read the count under each step and the percentages between steps. Save the insight so next week you only change the dates.
4. **Compare at the same age**: Compare with the counts you noted last Monday, not with the funnel rerun for the week before, because a rerun gives that week extra days to convert. If there are no saved counts, run the previous week and say the comparison is unfair in that direction.
5. **Name the step that moved**: Visit to signup, signup to activation and visit to activation for both weeks, the step whose conversion changed most, and the counts behind it.
Note: Funnel percentages in the UI are rounded to one decimal; read the counts for anything close. A saved insight remembers the steps, so the weekly run is a date change and a read.
## The report
- **Visit to activation** last week, and the week before.
- **Each step**: counts and conversion for both weeks.
- **The step that moved**, with the counts behind it.
- One line on where to look first.
## Post it to Briefkin
When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on.
```bash
[ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
-H "authorization: Bearer $BRIEFKIN_TOKEN" \
-H "content-type: application/json" \
-d @- <<'JSON'
{
"v": 1,
"event_id": "posthog-signup-funnel/<date of this run, e.g. 2026-10-16>",
"item_key": "posthog-signup-funnel",
"project": "acme-web",
"source": "PostHog signup funnel skill",
"kind": "metric",
"title": "Visit to activation 2.1%, signup step down",
"metric": {
"label": "Visit to activation",
"value": 2.1,
"unit": "%",
"better": "higher",
"period_start": "<start of the period, ISO 8601>",
"period_end": "<end of the period, ISO 8601>"
},
"glance": {
"type": "Grid",
"props": {
"columns": 3
},
"children": [
{
"type": "Stat",
"props": {
"label": "Visit to signup",
"value": 3.9,
"unit": "%",
"delta": -20
}
},
{
"type": "Stat",
"props": {
"label": "Signup to activation",
"value": 53.9,
"unit": "%",
"delta": 5
}
},
{
"type": "Stat",
"props": {
"label": "Signups",
"value": 942,
"delta": -16
}
}
]
},
"widget": [
{
"type": "Table",
"props": {
"columns": [
"Step",
"Last week",
"Rate",
"Week before",
"Rate"
],
"align": [
"left",
"right",
"right",
"right",
"right"
],
"rows": [
[
"Visited the site",
24180,
"100%",
22940,
"100%"
],
[
"Signed up",
942,
"3.9%",
1124,
"4.9%"
],
[
"Activated",
508,
"53.9%",
574,
"51.1%"
]
]
}
},
{
"type": "Callout",
"props": {
"text": "Visit to signup fell from 4.9% to 3.9% on 5% more traffic, so the drop is on the signup page, not in onboarding.",
"tone": "warn"
}
}
],
"size": "md"
}
JSON
```
Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report.
Set `period_start` and `period_end` to the window the number covers: the tile names it from them ("Last 7 days", "Today", "This month"). For a count right now (open items, a balance), send `"period_label": ""` so no period shows; for another name, send it as `period_label` (at most 24 characters).
## Run it on a schedule
Suggested: Mondays at 8:30 (`30 8 * * 1`). From cron, with the agent signed in on that machine:
```bash
30 8 * * 1 claude -p "Run the posthog-signup-funnel skill"
# Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run
```
Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/posthog-signup-funnel#schedule
Source: https://briefkin.dev/skills/posthog-signup-funnel
What your agent needs
A PostHog personal API key with
query:read(inPOSTHOG_API_KEY), the project ID and host, or a PostHog MCP server.The names of your signup and activation events, exactly as they appear in PostHog.
Connecting PostHog
- PostHog MCP server, PostHog's official remote server at
https://mcp.posthog.com/mcp. Sign in with OAuth, or let the PostHog Wizard install it in your client; it routes to the US or EU cloud based on your account. Clients without OAuth can send a personal API key made with the MCP Server preset as a Bearer token (docs). - Query API with a personal API key. Create one in your PostHog account settings, store it in
POSTHOG_API_KEYwithPOSTHOG_PROJECT_IDandPOSTHOG_HOST(https://us.posthog.comorhttps://eu.posthog.com), and give it thequery:readscope, plusinsight:readorfeature_flag:readif the report uses them.
Add ?readonly=true to the MCP URL (or send x-posthog-read-only: true) to drop every tool that creates, updates or deletes; on the API, read scopes alone do the same.
Questions
Why not just re-run the week before for the comparison?
Because the funnel counts people who convert within 7 days of their visit. On Monday morning, Sunday's visitors have had a few hours; the week before, re-run today, has had eight days or more. The figure saved last Monday was measured at the same age, so the comparison is fair.
Can it split the funnel by traffic source?
Yes. Add breakdownFilter: {"breakdown": "$initial_utm_source", "breakdown_type": "person"} to the query and the report shows each source's conversion. Keep the top five sources and fold the rest into other.
Do I need Briefkin to use the PostHog signup funnel skill?
No. The skill runs with your own agent and gives you the report in the chat. With a Briefkin token set, each run also posts it to your board as a stat tile, so you can glance at it instead of asking again.
Which agents can run it?
Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot CLI, OpenCode, Windsurf and Amp all read SKILL.md files. The install command puts it in ~/.claude/skills and ~/.agents/skills, where they look. ChatGPT, the Claude app and Grok take the prompt instead. Pick your agent under "Install and run it" and the commands change to match.
Can it work without an API or MCP server, from my browser?
Yes. Switch the data source to "Your browser" and the steps change to the PostHog pages themselves: the agent opens us.posthog.com in a browser you are signed in to and reads the numbers off the page. Claude Code, Codex, Cursor, Claude app and ChatGPT can drive a browser out of the box; Gemini CLI, Copilot CLI and OpenCode need a Playwright or Chrome DevTools MCP server first. It is slower than the API and needs you signed in, so it suits a report you run by hand or from a scheduler on your own computer.