authoring-error-tracking-alerts

Sets up an error-tracking alert that notifies Slack, a webhook, or Linear when an issue is first created, reopens, or starts spiking, picking the right trigger for how noisy the project already is.

WHEN TO USE

SCOPE

USE FOR

Get notified in Slack the moment a previously fixed error starts happening again.
Set up a starter set of error alerts right after turning on error tracking.
Route alerts for one specific error to a dedicated on-call channel or webhook.
Decide whether new-issue, reopened-issue, or spiking-issue is the right alert trigger.

NOT FOR

Tuning the spike detector's threshold, window, or multiplier — that isn't exposed here.
Investigating an issue that's actively firing — query it directly instead of adding an alert.
Setting up a volume-threshold alert on raw exception counts — that's a different kind of alert.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (10)

Authoring error tracking alerts

Authoring an error tracking alert is a routing problem, not a measurement problem. The trigger events already exist and fire on real conditions in the ingestion pipeline — your job is to pick the right trigger for the user's intent, dedupe against what's already configured, and wire a destination they can actually act on.

When to use this skill

The user asks to set up alerts / notifications for errors or exceptions in their project.
The user wants a starter set of alerts after enabling error tracking.
The user pastes an issue link and asks "notify me when this happens again" — usually _reopened with a per-issue property filter.

**When not to use this skill**

Tuning the spike detector itself (multiplier, window, threshold). That lives behind the spike detection config endpoint and is not exposed via MCP today.
Investigating an active incident — query the issue / its events directly via posthog:query-error-tracking-issue and posthog:query-error-tracking-issue-events instead of authoring more alerts mid-fire.
Configuring volume-threshold alerts (count of $exception events over a window). That's a logs-style alert and is not in scope here — error tracking alerts ride the lifecycle events instead.

Tools

Tool	Job	Where it fits
`posthog:error-tracking-alerts-list`	List existing alerts; dedupe before creating.	Step 2 — dedupe.
`posthog:integrations-list`	Find the user's Slack workspace id (filter by `kind=slack`).	Step 3 — pick channel.
`posthog:integrations-channels-retrieve`	List Slack channels for a workspace.	Step 3 — pick channel.
`posthog:error-tracking-alerts-create`	Create the alert (HogFunction with `type=internal_destination`).	Step 4 — ship.
`posthog:error-tracking-alerts-partial-update`	Toggle, rename, or modify an existing alert.	When tuning, not authoring.
`posthog:error-tracking-alerts-delete`	Soft-delete an alert.	When the user says "remove".

Trigger events — pick exactly one per alert

There are three lifecycle events. Each has a different "noise vs urgency" trade-off — picking the wrong one is the most common cause of alert fatigue here.

Event	Fires when	Use when
`$error_tracking_issue_created`	A brand-new issue first appears.	Small projects, or projects where every new error type is genuinely worth a look. Floods large/noisy projects.
`$error_tracking_issue_reopened`	A previously resolved issue starts emitting again.	Catch regressions on issues someone already triaged. The safest "I want to know if this comes back" trigger.
`$error_tracking_issue_spiking`	The spike detector flags abnormal volume on an issue.	Production projects with high baseline volume. Threshold/multiplier is shared across the project — check spike config before using.

If the user is vague ("alert me on errors"), default to _spiking. It's the most signal-dense trigger and the least likely to cause alert fatigue. Confirm explicitly before proceeding.

Workflow

1. Confirm intent

You need three things from the user before creating anything:

Which trigger event. If unspecified, recommend _spiking and ask for confirmation. Do not silently pick one.
Which channel. Slack channel name, webhook URL, Linear team, etc. Never hardcode a production channel. If the user says "the dev channel", ask for the exact channel id or name.
Which scope. All issues (most common), or scoped to a specific issue / exception type / assignee.

2. Dedupe against existing alerts

Call posthog:error-tracking-alerts-list. Filter the response client-side by filters.events[].id.

