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.

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