Track weekly npm downloads across all your packages

SKILL.md---
name: npm-weekly-downloads
description: "Every Monday: last week's npm downloads summed across your packages, the change against the week before, and the package that moved most. Use when the user asks for this, or when it runs on a schedule."
---

# npm weekly downloads

Every Monday: last week's npm downloads summed across your packages, the change against the week before, and the package that moved most.

npmjs.com shows one package's weekly downloads in a small sparkline, and that number is a rolling 7 days, so it changes every time you look. With five packages under a scope, getting one honest week-over-week figure means a spreadsheet.

The agent asks the public npm downloads API for fixed Monday-to-Sunday weeks, so this Monday's number never moves, sums every package and ranks them by change. It needs no token: download counts are public. Maintainers use it to see whether a release or a blog post moved adoption; founders use it as the open-source line in the weekly update.

## 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

- Nothing secret: the downloads API at `api.npmjs.org` is public and needs no token.
- The npm CLI only if you want the agent to find your packages with `npm access list packages`.

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

### Steps

1. **List your packages**: Use the list in the prompt, or `npm access list packages <user-or-scope> --json` for everything a user or scope publishes. Leave out deprecated packages unless you want them counted.
2. **Count last week** (npm): `GET https://api.npmjs.org/downloads/point/<monday>:<sunday>/<package>` with last week's dates (UTC, both inclusive). Unscoped packages can go in one call, comma-separated, up to 128 at a time; scoped ones like `@acme/cli` need one call each.
3. **Count the week before and the daily shape** (npm): Repeat for the previous Monday to Sunday. For the chart, `GET https://api.npmjs.org/downloads/range/<start>:<end>/<package>` returns one row per day; 8 weeks is plenty.
4. **Report**: Total downloads and the change, one row per package with its count and change, and the biggest mover in either direction. A drop on one package right after a release can mean a broken version; say so if the dates line up.

## Route B: the browser

### What you need

- No sign-in: download counts are public. A signed-in npm session only helps the agent find your packages from your profile.

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

### Steps

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

1. **List the packages**: Open your profile at `https://www.npmjs.com/~<username>` or the scope at `https://www.npmjs.com/org/<scope>` and read the **Packages** tab for the names. Skip packages marked deprecated unless you want them counted.
2. **Read last week's count per package**: The download counts are public JSON that opens in any tab: `https://api.npmjs.org/downloads/point/<last Monday>:<last Sunday>/<package>` with UTC dates, for example `2026-10-05:2026-10-11`. Read the `downloads` number. Unscoped names can be joined with commas in one URL; scoped names like `@acme/cli` need their own.
3. **Read the week before and the trend**: Change the dates to the previous Monday to Sunday and read again. For the 8-week trend, open `https://api.npmjs.org/downloads/range/<8 Mondays ago>:<last Sunday>/<package>` and add the daily rows up by week.
4. **Report**: Total downloads and the change, one row per package largest first with its change, and the biggest mover each way. If a package dropped sharply, open its npmjs.com page and check the **Versions** tab for a release that week.

Note: The **Weekly Downloads** figure on an npmjs.com package page is a rolling 7 days, so it never matches a fixed week; the JSON URLs above are the same data npmjs.com draws from and give fixed weeks. Each day is final shortly after midnight UTC.

## The report

- **Downloads last week** across all packages, and the change.
- **Per package**: downloads and change, largest first.
- **Biggest mover**, up or down, with a likely reason if one is visible (a release, a dependent that added you).
- An 8-week trend of the total.

## 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": "npm-weekly-downloads/<date of this run, e.g. 2026-10-16>",
  "item_key": "npm-weekly-downloads",
  "project": "acme",
  "source": "npm weekly downloads skill",
  "kind": "metric",
  "title": "48,920 downloads last week, up 9.4%",
  "metric": {
    "label": "Weekly downloads, all packages",
    "value": 48920,
    "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": "vs week before",
            "value": 9.4,
            "unit": "%"
          }
        },
        {
          "type": "Stat",
          "props": {
            "label": "Packages",
            "value": 6
          }
        },
        {
          "type": "Stat",
          "props": {
            "label": "Top mover",
            "value": "@acme/cli"
          }
        }
      ]
    }
  ],
  "widget": [
    {
      "type": "Table",
      "props": {
        "columns": [
          "Package",
          "Last week",
          "Change"
        ],
        "align": [
          "left",
          "right",
          "right"
        ],
        "rows": [
          [
            "acme-ui",
            "21,480",
            "+6%"
          ],
          [
            "@acme/cli",
            "12,310",
            "+18%"
          ],
          [
            "acme-hooks",
            "8,920",
            "+2%"
          ],
          [
            "@acme/eslint-config",
            "4,105",
            "+31%"
          ],
          [
            "acme-icons",
            "1,640",
            "-4%"
          ],
          [
            "@acme/legacy-client",
            "465",
            "-22%"
          ]
        ]
      }
    },
    {
      "type": "Callout",
      "props": {
        "text": "@acme/cli grew 18% after the 3.0 release on Tuesday. @acme/legacy-client keeps falling as users move to the new client.",
        "tone": "info"
      }
    }
  ],
  "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 npm-weekly-downloads 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/npm-weekly-downloads#schedule

Source: https://briefkin.dev/skills/npm-weekly-downloads