If an alert exists for the same event delivering to the same channel, stop. Tell the user it already exists and ask whether they want to change anything (in which case use error-tracking-alerts-partial-update) or skip.
Multiple alerts on the same event for the same channel produce duplicate Slack messages — the user almost never wants this.
Multiple alerts on the same event for different channels (e.g. one for #oncall, one for the oncall webhook) is fine and sometimes intentional. Confirm.

PostHog's "alerts configured" recommendation only inspects filters.events — adding per-issue filters.properties does not affect the status the recommendations card reports.

3. Pick the integration

For Slack:

posthog:integrations-list with kind=slack → pick the integration id (an integer).
posthog:integrations-channels-retrieve with that id → pick the channel id (e.g. C0123ABC). Channel names like "#oncall" are accepted but channel ids are preferred — they survive renames.

For webhook: the user supplies a single https:// URL. Refuse http:// URLs.

For Linear / GitHub / GitLab: confirm the integration is connected via posthog:integrations-list first, then ask the user which project / repository / team to file issues into.

4. Create the alert

Call posthog:error-tracking-alerts-create with:

{
  "type": "internal_destination",
  "template_id": "template-slack",
  "name": "<short, channel-attributed name>",
  "enabled": true,
  "filters": {
    "events": [{ "id": "$error_tracking_issue_created", "type": "events" }]
  },
  "inputs": {
    "slack_workspace": { "value": <slack_integration_id_int> },
    "channel": { "value": "<channel_id>" },
    "text": { "value": "..." },
    "blocks": { "value": [...] }
  }
}

The canonical Slack blocks payload for each event lives in references/block-templates.md. Copy the matching block verbatim — it matches the in-product alert wizard, so agent-created alerts look identical to UI-created ones.

For per-issue scoping — created / reopened only, spiking events carry no exception properties — add to filters:

"properties": [
  { "key": "$exception_issue_id", "value": "<issue_uuid>", "operator": "exact", "type": "event" }
]

Other useful property filters: $exception_types (exception class names, an array), name (issue title). See references/event-triggers.md for the full property surface per event.

5. Verify

Echo the alert back to the user with: name, trigger event (human-readable), destination, and a one-line preview of the message body. Do not echo Slack workspace ids or webhook URLs — those are sensitive. Tell the user how to disable: "you can pause this alert by setting enabled: false via error-tracking-alerts-partial-update or by toggling it in the destinations UI."

Naming convention

Use <trigger> · <channel> (auto) so the user can scan their alert list and spot agent-created entries. Examples:

Issue spiking · #oncall (auto)
Issue reopened · #regressions-webhook (auto)
Issue created · Linear/Eng (auto)

Do not use the issue title in the name — alerts can match many issues, and the title becomes stale once the issue evolves.

Token-economy rules

One posthog:error-tracking-alerts-list call up front, not per candidate.
Reuse a single integration lookup for multiple alerts going to the same workspace.
Confirm the channel / URL with the user before creating each alert. Never batch-create alerts to a destination the user has not explicitly named.
Cap iteration at 1 round per alert. If the user wants three alerts, that's three create calls — not three create calls per alert.

Output

Report what you did, in this shape:

For each shipped alert: name, trigger event, destination (channel name or webhook host — never the full URL), enabled state.
For each skipped alert: trigger + channel + why (already exists, user declined, missing integration).
Anything the user should do next: enable the spike detection config (if they picked _spiking and the detector hasn't been turned on), wire up source maps (so the alert's stack trace links resolve), or tune the alert filters after watching it for a day.

Related skills

triaging-error-issues — work out which issues actually matter before wiring alerts for them
investigating-error-issue — deep-dive an issue an alert fired for
authoring-log-alerts — the same alerting job, but for log lines instead of exceptions

MCP connection required

1 FOR YOU

01
Connect the PostHog MCP
Connect the PostHog MCP server to a project with error tracking enabled, plus any Slack, webhook, or Linear integration you want to route to, so the skill can call the posthog:error-tracking-alerts-* and posthog:integrations-* tools.

This skill ships inside the PostHog AI Plugin. Listed package contents include 3 slash commands, 1 agent, hooks and an MCP server. Installed components and skill versions may vary by AI tool.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add posthog/ai-plugin --skill "authoring-error-tracking-alerts" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

MCP server required

The skill's steps call for tools from the PostHog MCP server. Installing just this skill doesn't add that connection; set it up in your AI tool if it isn't there yet: PostHog MCP setup. Installing the whole plugin instead includes the connection settings.

Requirements for the PostHog MCP server

Connecting is free; sign in with your PostHog account.
Some tools use AI internally and may incur PostHog AI charges. Those tools require AI data processing to be enabled in your organization settings.

Install the whole plugin

This route installs the posthog plugin package selected for your AI tool.

Claude Code

Add PostHog's marketplace, then install the plugin

Run both lines in a terminal. They install PostHog's posthog plugin: this skill, PostHog's other skills, and a connection to PostHog's hosted MCP server.

claude plugin marketplace add PostHog/ai-plugin

02
```
claude plugin install posthog@posthog
```

Installation and loading

The plugin installs for you in every project and loads the next time you start Claude Code, or after /reload-plugins in an open session.
To connect your PostHog account, start claude, type /mcp, select plugin:posthog:posthog and follow the browser prompts.

Good to know

The plugin includes PostHog's session-capture hook; PostHog's README says it sends sessions to LLM Analytics only when POSTHOG_LLMA_CC_ENABLED=true and POSTHOG_API_KEY are both set.
If you use the separate posthog-telemetry plugin, PostHog says to keep only one of the two, because both register the same hook.
On a self-hosted PostHog, this route's MCP connection won't reach your instance: the plugin's config is fixed to https://mcp.posthog.com/mcp, which routes to PostHog's US or EU region. POSTHOG_MCP_URL works only for the Gemini CLI extension.

View on GitHub

Same repository

adding-warehouse-person-properties
Sync columns from a synced data warehouse table onto PostHog person or group properties, so warehouse data becomes usable anywhere person and group properties already work: feature flag targeting, cohorts, insight filters and breakdowns, surveys, session replay filters, workflows, and the person profile. Use when the user wants to "add a person property from my warehouse", "enrich people with Stripe/Postgres/Salesforce data", "put ARR or plan tier on my persons", "target a feature flag by a warehouse column", "sync warehouse columns onto groups or organizations", or wants to inspect, backfill, disable, or debug an existing warehouse-backed person or group property.Read full description
analyzing-expensive-users
Analyze the most expensive users in AI observability and explain why they cost so much. Use when the user asks about top spenders, expensive users, per-user LLM cost, user-level cost drivers, or patterns behind high AI observability spend.Read full description
analyzing-experiment-session-replays
Analyze session replay patterns across experiment variants to understand user behavior differences. Use when the user wants to see how users interact with different experiment variants, identify usability issues, compare behavior patterns between control and test groups, or get qualitative insights to complement quantitative experiment results. Also covers pairing the observed behavior with a linked survey when the user wants qualitative feedback beyond what recordings show.Read full description
assessing-heatmaps
Assesses what a page's heatmap is telling you and recommends concrete changes. Pulls click / rageclick / scroll-depth data for a URL, names the hot elements by cross-referencing autocapture events on the same page, and can create a saved heatmap the user opens in PostHog, then summarizes the behavior and proposes improvements. TRIGGER when: user asks what a heatmap shows, why people aren't clicking something, where users rage-click, how far they scroll, what to change on a page based on heatmap/click data, or to 'analyze/assess/review the heatmap' for a URL. DO NOT TRIGGER when: the user only wants to create a saved heatmap screenshot with no analysis (use heatmaps-saved-create directly), or is asking about session replay in general (use investigating-replay).Read full description
auditing-endpoints
Audit every endpoint in a PostHog project for staleness, failed materialisations, and unused materialised versions. Use when the user asks "what endpoints can I clean up?", "are any of my endpoints broken?", "which materialised versions are still being called?", or wants a one-shot cleanup pass over the Endpoints product. Produces a prioritised report grouped by issue type, with recommended actions but does not modify anything without explicit confirmation.Read full description
auditing-experiments-flags
Audit PostHog experiments and feature flags for configuration issues, staleness, and best-practice violations. Read when the user asks to audit, health-check, or review experiments or feature flags, check flag hygiene, or verify experiment setup.Read full description