SKILL.md · 24000
ample/repository/pull/123"] }
PR links are additive and retries do not duplicate them. Send every known PR together so completion
considers the entire stack. The same PR may be attached to multiple reports. Connected repositories receive immediate state
validation and webhook updates. PRs from unconnected repositories are accepted with unknown state,
so resolve those reports manually after the work lands. Also reference the report's `_posthogUrl`
in the PR description so the loop is traceable from either side.
**Don't resolve a report because you opened a PR.** A report resolves when all linked PRs are closed
or merged and at least one merged. If all closed without merging, it is suppressed. Any open, draft,
or unknown PR prevents automatic completion. Resolving by hand at PR-open
time asserts work that hasn't landed, and a reviewer looking at the inbox can't tell the difference.
Manual resolve is for fixes a PR merge will never cover — a skill-body change, a config change, a
`NO_REPO` report — see the workflow below.
## Workflow: run an action on a report
A report can offer actions that start an agent run, the same ones the inbox shows as buttons:
**Get it merged** (`get_it_merged`) fixes CI on the report's open, approved pull request and merges
it, **Make it green** (`make_it_green`) fixes failing CI on its open pull request without merging,
and each **suggested prompt** (`suggested_prompt`) sends one prompt the report suggests. **Ask**
(`ask`) sends your own `message`, like Ask AI in the inbox. Use these instead of
`tasks-create-and-run`: a run started here is linked to the report, so it shows in
the report's runs, counts toward the report's task limit, and gets the report's code access rules.
The two tools are rolling out behind a flag, so they can be missing from your tool list. If they
are, send the person to the report's `_posthogUrl` to press the button.
### Step 1 — List the actions
```json
posthog:inbox-report-actions-list
{ "report_id": "<report_uuid>" }
Every action comes back, available or not. Pick one with available: true. When an action is not
available, disabled_reason says why (no approved open PR, AI data processing not approved, and so
on): tell the person rather than trying to run it. text is the message the run gets as its first
request, so show it when the person wants to know what the agent will be asked to do.
Step 2 — Confirm, then run it
Starting a run creates a task that spends the organization's usage, and Get it merged can merge a pull request. Confirm with the person before you run an action they did not ask for by name.
posthog:inbox-report-actions-run
{ "report_id": "<report_uuid>", "action": "suggested_prompt", "suggested_prompt_index": 0 }
Pass suggested_prompt_index only for suggested_prompt, with the value from the list.
To ask about the report or request work the listed actions do not cover, use ask with a
message. ask is not in the list. The run answers a question, and carries out requested work
only while the report still has work to do and no pull request:
posthog:inbox-report-actions-run
{ "report_id": "<report_uuid>", "action": "ask", "message": "Which customers hit this error?" }
get_it_merged and make_it_green also take an optional message. It replaces the action's
fixed request and keeps its instructions and gates. Pass it only when you know something the report
does not, such as "#123 lands first, so rebase onto it after it merges" or "the migration check
also fails on the base branch, so leave it".
A 201
returns task_id, run_id, and task_url. Each successful call creates a new task, so do not
retry it. If run_error is set, the task exists but its run did not start: report the error and do
not start a second one.
Step 3 — Follow the run
The run works in the background. Follow it with tasks-runs-retrieve using task_id and run_id,
and give the person task_url. Nobody can answer questions in a background run, so when the agent
needs a decision it writes a note to the report's work log. Read new notes with
inbox-report-artefacts-list.
Errors
Every refusal carries a code. Do not retry any of them unchanged.
| Status | code | What to do |
| ------ | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
| 400 | report_action_unavailable | The action is not available now. Tell the person the detail. |
| 403 | report_action_unavailable | The organization has not approved AI data processing. An admin turns it on in settings. |
| 403 | report_action_sandbox_refused | A task sandbox cannot start report actions. Ask a person to start it from their own session. |
| 409 | report_action_run_active | A merge run is already working on the report. Follow the task_id and run_id in the body. |
| 429 | signal_report_task_cap | The report reached its task limit. Work with the runs it already has. |
| 429 | throttled, usage_limit_exceeded | A per-user or organization usage limit fired. Wait until it clears. |
| 402 | self_driving_free_trial | The organization is on a Self-driving free trial, which cannot open pull requests. |
| 404 | none | The report has no suggested prompt at that index. List the actions again and use a fresh index. |
Workflow: resolve, dismiss, or snooze a report
Three outcomes, one tool. Pick by what actually happened to the underlying issue:
| The issue is… | State | Why |
| --------------------------------------------- | ------------ | -------------------------------------------------- |
| fixed by work you did | resolved | terminal; the report has served its purpose |
| not real, or not worth fixing | suppressed | dismissed from the inbox, with the reason recorded |
| real but deferred, or fixed by something else | potential | back into the pipeline; reappears if it recurs |
inbox-reports-set-state
{
"id": "<report_uuid>",
"state": "suppressed",
"dismissal_reason": "analysis_wrong",
"dismissal_note": "Verified against products/foo/bar.py — the cited code path can't reach this state."
}
state: "resolved"marks the requested work done, and is terminal — a recurrence starts a fresh report rather than reopening this one. Allowed fromready/pending_input, or from asuppressedreport that held one of those when archived; anything else returns409. Only resolve work that has actually landed. A fix shipping as a PR resolves itself on merge (see Step 4); resolve by hand only where the webhook can never reach — a skill-body edit, a config change, aNO_REPOreport. Recorddismissal_reason: "fixed_outside_posthog"for that (the fix landed without a pull request); usepr_mergedwhen a pull request with the fix was merged but did not resolve the report on its own; reservealready_fixedfor an issue fixed before the report was filed. Don't usealready_fixed+state: "potential"when you did the fixing: that pairing means "fixed by something else, might recur", so the report comes back.state: "suppressed"dismisses the report from the inbox;state: "potential"snoozes it back into the pipeline. When snoozing,snooze_for: <N>holds it until it accumulates N more signals.dismissal_reasonmust be one of the server-validated canonical codes —already_fixed,report_unclear,analysis_wrong,wrong_assignee,wrong_repo,wontfix_intentional,wontfix_irrelevant,fixed_outside_posthog,no_action_needed,pr_merged,other— an unlisted value returns400. Reach forotherplus adismissal_notefor anything that doesn't fit a specific code.dismissal_noteis free-form (≤ 4000 chars). Both persist as a DISMISSAL artefact, so the rationale survives later transitions — always include them, on a resolve too, so a future reader knows why.wrong_repomeans the agent researched the report against the wrong repository. Pair it withcorrected_repository("owner/repo", case-insensitive; only allowed with this reason) naming the right one: the correction is recorded on the dismissal and fed into every future repository selection for the project, and when the named repository is connected to the project it also becomes this report's own next selection. Without a usable correction the report's selection is cleared instead, so a restored report re-selects rather than reusing the rejected repository.wrong_assigneemeans the report reached the wrong person or team. It is routing feedback, not a verdict that the report itself was wrong.- On a dismiss, snooze, or restore, the
dismissal_noteis also forwarded as a steering note to the scout that filed the report, which every scout run reads at cold start, so what you write there is what stops the same report being filed again. Write it for that reader: name the evidence that settles it, not just the verdict. A resolve is not forwarded, since it says the report did its job rather than that filing it was wrong; that note stays on the report. Awrong_repodismissal is forwarded even with no note: the steering note names the repository the report wrongly targeted and, when you passed one, thecorrected_repository. Forwarding needs the same skill-editing access as leaving a scout note by hand, so on a project where you lack it the note still lands on the report but does not reach the scout. - It's a destructive, non-idempotent transition and returns
409if it isn't allowed from the report's current status (and400ifdismissal_reasonisn't a canonical code). Confirm with the user before suppressing, and capture why in the note — a dismissal with no rationale is worse than none. A report you dismissed because the diagnosis was wrong (Step 2 above) is the textbook case: suppress it withanalysis_wrongand the evidence in the note. A refunded report is frozen: snooze and resolve both come back409/skippedwith an explanatorydetail. - To transition several reports at once, use
inbox-reports-bulk-set-statewith anidsarray (1–100). It applies the samestate/dismissal_reason/dismissal_note/corrected_repository/snooze_forto every id and returns a per-idresultslist (in request order) plus atransitioned_count/skipped_count/failed_count/not_found_countsummary. Each id is processed independently, so the call returns200even on partial failure — an id whose transition isn't allowed comes back asskipped(the single-report409) while the rest go through. Inspect the per-id outcomes rather than assuming the whole batch succeeded.
Workflow: filter by topic or source
"Are there any reports about ?" — start with search:
inbox-reports-list
{
"search": "checkout",
"status": "ready,in_progress,pending_input",
"limit": 20
}
search matches title and summary. If the user is asking about a product area rather than a
keyword, use source_product:
inbox-reports-list
{
"source_product": "session_replay,error_tracking",
"limit": 20
}
If the keyword search returns nothing meaningful, hand off to the signals skill — semantic
search over signal text via embedText() will catch reports the keyword filter missed.
Model predictions as building blocks
The inbox ranking model predicts outcomes for each report. Each row of inbox-reports-list and
inbox-reports-retrieve carries them in ranking:
"ranking": {
"status": "scored",
"scored_at": "2026-10-24T05:12:00Z",
"predictions": [
{ "outcome": "open", "probability": 0.21, "lift": 1.5, "readable": true },
{ "outcome": "action", "probability": 0.09, "lift": 1.4, "readable": true },
{ "outcome": "fix", "probability": 0.3, "lift": 2.7, "readable": true }
]
}
open: a person opens the report.action: a person or their agent acts on it.fix: someone fixes the problem it describes. Callinbox-ranking-outcomes-listfor the current meaning, horizon and base rate of each outcome, because they follow the served model.- A prediction says what may happen, never what did. A high
fixprobability does not mean the report is fixed: readstatusand the PR fields for that. - A lift is the probability divided by the outcome's base rate. 1.0 is an average report, 2.7 is 2.7x as likely. Compare lifts across outcomes. Raw probabilities do not compare, because each outcome has its own base rate.
readable: falsemeans the training run could not measure the holdout AUC of that outcome. Rank and filter on that outcome with caution.statusisscored,stale(the title or summary changed after scoring, so the predictions describe the old text),unscored(no score yet, which is not a low score), ornot_available(the user cannot see the ranking model, so ordering and filtering by it return 400).inbox-reports-retrievealso names themodelthat made the predictions. Predictions from different models do not compare.
Recipes:
- Likely to get a fix:
view=actionablewithordering=-ranking_fix. - Hidden gems:
priority=P3,P4withranking_min_lift=fix:2. - Probably noise: reports with a low lift on all three outcomes are candidates to dedupe or dismiss. Read them before you act: a low lift is a hint, not a verdict.
- Add
searchorsource_productto any recipe to narrow it to a topic.
ranking_min_lift and ranking_min_probability take comma-separated <outcome>:<value> pairs,
and a report must meet every pair. Unscored and stale reports never match.
Caveats:
- The predictions are model estimates, and the top end over-predicts. Use them to rank and filter, not as literal odds.
- Most
fixpositives are alsoactionpositives, so do not add the two together.
Workflow: review configured sources
When the user asks "which signal sources are set up?" or "is hooked up?":
inbox-source-configs-list
{ "limit": 50 }
Each entry returns id, source_product, source_type, enabled, status, plus timestamps.
For full details (including the per-source config JSON — recording filters, evaluation IDs,
etc.):
inbox-source-configs-retrieve
{ "id": "<source_config_uuid>" }
Integration credentials live in a separate Integration model — they are not in the
config blob, so it's safe to summarize the contents back to the user.
The status field reflects the underlying data import or workflow:
running/completed— feeding signals normallyfailed— the source isn't currently producing signals; flag this to the user
To turn a source on or off, use inbox-source-configs-partial-update with the config's id and
{ "enabled": true | false } — only the fields you pass change, so this is the right tool for a
plain toggle (-update replaces the whole record; -create stands up a new source). Confirm with
the user before flipping a source, since enabling one drives signal processing and spend.
inbox-source-configs-partial-update
{ "id": "<source_config_uuid>", "enabled": false }
To edit individual source settings, send only the top-level keys to change in config_set and keys to delete in config_remove.
These edits preserve unrelated settings even when another editor saves at the same time.
For guidance, set config_set.steering and include default_not_actionable in config_remove.
Use config_set.linear_team_ids for Linear team selection.
Reserve config for an intentional whole-object replacement; do not combine it with key edits.
Tips
- Check setup before assuming the inbox is empty. If
inbox-reports-listreturnscount: 0, callinbox-source-configs-listfirst — no sources means the user needs to install PostHog Desktop to start receiving signals; sources-but-no-reports means signals are flowing but nothing has clustered yet - Always surface
_posthogUrlso the user can click through to the report - The default ordering already prioritizes the user's suggested reports — don't reorder unless asked
priorityandactionabilityarenullfor reports still inpending_inputorcandidatestatus; this is expected, not a bug — judgment hasn't run yetsuppressedreports are excluded by default. Passview: "dismissed"for reports someone dismissed,view: "held_back"for reports a judge held back, orstatus: "suppressed"for both. Readsuppression_sourcebefore you describe why a report left the inbox- The inbox writes exposed via MCP are
inbox-reports-set-state(resolve / dismiss / snooze one report),inbox-reports-bulk-set-state(the same for 1–100 reports),inbox-reports-claim(claim / release / attach a PR), andinbox-source-configs-partial-update(toggle a source'senabledflag). To act on a report (implement a fix), claim it, verify the diagnosis against the code, then open and attach a PR — see Workflow: act on an actionable report. A PR-backed fix is resolved automatically when the PR merges, so don't resolve it by hand at PR-open time. Always also surface the_posthogUrldeep-link - Never implement a report's fix straight from its
summary. Reports — especiallysignals_scoutones — are LLM diagnoses; confirm the cited files / functions / behavior in the actual code before writing a fix. A report that doesn't hold up is a dismissal candidate, not a fix - For "what kinds of signals exist?" or "what's been happening recently across all sources?",
drop into the
signalsskill — the report layer hides individual observations; you need HogQL ondocument_embeddingsto see them - Source configs don't have per-record deep-links — they live behind project settings, so
inbox-source-configs-retrievereturns no_posthogUrl. Don't confuse them with reports