@openhands/extensions 0.24.0 → 0.26.0

package/skills/openhands-api/SKILL.md

@@ -177,7 +177,7 @@ When you start a delegated Cloud conversation:
 3. Start the new conversation with `POST /api/v1/app-conversations`.
 4. Poll the start-task until `status` is `READY` and you have an `app_conversation_id`.
 5. Monitor the delegated conversation via `GET /api/v1/app-conversations?ids=...`.
-6. Share or store the Cloud URL: `https://app.all-hands.dev/conversations/<app_conversation_id>`.
+6. Share or store the conversation's `conversation_ui_url` from that response. It opens the conversation in Agent Canvas. If the server does not return it, use `<base_url>/canvas/conversations/<app_conversation_id>`, where `<base_url>` is the server you called the API on. Never share `conversation_url`; it is the sandbox's agent-server API, not a page users can open.
 
 ### Minimal cURL flow
 
@@ -200,7 +200,7 @@ curl -s "https://app.all-hands.dev/api/v1/app-conversations/start-tasks?ids=${ST
   -H "Authorization: Bearer ${OPENHANDS_CLOUD_API_KEY}"
 ```
 
-Then check execution status:
+Then check execution status and get the link to share (`conversation_ui_url`):
 
 ```bash
 curl -s "https://app.all-hands.dev/api/v1/app-conversations?ids=${APP_CONVERSATION_ID}" \
@@ -229,7 +229,7 @@ if not ready.get("app_conversation_id"):
     ready = api.poll_start_task_until_ready(start["id"])
 
 conversation_id = ready["app_conversation_id"]
-print(f"Delegated conversation: {api.base_url}/conversations/{conversation_id}")
+print(f"Delegated conversation: {api.app_conversation_ui_url(conversation_id)}")
 
 status = api.app_conversation_get(conversation_id)
 print(status.get("sandbox_status"), status.get("execution_status"))

package/skills/openhands-api/scripts/openhands_api.py

@@ -129,6 +129,19 @@ class OpenHandsAPI:
         items = self.app_conversations_get_batch(ids=[conversation_id])
         return items[0] if items else None
 
+    def app_conversation_ui_url(self, conversation_id: str) -> str:
+        """Browser link that opens the conversation in Agent Canvas.
+
+        Share this link with users. `conversation_url` on the conversation record is
+        the sandbox's agent-server API, not a page a user can open.
+        """
+        conversation = self.app_conversation_get(conversation_id) or {}
+        # Servers that predate `conversation_ui_url` serve Agent Canvas at /canvas.
+        return (
+            conversation.get("conversation_ui_url")
+            or f"{self.base_url}/canvas/conversations/{conversation_id}"
+        )
+
     def sandboxes_search(self, *, limit: int = 20) -> dict[str, Any]:
         limit = max(1, int(limit))
         r = self._client.get(f"{self.api_v1_url}/sandboxes/search", params={"limit": limit})

package/skills/openhands-automation/SKILL.md

