# Decisions

> How to use `@agent-native/core/decisions` for capability-aware classification and scoring. Use when implementing or reviewing decision evaluation, provider ordering, per-provider thresholds, or decision-result caches.

- Skill: `builderio/decisions` (Agent Skill)
- Install (CLI): `npx get-skill add builderio/decisions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/builderio/decisions/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Builder.io (https://skillmd.com/u/builderio)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/builderio/decisions

---


# Decisions

## Rule

Use `decide()` to classify or score supplied inputs. It returns a result and
never performs, authorizes, or replaces the action selected from that result.

## How

Pass an explicit `ownerEmail`, an `input` string or array of parts, and named
`questions` to `decide()` from `@agent-native/core/decisions`:

```ts
import { decide } from "@agent-native/core/decisions";

const result = await decide({
  ownerEmail: "owner@example.com",
  input: [{ type: "text", text: "Please cancel Friday's lunch reservation." }],
  questions: [
    {
      type: "predicate",
      name: "isCancellationRequest",
      instructions: "Does the message ask to cancel a reservation?",
    },
  ],
});
```

`input` can be a plain string or contain text, structured JSON, or an image URL.
Questions are named and use one of these shapes:

| Type | Fields | Use |
| --- | --- | --- |
| `predicate` | `name`, `instructions` | Evaluate one stated predicate |
| `choice` | `name`, `instructions`, `choices: { value: string, description: string }[]` | Choose among the supplied string values |
| `score` | `name`, `instructions`, `levels: { label: string, description: string }[]` | Score against 2–10 ordered levels |

Provider and model capabilities can differ. Treat question support as
capability-aware. Only claim a provider/model supports a question type after
that combination has been verified. An `ok` result includes `provider`, `model`, and `answers` keyed by question name;
`cached` and `usage` are optional. A `not_configured` result includes the
`missing_credentials` reason and configured provider list. A `failed` result has
a typed reason and may include `provider` and `questionNames`. Handle these
statuses as distinct outcomes; never turn a failure into an answer.

## Provider routing and caches

Provider order is configurable per workspace. New customer workspaces try
Builder Jev first, then a personal Jev key, then OpenAI. Within Jev, the
Builder gateway is tried before falling back to a direct key. If no provider
is configured, `decide()` returns `not_configured`.

`getDecisionsStatus()` reports credential readiness separately from provider
capabilities. The Builder Jev proxy is verified for `predicate` and `choice`.
Jev `score` remains unverified and disabled by its capability flag, so
`decide()` skips Jev for score questions and continues to the next configured
provider. A Jev-only score request returns `failed` with
`unverified_capability`. The OpenAI Decisions API supports scores with 2–10
ordered levels; its request and response mapping is covered by documented
fixtures.

Key any per-provider threshold or cache by both provider and model. `cacheKey`
enables caching only when supplied. Cache identity includes the owner,
organization, provider, model, cache key, input, and questions. The in-memory
cache has a 60-second TTL and a 256-entry cap.

## Related skills

- **actions** — keep action behavior focused and deterministic.

