agentleFS
robertn702robertn702/reasoning-router/.agents/skills/add-classifier/SKILL.md

add-classifier

Skill4 starsChanged 35 days agoMITView on GitHub

Add a new reasoning-effort classifier (decision model) to reasoning-router as a preset in @reasoning-router/classifiers, wired through the registry, tests, the classifiers README, and a changeset. Use whenever the task is to support, integrate, or add a classifier or decision-model provider (for example "add a classifier for <service>", "support <model> as a decision model", "make X selectable via classifier.provider" or REASONING_ROUTER_CLASSIFIER), even if the user doesn't say "preset" or name this skill. Not for changing classification policy (retries, fallback) or adding a harness.

  • Reads credentials

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 5 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    No new package: Add the preset to packages/classifiers.

    line 25
  2. Distinctive:

    If this skill and those files disagree, the files win.

    line 43
  3. Very specific:

    Different settings: Prefer mapping onto the shared REASONING_ROUTER_CLASSIFIER* settings (apiKey, baseUrl, accountId, model, timeoutMs).

    line 54
  4. Distinctive:

    Different auth or endpoint: Keep the credential safe: send it only to hosts the preset can vouch for.

    line 62
  5. Distinctive:

    Stop and raise it with the user instead of bending core or the state to fit one provider.

    line 69
  6. Very specific:

    No type assertions: Biome rejects them (as const is the only exception).

    line 121
  7. Distinctive:

    Document the settings the new one actually uses.

    line 152
  8. Very specific:

    Leave docs/environment.md, .env.example, and the OpenCode and Pi READMEs alone: they describe the shared variables generically and link to …

    line 163
  9. Very specific:

    Not every hit is a list. Tests that exercise one provider end to end (for example the Clef cases in packages/classifiers/test/env.test.ts, …

    line 178
  10. Very specific:

    Update AGENTS.md and docs/architecture.md only where a provider list becomes stale.

    line 183
  11. Very specific:

    Create .changeset/<short-name>.md.

    line 190
  12. Very specific:

    Don't run npm publish or changeset publish.

    line 203
  13. Distinctive:

    Run from the repo root on Node 24:

    line 208

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

Add a classifier

A classifier is a preset in packages/classifiers, selected by name through classifier.provider (plugin) or REASONING_ROUTER_CLASSIFIER (proxy and Pi).

This skill is guidance, not a template. The steps describe how the existing presets (Jev, Clef, Laya) were built, and those all happen to speak some form of the System One API with similar settings. A new classifier may not: it may take different settings, authenticate differently, ask a different question, or answer in a different shape. Treat the repo rules below as fixed, and the steps as a starting point to adapt. When a step doesn't fit, follow its purpose rather than its letter, and say in your summary where and why you departed from it.

Repo rules

These come from AGENTS.md and docs/architecture.md and apply to every classifier.

  • No new package. Add the preset to packages/classifiers. Core stays provider-neutral; put no provider-specific code or dependency in packages/core.
  • HTTP only. Reach the classifier with the injected fetch. If it runs a local model, it is a server the user runs. Never install, download, load, or start a model, its weights, or its runtime, and add no runtime dependency.
  • Protect the credential and the conversation summary. Constrain where the request can go: Jev allows only its known endpoints, and the server presets (server.ts) allow HTTPS or plain HTTP to loopback only, with no credentials, query, or fragment in the URL. Don't accept an arbitrary base URL alongside an API key.
  • Use a distinct provider name, even if the wire protocol matches an existing preset. The name identifies the service in decision logs.
  • Smallest change that works. Core already handles deadlines, retries, and fallback; don't reimplement them. Add no setting without a current requirement.

If this skill and those files disagree, the files win.

When a classifier doesn't fit

The real contract is the Classifier and ClassifierProvider interfaces in packages/core/src/classifier.ts, not the shape of the existing presets. Whatever the service looks like, the preset must produce one of the target model's supported efforts from the bounded state core passes in, and report failures in a way core can categorize and retry. Some ways a classifier might differ, and how to approach them:

  • Different settings. Prefer mapping onto the shared REASONING_ROUTER_CLASSIFIER* settings (apiKey, baseUrl, accountId, model, timeoutMs). If the service truly needs another one, note that core's ClassifierConfig already passes extra fields through to the preset from the plugin's classifier option, but the proxy and Pi read only the variables mapped in packages/classifiers/src/env.ts. A new setting means a new variable there, plus a generic row in every doc that lists the shared variables (step 5); propose it before building it.
  • Different auth or endpoint. Keep the credential safe: send it only to hosts the preset can vouch for.
  • A different question or answer. For example, scores or probabilities instead of a single choice. Translate them into one supported effort inside the preset, and document how.
  • Something the interface can't express, such as needing more of the conversation than the bounded state, or a streaming or multi-call protocol. Stop and raise it with the user instead of bending core or the state to fit one provider.

Typical steps

1. Pick the wire contract

Read packages/classifiers/src/systemone.ts. createSystemOneClassifier already limits choices to the target model's supported efforts, refuses redirects, discards error bodies, categorizes errors, and honors Retry-After. Reuse it when the service fits:

  • A System One server the user runs at {baseUrl}/v1/systemone, with an optional bearer key and model: use createServerPreset(name, defaultBaseUrl) from server.ts, as laya.ts, kev.ts, and clm.ts do. The whole preset file is that call plus the four exports, and step 2 is done.
  • Same System One API at a fixed or credentialed endpoint: pass the URL, key, and model to createSystemOneClassifier, as jev.ts does.
  • System One inside a provider envelope: also pass unwrap to extract the System One response, as clef.ts does for Workers AI's { result, success, errors, messages }.
  • A different contract: translate the request and response in the new preset's file, keeping the same behaviors. Offer only the model's supported efforts, throw ClassifierRequestError with a category, never surface response bodies or credentials in errors, and treat an unsupported answer as invalid output.

2. Write packages/classifiers/src/<name>.ts

Skip this step for a server preset (see step 1). Otherwise clef.ts is the simplest model. Its shape is a convention, not a requirement; only the exported ClassifierProvider is required:

  • a Zod connection schema validated with core's parseConfig, so every problem is reported in one error, with blank optional strings treated as unset;
  • resolve<Name>Connection(config);
  • create<Name>Transport(connection & { fetch?: Fetch }) returning a Classifier;
  • the provider object:
/** Selected by `classifier: { provider: "<name>", ... }`. */
export const <name>ClassifierProvider: ClassifierProvider = {
  name: "<name>",
  create(config: ClassifierConfig): Classifier {
    return create<Name>Transport(resolve<Name>Connection(config));
  },
};

No type assertions: Biome rejects them (as const is the only exception).

3. Register it in packages/classifiers/src/index.ts

Export the provider, transport, resolver, and connection type, and append the provider to classifierProviders. That array is what createConfiguredSelector searches by name.

4. Test it in packages/classifiers/test/<name>.test.ts

Model it on laya.test.ts, or on clef.test.ts for an envelope. A server preset shares Laya's request and URL rules, so clm.test.ts is enough: the default base URL, the provider name in the request, and selection. Inject a fake fetch that records the URL and init. Cover whichever of these apply, plus anything specific to the new contract:

  • the request: URL, headers (including the key only when set), and a body that offers only the target model's supported efforts and omits unset optional fields;
  • a valid answer, and an unsupported or malformed answer (fallback);
  • HTTP error categories, a network error, and Retry-After;
  • config: defaults, every accepted value, and every rejected base URL or missing required field;
  • selection through createConfiguredSelector({ provider: "<name>" }, classifierProviders, {}). This selection test is what proves the provider is registered; no test lists every provider name.

5. Update the docs and examples

Per-provider settings (defaults, which settings are required, accepted model values) are documented in one place: packages/classifiers/README.md. Document the settings the new one actually uses; if it has setup steps (an account, a server to run), describe those the way the root README's Laya section does.

  • packages/classifiers/README.md: a section with a settings table.
  • Root README.md: a setup subsection under "Classifiers" and the provider list in the package description.
  • packages/classifiers/package.json: the description and keywords.
  • The README_CN.md, README_JA.md, and README_KO.md beside every README edited above: make the same change in Chinese, Japanese, and Korean.

Leave docs/environment.md, .env.example, and the OpenCode and Pi READMEs alone: they describe the shared variables generically and link to the classifiers README. The proxy --help lists provider names from classifierProviders itself. Touch those only if the classifier adds a new shared variable, and then add a generic row, not per-provider details.

6. Sweep for missed spots

The existing names are the checklist. Every hit that lists them should now include the new one:

rg -n -i 'laya|clef' --glob '!**/CHANGELOG.md' --glob '!package-lock.json' --glob '!.agents/**'

Not every hit is a list. Tests that exercise one provider end to end (for example the Clef cases in packages/classifiers/test/env.test.ts, packages/opencode/test/plugin-v2.test.ts, and packages/pi/test/config.test.ts), research notes in docs/harnesses/, and docs/proposals/<provider>.md describe a single provider; leave them alone. Update AGENTS.md and docs/architecture.md only where a provider list becomes stale. A hit in docs/environment.md, .env.example, or the OpenCode or Pi READMEs is an example value, not a list to extend; don't add per-provider details there (step 5).

7. Add a changeset

Create .changeset/<short-name>.md. The classifiers package gets minor, because a new preset is a new feature. Bump other packages only if their published behavior changed; the proxy's help text updates on its own, so it usually needs no bump.

---
"@reasoning-router/classifiers": minor
---

Add the <Name> classifier (`provider: "<name>"`), ...

Don't run npm publish or changeset publish; releases go through the release workflow.

8. Verify

Run from the repo root on Node 24:

  • npm run check (typecheck, Biome, Vitest) must pass.
  • npm run smoke:package packs, installs, and runs the packages.

Report the commands you ran and their results. If you couldn't call the real service, say so; fake-fetch tests prove the contract you assumed, not that the service accepts it.

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.