Track your Net Promoter Score from Typeform responses every week

SKILL.md---
name: typeform-nps-score
description: "Every Monday: your NPS from the last 30 days of Typeform responses, the split of promoters and detractors, and what the detractors said. Use when the user asks for this, or when it runs on a schedule."
---

# Typeform NPS score

Every Monday: your NPS from the last 30 days of Typeform responses, the split of promoters and detractors, and what the detractors said.

Typeform collects the 0 to 10 answers well, but the score itself is arithmetic you do in a spreadsheet: promoters minus detractors, as percentages, over a window that has to stay the same every time. And the reasons sit in a follow-up question nobody reads in bulk.

Every Monday the agent reads the last 30 days of completed responses, works out NPS, and groups the detractors' comments into a few themes with an example of each. Founders get the number and its direction, product and support leads get the reasons behind it.

## 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 Typeform personal access token with `forms:read` and `responses:read` in `TYPEFORM_TOKEN`.
- The form ID (from the form's URL), and which question is the NPS one if the form has several scales.

If something is missing, say what and stop; do not invent numbers.

### Steps

1. **Find the NPS question** (Typeform): Call `GET https://api.typeform.com/forms/{form_id}` and find the field with `type: "nps"` (or a 0 to 10 `opinion_scale`), plus the follow-up `long_text` field that asks why. Keep both field IDs.
2. **Read 30 days of responses** (Typeform): Call `GET /forms/{form_id}/responses` with `since` set to 30 days ago, `page_size=1000` and `response_type=completed`, paging with `before`. Each answer to the NPS field has `type: "number"` and a `number` from 0 to 10.
3. **Work out the score**: Promoters answered 9 or 10, passives 7 or 8, detractors 0 to 6. NPS is the percentage of promoters minus the percentage of detractors, from -100 to 100. Save each Monday's score so the tile has 8 weeks of history.
4. **Read what detractors said**: Group the detractors' follow-up answers into 3 to 5 themes, count each, and quote one short example per theme without names or emails.

## Route B: the browser

### What you need

- Signed in to Typeform as the form owner or a workspace member who can see results; a viewer who can only edit the form will not see the Responses tab.

If something is missing, say what and stop; do not invent numbers.

### Steps

Start at https://admin.typeform.com/. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears.

1. **Open the form's results**: Pick the workspace, open the NPS form and click **Results** at the top, then the **Summary** tab. Use the date filter above the summary and set it to the last 30 days.
2. **Read the score**: Scroll to the Net Promoter Score question. The summary shows the score and the split of promoters, passives and detractors with their counts. Note all four and the number of responses.
3. **Read what detractors said**: Open the **Responses** tab with the same 30-day range and filter to completed responses. Sort or scan by the NPS answer and read the follow-up answer of every response scored 0 to 6.
4. **Export when there are many**: If the table holds more than a hundred responses, use **Download** to get a CSV of the filtered responses and read the score and follow-up columns from it instead.
5. **Group the reasons**: Sort the detractors' comments into 3 to 5 themes with a count each and one short quote per theme, without names or emails. Compare the score with last week's if you saved it.

Note: The Summary tab counts completed responses by default; the Responses tab can also show partial ones, so keep its filter on completed. If the score question is an opinion scale rather than Typeform's NPS question type, the summary shows a distribution instead of a score and you work it out from the 0 to 10 counts.

## The report

- **NPS** over the last 30 days, with the change on last week and an 8-week trend.
- **Promoters, passives and detractors** as percentages and counts.
- **Detractor themes**, each with a count and one short quote.
- One line on the theme to act on 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": "typeform-nps-score/<date of this run, e.g. 2026-10-16>",
  "item_key": "typeform-nps-score",
  "project": "Acme",
  "source": "Typeform NPS score skill",
  "kind": "metric",
  "title": "NPS 42 over the last 30 days",
  "metric": {
    "label": "NPS (30 days)",
    "value": 42,
    "better": "higher",
    "period_start": "<start of the period, ISO 8601>",
    "period_end": "<end of the period, ISO 8601>"
  },
  "glance": [
    {
      "type": "Grid",
      "props": {
        "columns": 4
      },
      "children": [
        {
          "type": "Stat",
          "props": {
            "label": "Promoters",
            "value": 54,
            "unit": "%",
            "tone": "ok"
          }
        },
        {
          "type": "Stat",
          "props": {
            "label": "Passives",
            "value": 34,
            "unit": "%"
          }
        },
        {
          "type": "Stat",
          "props": {
            "label": "Detractors",
            "value": 12,
            "unit": "%",
            "tone": "bad"
          }
        },
        {
          "type": "Stat",
          "props": {
            "label": "Responses",
            "value": 250
          }
        }
      ]
    }
  ],
  "widget": [
    {
      "type": "Table",
      "props": {
        "columns": [
          "Detractor theme",
          "Count",
          "Example"
        ],
        "align": [
          "left",
          "right",
          "left"
        ],
        "rows": [
          [
            "Slow support replies",
            11,
            "\"Waited three days for an answer about billing.\""
          ],
          [
            "Missing integrations",
            8,
            "\"No way to sync with our accounting tool.\""
          ],
          [
            "Price after the increase",
            7,
            "\"Too expensive for a team of four now.\""
          ],
          [
            "Other",
            4,
            ""
          ]
        ]
      }
    },
    {
      "type": "Callout",
      "props": {
        "text": "NPS slipped 2 points from last week's 44. Slow support replies is the biggest detractor theme, 11 of 30.",
        "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 9:00 (`0 9 * * 1`). From cron, with the agent signed in on that machine:

```bash
0 9 * * 1 claude -p "Run the typeform-nps-score 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/typeform-nps-score#schedule

Source: https://briefkin.dev/skills/typeform-nps-score