write-provider-skill

# Writing a provider skill

A provider skill is **an MCP server made of documentation**. An MCP server gives a model a tool
list and typed parameters. We can't ship a server per platform, so the skill carries the same
payload as prose: *which endpoints matter, what the parameters really are, and where the API
lies to you.*

The third part is the one MCP can't give you, and it's where nearly all the value is.

## The rule that decides what goes in

> **Document what produces a wrong answer without producing an error.**

Ranked by value to an agent:

| Class | Why it matters | Example |
|---|---|---|
| **Silent wrong answers** | Agent reports confidently false results. Unrecoverable alone. | GA4: incompatible dimension+metric returns `"0"` per row, not an error — reads as "no revenue" |
| **Wrong-shaped errors** | Error doesn't describe the real cause, so retries go sideways | GA4: bad path returns a Google **HTML 404 page**, not JSON — a JSON parse throws something unrelated |
| **Unguessable identifiers** | Agent invents an ID and gets 403/404 forever | GA4 needs `properties/123456789`; GSC needs `sc-domain:x.com` vs `https://x.com/` |
| **Host splits** | Endpoint exists but not on the bound host | GA4 Admin API is `analyticsadmin`, tool is bound to `analyticsdata` → 404 |
| **Capability limits** | Agent attempts work the scope can't do | GA4 connection is `read` only |
| Endpoint list | Findable in official docs | — |

Anything in the bottom row: **link to the docs, don't restate them.** A skill that paraphrases
the API reference is worse than a URL — it goes stale and it's longer.

## Verification protocol — non-negotiable

**Every endpoint and every example body in the skill must have been executed.** Not adapted from
docs, not plausible — run.

```bash
scripts/dev-local.sh up
scripts/dev-local.sh cli connections ls          # confirm health + resource_ref
scripts/dev-local.sh cli call <provider> <path>  # always via /call/, never direct
```

Call through `/call/` rather than curl-with-a-token: that exercises binding injection, token
refresh, and the audit trail, which is where treg bugs surface.

Mark every endpoint **✅ verified** or **⚠️ unverified**, and date the skill. An unverified
endpoint is allowed — an *unmarked* one is not.

**Read the audit log when something 404s.** It records the exact upstream URL, which catches
client-side path mangling that the terminal output hides:

```bash
sqlite3 treg-dev.db "select method,path,status_code from callrecord order by id desc limit 5"
```

That's how the zsh `:r` bug below was found: the terminal showed a plausible Google error, the
audit log showed the request had gone to `...123456789unRealtimeReport`.

## Write-side testing

Read endpoints: call freely. **Write endpoints publish real things to real accounts and are not
reversible.** Before any POST/PUT/DELETE that creates content or spends money:

1. Get an explicit designated target from the human (throwaway account, sandbox ad account)
2. Get explicit per-provider go-ahead
3. If neither exists, mark the endpoint ⚠️ unverified and document it from the API reference

Never publish to a production account to satisfy a checkbox.

## Skill structure

Follow this order — it matches how an agent actually reads under time pressure:

```
frontmatter: name + description (description = the trigger; list the words a user would say)
# <Platform> via treg
  one line: you call X through treg's proxy, you never hold a credential
  "All examples verified live on <date>"
## Setup (once per team)      — connect command, what capability you get
## Which <resource> to use    — how to READ the id, never guess it
## The endpoints              — table: path | method | purpose | verified?
## Common jobs                — 4-6 real tasks, full runnable bodies
## Reading the response       — shape gotchas (positional arrays, strings-not-numbers, timezone)
## Pitfalls                   — the silent-wrong-answer list. The most valuable section.
## Full documentation         — links out
```

## Pitfall classes that recur across providers

Check each one explicitly when building a new skill. Confirmed on GA4; **expected but
unconfirmed** elsewhere until tested.

- **Host split** — is there an admin/management API on a different hostname than the data API?
  The tool's `base_url` binds one host; the other is unreachable via `/call/`.
  *Expect this on Google Ads (googleads vs googleadsapi surfaces) and Meta (graph vs business).*
- **Resource id format** — exact prefix, exact encoding. Read it from `treg connections ls`
  → `resource_ref`. If empty, `treg connections resources <id>` then `treg connections use`.
- **Positional response arrays** — headers and values matched by index, not name.
- **Numbers as strings** — cast before arithmetic.
- **Timezone/currency** — reports render in the *property's* timezone. Read it from the response
  before interpreting "today".
- **Silent truncation** — default row limits, `(other)` buckets for high-cardinality dimensions,
  pagination tokens that look like completion.
- **Shell quoting** — in zsh, `$VAR:runReport` triggers the `:r` history modifier and silently
  corrupts the path. Use `${VAR}:runReport`. Applies to any API with `:action` path suffixes.
- **Scope vs capability** — what the connection actually granted (`treg connections ls` →
  `scopes`, `capabilities`, `missing_capabilities`), not what the platform offers.

## Also record treg friction

This exercise doubles as a treg test. When an agent would plausibly guess wrong about *treg's own
interface*, note it — those are product bugs, not skill content. Found so far:

- `treg connections list` is invalid; the subcommand is `ls`
- `treg connections resources` takes a numeric id, not a provider name

## Checklist

- [ ] Connected via real OAuth; `connections ls` shows `health: ok`
- [ ] Every endpoint executed through `/call/`; each marked verified/unverified
- [ ] Deliberately probed for silent-wrong-answers (bad f