@@ -47,7 +47,7 @@ The agent server typically runs inside a **sandbox** (a Docker or Kubernetes con
 | Variable | Availability | Description |
 |---|---|---|
 | `RUNTIME_URL` | Ambient in cloud environments | Public-facing URL of the **agent server** sandbox. Use this to determine whether external webhook delivery is possible — if unset or local, webhooks cannot be received. The automation service may run at a separate URL (see Determining the API Host). |
-| `AGENT_SERVER_URL` | Injected into scripts at run time only | Internal URL of the agent server. Available inside script execution context; **not** an ambient environment variable outside of a running script. |
+| `AGENT_SERVER_URL` | Injected into scripts at run time, local Agent Canvas only | Internal URL of the agent server. Available inside script execution context; **not** an ambient environment variable outside of a running script, and not set on OpenHands Cloud or Enterprise. |
 | `OPENHANDS_HOST` | Shell convention only — set manually | Base URL for the automation service API. **Not a real environment variable.** Set it from an explicit host, a detected local Agent Canvas server, or the cloud default. Used in all `curl` examples throughout this skill. |
 
 > **⚠️ CRITICAL — Agent behavior rules:**
@@ -77,17 +77,22 @@ The agent server typically runs inside a **sandbox** (a Docker or Kubernetes con
 
 ### No-LLM Script Helpers
 
-When building a deterministic custom script, these two stdlib-only functions are required. Copy them verbatim — they use `AGENT_SERVER_URL` and `SESSION_API_KEY` injected by the automation service.
+When building a deterministic custom script, these two stdlib-only functions are required. Copy them verbatim - they use variables injected by the automation service: `SESSION_API_KEY`, plus `AGENT_SERVER_URL` on a local Agent Canvas or `OPENHANDS_CLOUD_API_URL` and `SANDBOX_ID` on OpenHands Cloud and Enterprise.
 
 ```python
 import json, os, urllib.request
 
 def get_secret(name):
-    """Fetch a named secret stored in the agent server."""
+    """Fetch a named secret: from the agent server when AGENT_SERVER_URL is set, else from the OpenHands API."""
     url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
     key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
+    if url:  # local Agent Canvas
+        url = f"{url}/api/settings/secrets/{name}"
+    else:  # OpenHands Cloud / Enterprise
+        api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
+        url = f"{api}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}"
     with urllib.request.urlopen(urllib.request.Request(
-        f"{url}/api/settings/secrets/{name}", headers={"X-Session-API-Key": key}
+        url, headers={"X-Session-API-Key": key}
     )) as r:
         return r.read().decode().strip()
 
@@ -498,6 +503,7 @@ For services other than GitHub (Linear, Stripe, Slack, etc.), register a custom
 
 > **Agent behavior:**
 > - **Always provide the curl request** to the user — do not attempt to register webhooks yourself.
+>   The exception is a service skill that ships a setup script for its webhook, such as `jira-issue-to-pr`: the script registers both sides and keeps the signing secret out of the conversation, so run it as that skill describes.
 > - **Ask the user:** "Do you have a webhook signing secret from [service], or should the system generate one?"
 >   - If they have one → include `webhook_secret` in the request
 >   - If not → omit it; the response will contain a generated secret they must configure in their service
@@ -619,11 +625,67 @@ curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   }'
 ```
 
+### Custom Webhook Example: Jira Cloud
+
+Jira Cloud sends webhooks with:
+- Signature header: `X-Hub-Signature` (`sha256=` followed by the hex HMAC-SHA256 of the body), sent only when the webhook has a secret
+- Event type in payload: `webhookEvent` field (e.g., `jira:issue_created`, `jira:issue_updated`)
+- Labels as plain strings: `issue.fields.labels` is `["create-pr"]`, not a list of objects, so `issue.fields.labels[].name` matches nothing
+- On an update, a `changelog.items` list naming each changed `field`
+
+Only a webhook a Jira admin registers (Jira settings → System → WebHooks, or the REST API) can carry a secret. The "Send web request" action of a Jira Automation rule cannot sign its request, so it cannot deliver to a custom webhook.
+
+When the user can supply the API token of a Jira administrator, `scripts/setup_webhook.py` in the `jira-issue-to-pr` skill registers the webhook on both sides for them, replacing step 1 and the Jira configuration below. Done by hand:
+
+```bash
+# 1. Register the Jira webhook
+#    - Use "X-Hub-Signature" as the signature header
+#    - Use "webhookEvent" to extract the event type from the payload
+#    - Omit webhook_secret to have one generated, or pass the one Jira generated
+curl -X POST "${OPENHANDS_HOST}/api/automation/v1/webhooks" \
+  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Jira Cloud",
+    "source": "jira",
+    "event_key_expr": "webhookEvent",
+    "signature_header": "X-Hub-Signature"
+  }'
+
+# Response includes webhook_url and the generated webhook_secret - configure both in Jira:
+# Jira settings → System → WebHooks → Create a WebHook → paste the webhook_url and the
+# secret, then select the issue events. A JQL filter such as `labels = create-pr` keeps
+# unrelated issues from being sent at all.
+
+# 2. Create an automation for issues that receive a label
+#    The filter matches an issue created with the label and an update that changes the
+#    labels of an issue carrying it. Without the changelog check, every later edit of a
+#    labelled issue would start another run. It still fires when another label is added
+#    to or removed from an issue that carries the label, so have the prompt skip an
+#    issue that already has a pull request.
+curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
+  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Jira Issues Labelled create-pr",
+    "prompt": "A Jira issue received the create-pr label. Read the issue from the event payload and open a pull request for it.",
+    "trigger": {
+      "type": "event",
+      "source": "jira",
+      "on": ["jira:issue_created", "jira:issue_updated"],
+      "filter": "contains(issue.fields.labels, '\''create-pr'\'') && (webhookEvent == '\''jira:issue_created'\'' || length(changelog.items[?field == '\''labels'\''] || `[]`) > `0`)"
+    }
+  }'
+```
+
+An unsigned request to the webhook URL answers `401 Missing signature header: X-Hub-Signature`; that is the webhook working, not a fault. `404 Unknown webhook source` means no webhook with that source is registered for the organization in the URL.
+
 ### Common Signature Headers by Service
 
 | Service | Signature Header | Event Key Expression |
 |---------|-----------------|---------------------|
 | Linear | `Linear-Signature` | `type` |
+| Jira Cloud | `X-Hub-Signature` | `webhookEvent` |
 | Stripe | `Stripe-Signature` | `type` |
 | Slack | `X-Slack-Signature` | `type` |
 | Twilio | `X-Twilio-Signature` | `type` |

package/skills/openhands-automation/references/custom-automation.md

@@ -223,7 +223,7 @@ Key points:
 - **Your script and its conversations share the same agent server.** There is no network hop to a remote service.
 - **Conversations are asynchronous.** You can fire one and continue, fire several concurrently, or start none at all (e.g. if your script fetches external data and decides no action is needed).
 - **The completion callback** is sent by `OpenHandsCloudWorkspace.__exit__` when the `with` block exits, telling the automation service the run is done. For async patterns, defer exiting until the conversation is in the desired state.
-- **Secrets** stored in the agent server are accessed via its REST API: `GET {AGENT_SERVER_URL}/api/settings/secrets/{name}` with `X-Session-API-Key: {SESSION_API_KEY}`. SDK scripts can also call `workspace.get_llm()` to get the configured LLM.
+- **Secrets** are fetched over REST with `X-Session-API-Key: {SESSION_API_KEY}`. When `AGENT_SERVER_URL` is set (local Agent Canvas): `GET {AGENT_SERVER_URL}/api/settings/secrets/{name}`. Otherwise (OpenHands Cloud and Enterprise): `GET {OPENHANDS_CLOUD_API_URL}/api/v1/sandboxes/{SANDBOX_ID}/settings/secrets/{name}`. SDK scripts can also call `workspace.get_llm()` to get the configured LLM.
 
 **SDK Documentation:** https://docs.openhands.dev/sdk
 
@@ -421,7 +421,7 @@ with OpenHandsCloudWorkspace(local_agent_server_mode=True, cloud_api_url=api_url
 
 For tasks that don't need AI reasoning — sending a Slack message, calling an API, rotating from a fixed list — skip the SDK entirely. Use pure Python stdlib with `python3 main.py` as the entrypoint and no `setup.sh`.
 
-**Accessing secrets** — custom secrets are not injected into the subprocess environment automatically. Fetch them via the agent server's REST API:
+**Accessing secrets** — custom secrets are not injected into the subprocess environment automatically. Fetch them over REST (from the agent server when `AGENT_SERVER_URL` is set, otherwise from the OpenHands API):
 
 ```python
 import os, urllib.request
@@ -429,8 +429,15 @@ import os, urllib.request
 def get_secret(name: str) -> str:
     url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
     key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
+    if url:
+        # Local Agent Canvas: secrets live in the agent server.
+        url = f"{url}/api/settings/secrets/{name}"
+    else:
+        # OpenHands Cloud / Enterprise: secrets live in the OpenHands API.
+        api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
+        url = f"{api}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}"
     req = urllib.request.Request(
-        f"{url}/api/settings/secrets/{name}",
+        url,
         headers={"X-Session-API-Key": key},
     )
     with urllib.request.urlopen(req) as r:
@@ -627,11 +634,13 @@ def save_state(state: dict) -> None:
 
 ## Environment Variables
 
-The automation service injects these environment variables into every run:
+The automation service injects these environment variables into every run, except where a row says otherwise:
 
 | Variable | Alt name | Description |
 |----------|----------|-------------|
-| `AGENT_SERVER_URL` | — | Agent server URL. Used as `cloud_api_url` for `OpenHandsCloudWorkspace`, and as the base URL for secret lookups |
+| `AGENT_SERVER_URL` | — | Agent server URL. Local Agent Canvas only; not set on OpenHands Cloud or Enterprise. Used as `cloud_api_url` for `OpenHandsCloudWorkspace`, and as the base URL for secret lookups |
+| `OPENHANDS_CLOUD_API_URL` | — | OpenHands API base URL. OpenHands Cloud and Enterprise only. Base URL for secret lookups |
+| `SANDBOX_ID` | — | ID of the sandbox the run executes in. OpenHands Cloud and Enterprise only. Part of the secret lookup URL |
 | `OH_SESSION_API_KEYS_0` | `SESSION_API_KEY` | Session API key. Used as `cloud_api_key` for `OpenHandsCloudWorkspace`, and as `X-Session-API-Key` for REST API calls |
 | `AUTOMATION_CALLBACK_URL` | — | POST here to mark the run complete (done automatically by `OpenHandsCloudWorkspace.__exit__`, or manually in no-LLM scripts) |
 | `AUTOMATION_CALLBACK_API_KEY` | — | Bearer token for the completion callback POST |
@@ -673,7 +682,12 @@ CHANNEL = "C12345678"
 def get_secret(name):
     url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
     key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
-    req = urllib.request.Request(f"{url}/api/settings/secrets/{name}",
+    if url:  # local Agent Canvas
+        url = f"{url}/api/settings/secrets/{name}"
+    else:  # OpenHands Cloud / Enterprise
+        api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
+        url = f"{api}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}"
+    req = urllib.request.Request(url,
         headers={"X-Session-API-Key": key})
     with urllib.request.urlopen(req) as r:
         return r.read().decode().strip()
@@ -823,7 +837,7 @@ The upload limit is 1MB. Reduce your tarball size by:
 ### Run fails instantly with `error_detail: null`
 The script sent `fire_callback("FAILED")` immediately — before doing meaningful work. Common causes:
 - A required secret was empty: the `get_secret()` call failed or returned nothing
-- A missing/wrong `AGENT_SERVER_URL` or `SESSION_API_KEY`
+- A missing/wrong `SESSION_API_KEY`, or a missing `OPENHANDS_CLOUD_API_URL` / `SANDBOX_ID` (`AGENT_SERVER_URL` on a local Agent Canvas)
 - An import error in the entrypoint
 
 Add `"error": str(exc)` to your `fire_callback("FAILED", ...)` call so `error_detail` is populated.

package/skills/openhands-sdk/SKILL.md

@@ -201,6 +201,7 @@ Source: [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/
 - [`56_structured_output.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/56_structured_output.py)
 - [`57_prompt_hooks`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/57_prompt_hooks)
 - [`58_ask_oracle_tool`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/58_ask_oracle_tool)
+- [`59_route_task_to_model.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/59_route_task_to_model.py)
 
 ### [`02_remote_agent_server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server)
 

package/skills/research-brief/SKILL.md

@@ -71,14 +71,14 @@ Construct a prompt that includes:
 
 ### Step 4 — Create the automation
 
-Read the Automation backend URL and auth from `<RUNTIME_SERVICES>`:
-- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`
-- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`
+Set `OPENHANDS_HOST` and `AUTH_HEADER` for the request below:
+- **OpenHands Cloud or Enterprise** - a `<HOST>` value is in your system prompt: use it as `OPENHANDS_HOST`, with `AUTH_HEADER="Authorization: Bearer $OPENHANDS_API_KEY"`
+- **Local Agent Canvas** - an **Automation backend** is listed in `<RUNTIME_SERVICES>`: use its `url_from_agent` as `OPENHANDS_HOST`, with `AUTH_HEADER="X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY"`
 
 Use the **prompt preset** endpoint:
 ```bash
 curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
-  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "$AUTH_HEADER" \
   -H "Content-Type: application/json" \
   -d '{
     "name": "Research Brief Writer",
@@ -87,7 +87,7 @@ curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   }'
 ```
 
-PowerShell note: use `curl.exe` for this exact flag syntax, and replace `${OPENHANDS_HOST}` / `$OPENHANDS_AUTOMATION_API_KEY` with `$env:OPENHANDS_HOST` / `$env:OPENHANDS_AUTOMATION_API_KEY` if running it natively.
+PowerShell note: use `curl.exe` for this exact flag syntax, and replace `${OPENHANDS_HOST}` / `$AUTH_HEADER` with `$env:OPENHANDS_HOST` / `$env:AUTH_HEADER` if running it natively.
 
 ### Step 5 — Confirm
 

package/skills/slack-standup-digest/SKILL.md

@@ -64,14 +64,14 @@ Construct a prompt that includes:
 
 ### Step 4 — Create the automation
 
-Read the Automation backend URL and auth from `<RUNTIME_SERVICES>`:
-- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`
-- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`
+Set `OPENHANDS_HOST` and `AUTH_HEADER` for the request below:
+- **OpenHands Cloud or Enterprise** - a `<HOST>` value is in your system prompt: use it as `OPENHANDS_HOST`, with `AUTH_HEADER="Authorization: Bearer $OPENHANDS_API_KEY"`
+- **Local Agent Canvas** - an **Automation backend** is listed in `<RUNTIME_SERVICES>`: use its `url_from_agent` as `OPENHANDS_HOST`, with `AUTH_HEADER="X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY"`
 
 Use the **prompt preset** endpoint:
 ```bash
 curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
-  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "$AUTH_HEADER" \
   -H "Content-Type: application/json" \
   -d '{
     "name": "Slack Standup Digest",
@@ -80,7 +80,7 @@ curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   }'
 ```
 
-PowerShell note: use `curl.exe` for this exact flag syntax, and replace `${OPENHANDS_HOST}` / `$OPENHANDS_AUTOMATION_API_KEY` with `$env:OPENHANDS_HOST` / `$env:OPENHANDS_AUTOMATION_API_KEY` if running it natively.
+PowerShell note: use `curl.exe` for this exact flag syntax, and replace `${OPENHANDS_HOST}` / `$AUTH_HEADER` with `$env:OPENHANDS_HOST` / `$env:AUTH_HEADER` if running it natively.
 
 ### Step 5 — Confirm
 

package/skills/ticket-to-code-change/SKILL.md

@@ -40,9 +40,12 @@ Ask the user for:
    dependency status, repository, base branch, and provider-specific request
    terminology. Require the agent to run the repository's tests before opening
    the pull request or merge request.
-5. Create the automation through the Automation backend described in
-   `<RUNTIME_SERVICES>`. Use its prompt-preset endpoint and authenticate with
-   the runtime-provided automation API key.
+5. Create the automation through the Automation backend's prompt-preset
+   endpoint. On OpenHands Cloud or Enterprise the backend is the `<HOST>` value
+   in your system prompt, authenticated with
+   `Authorization: Bearer $OPENHANDS_API_KEY`. On a local Agent Canvas it is the
+   Automation backend described in `<RUNTIME_SERVICES>`, authenticated with the
+   runtime-provided automation API key.
 6. Configure the automation to post the OpenHands conversation URL immediately
    and the resulting pull-request or merge-request URL back to the ticket.
 

package/skills/use-jev/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "use-jev",
+  "version": "1.0.0",
+  "description": "Use Jev, a general classifier, for typed choices, scores, and yes/no probabilities in software.",
+  "author": {
+    "name": "OpenHands"
+  }
+}

package/skills/use-jev/.codex-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "use-jev",
+  "version": "1.0.0",
+  "description": "Use Jev, a general classifier, for typed choices, scores, and yes/no probabilities in software.",
+  "author": {
+    "name": "OpenHands"
+  }
+}

