provider-connector
Skill83 starsChanged 13 days agoMITView on GitHub
Change, add or review a Headroom provider connector in `packages/connectors/`. Use when a provider metric parses wrong, a response shape changes, a provider needs a new endpoint or a new provider is added, or when reviewing a connector pull request.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- app-api-compatibilitySkill
- pr-ciSkill
- pr-showcaseSkill
- verify-webSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Reproduce with a fixture: Add a synthetic response to src/fixtures/ in the reported shape.
- Very specific: line 26
Do every step above, and also wire the package in.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Provider connector
A connector reads one provider's quota and balance data over direct HTTP. Its rules live in four documents; read the ones the change touches before writing code:
- the provider's dossier,
docs/providers/<provider>.md: endpoints, metric labels, evidence; - the connector contract: adapter obligations, error categories, version policy;
- the validation plan: what counts as proof per provider;
- ADR 0001 when sign-in changes.
Fix or extend a connector
- Reproduce with a fixture. Add a synthetic response to
src/fixtures/in the reported shape. Replace every email, id, name, token and URL with an invented value. Write the test that fails on it before you change code. - Change the parser at its schema. Response shapes are Zod schemas in
src/schemas.ts; endpoints and headers live only insrc/endpoints.ts. Call only endpoints the dossier lists; a new endpoint goes into the dossier first, with its evidence label. - Keep unknown unknown. A missing or unparseable value is
invalid_responsefor that one metric, and the other metrics keep their values. Never default to 0. Money, credits and percentages stay in separate units. Add a schema-drift fixture when the change touches parsing. - Bump the version. Any endpoint, header or parser change raises
<provider>ConnectorVersioninsrc/index.ts. - Update the dossier. Each touched metric keeps its
officialorprivatelabel and an evidence label: documented, source-inspected, prior observation, validated or unvalidated. A fixture test proves the parser, so the label is at most source-inspected; only the owner's live run makes it validated. - States. A new state goes into
packages/core/src/enums.tsand the data model in the same commit.
Add a provider
Do every step above, and also wire the package in. Copy the layout of an existing connector, such as packages/connectors/cursor:
package.jsonwith exact dependency versions, and aknip.jsonworkspace entry;- the dependency in
apps/server/package.jsonand the registration inapps/server/src/index.ts; - the provider name in
enums.ts; - a dossier, a row in
docs/providers/README.mdand the docs index, and a provider gate row in the validation plan.
Review a connector pull request
Apply the same list to the diff, and read each new fixture for real data: a plausible email, a long random id or a real organization name means a captured response. Ask the author to replace it before any other review.
Boundaries
Agents never run a connector against a real account, and monitoring never sends a model request, redeems a reset or buys credits. Live checks are the owner's; record them in the evidence register.
Done when
- The new test failed before the change and passes after it.
mise run checkpasses.- The connector version, the dossier and the enums match the change.
- The pull request shows the before and after parse under Showcase (PR showcase skill).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

