agentleFS
amitray007amitray007/headroom/.agents/skills/provider-connector/SKILL.md

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.

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
  1. Very specific:

    Reproduce with a fixture: Add a synthetic response to src/fixtures/ in the reported shape.

    line 17
  2. Very specific:

    Do every step above, and also wire the package in.

    line 26

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. 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.
  2. Change the parser at its schema. Response shapes are Zod schemas in src/schemas.ts; endpoints and headers live only in src/endpoints.ts. Call only endpoints the dossier lists; a new endpoint goes into the dossier first, with its evidence label.
  3. Keep unknown unknown. A missing or unparseable value is invalid_response for 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.
  4. Bump the version. Any endpoint, header or parser change raises <provider>ConnectorVersion in src/index.ts.
  5. Update the dossier. Each touched metric keeps its official or private label 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.
  6. States. A new state goes into packages/core/src/enums.ts and 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.json with exact dependency versions, and a knip.json workspace entry;
  • the dependency in apps/server/package.json and the registration in apps/server/src/index.ts;
  • the provider name in enums.ts;
  • a dossier, a row in docs/providers/README.md and 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 check passes.
  • 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).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.