package/skills/use-jev/.plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "use-jev",
+  "version": "1.0.0",
+  "description": "Use Jev, a general classifier, for typed choices, scores, and yes/no probabilities in software.",
+  "author": {
+    "name": "OpenHands"
+  }
+}

package/skills/use-jev/README.md

@@ -0,0 +1,66 @@
+---
+name: use-jev
+description: Use Jev, a general classifier, for typed choices, scores, and yes/no probabilities in software.
+triggers:
+- jev
+---
+
+[Jev](https://typesafe.ai) is a newly released general classifier.
+Give it text or application state and typed questions; it returns decisions and
+probabilities your code can use for routing, ranking, extraction, or verification.
+
+Read the upstream [llms.txt](https://docs.typesafe.ai/llms.txt) to find current
+documentation, then follow the pages relevant to the task:
+
+- [Use cases](https://docs.typesafe.ai/concepts/use-case-map.md): explore applications;
+  see worked examples for [function calling](https://docs.typesafe.ai/cookbooks/function_calling.md),
+  [reranking](https://docs.typesafe.ai/cookbooks/rerank_typesafe.md), and
+  [citation checks](https://docs.typesafe.ai/cookbooks/citation_check.md).
+- [Best practices](https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md):
+  provide relevant state, ask focused questions, define clear criteria, and batch
+  independent questions. Keep workflow logic in code.
+- [Confidence](https://docs.typesafe.ai/confidence.md): use uncertainty to decide
+  when to escalate, and validate thresholds on representative data.
+- [Python SDK](https://docs.typesafe.ai/sdk/python.md),
+  [JavaScript SDK](https://docs.typesafe.ai/sdk/javascript.md), or
+  [HTTP API](https://docs.typesafe.ai/api.md): read before integrating.
+
+## Choice, Score, and Noul
+
+| Primitive | Example use | Result |
+| --- | --- | --- |
+| [Choice](https://docs.typesafe.ai/primitives/choice.md) | Route a support request to a team | One option, option probabilities, and confidence |
+| [Score](https://docs.typesafe.ai/primitives/score.md) | Rate a bug's impact | Probability-weighted position on ordered levels, plus confidence |
+| [Noul](https://docs.typesafe.ai/primitives/noul.md) | Check whether a refund is requested | Probability of yes; 0.5 means uncertainty, not medium intensity |
+
+Install `typesafe-sdk` and check that `JEV_API_KEY` is set in the environment,
+otherwise ask the user to provide it.
+This Python example asks one question of each type in a single call:
+
+```python
+import os
+
+from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
+
+with TypeSafeClient(api_key=os.environ["JEV_API_KEY"]) as client:
+    result = client.system_one(
+        state={"ticket": "PDF export fails, but CSV works. Please refund this month."},
+        questions={
+            "team": Choice(
+                instructions="Which team should handle the main issue in the ticket?",
+                criteria={"billing": "Charges and payments",
+                          "technical": "Broken product features", "other": "Neither"},
+            ),
+            "impact": Score(
+                instructions="How much does the reported bug affect functionality?",
+                criteria=["Cosmetic only", "Feature broken; workaround available",
+                          "Work blocked; no workaround available"],
+            ),
+            "refund": Noul(instructions="Does the ticket explicitly request a refund?"),
+        },
+    )
+
+print(result.choices["team"].choice)
+print(result.scores["impact"].score)
+print(result.nouls["refund"].noul)
+```

package/skills/use-jev/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: use-jev
+description: Use Jev, a general classifier, for typed choices, scores, and yes/no probabilities in software.
+triggers:
+- jev
+---
+
+[Jev](https://typesafe.ai) is a newly released general classifier.
+Give it text or application state and typed questions; it returns decisions and
+probabilities your code can use for routing, ranking, extraction, or verification.
+
+Read the upstream [llms.txt](https://docs.typesafe.ai/llms.txt) to find current
+documentation, then follow the pages relevant to the task:
+
+- [Use cases](https://docs.typesafe.ai/concepts/use-case-map.md): explore applications;
+  see worked examples for [function calling](https://docs.typesafe.ai/cookbooks/function_calling.md),
+  [reranking](https://docs.typesafe.ai/cookbooks/rerank_typesafe.md), and
+  [citation checks](https://docs.typesafe.ai/cookbooks/citation_check.md).
+- [Best practices](https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md):
+  provide relevant state, ask focused questions, define clear criteria, and batch
+  independent questions. Keep workflow logic in code.
+- [Confidence](https://docs.typesafe.ai/confidence.md): use uncertainty to decide
+  when to escalate, and validate thresholds on representative data.
+- [Python SDK](https://docs.typesafe.ai/sdk/python.md),
+  [JavaScript SDK](https://docs.typesafe.ai/sdk/javascript.md), or
+  [HTTP API](https://docs.typesafe.ai/api.md): read before integrating.
+
+## Choice, Score, and Noul
+
+| Primitive | Example use | Result |
+| --- | --- | --- |
+| [Choice](https://docs.typesafe.ai/primitives/choice.md) | Route a support request to a team | One option, option probabilities, and confidence |
+| [Score](https://docs.typesafe.ai/primitives/score.md) | Rate a bug's impact | Probability-weighted position on ordered levels, plus confidence |
+| [Noul](https://docs.typesafe.ai/primitives/noul.md) | Check whether a refund is requested | Probability of yes; 0.5 means uncertainty, not medium intensity |
+
+Install `typesafe-sdk` and check that `JEV_API_KEY` is set in the environment,
+otherwise ask the user to provide it.
+This Python example asks one question of each type in a single call:
+
+```python
+import os
+
+from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
+
+with TypeSafeClient(api_key=os.environ["JEV_API_KEY"]) as client:
+    result = client.system_one(
+        state={"ticket": "PDF export fails, but CSV works. Please refund this month."},
+        questions={
+            "team": Choice(
+                instructions="Which team should handle the main issue in the ticket?",
+                criteria={"billing": "Charges and payments",
+                          "technical": "Broken product features", "other": "Neither"},
+            ),
+            "impact": Score(
+                instructions="How much does the reported bug affect functionality?",
+                criteria=["Cosmetic only", "Feature broken; workaround available",
+                          "Work blocked; no workaround available"],
+            ),
+            "refund": Noul(instructions="Does the ticket explicitly request a refund?"),
+        },
+    )
+
+print(result.choices["team"].choice)
+print(result.scores["impact"].score)
+print(result.nouls["refund"].noul)
+```