---
title: "The typesafe-ai agent skill and Claude Code plugin"
type: reference
tags: [agent-skill, claude-code, plugin, skills, installation]
created: 2026-09-17
updated: 2026-09-21
confidence: high
sources:
  - raw/docs/agent-skill.md
  - raw/github/skills/README.md
  - raw/github/skills/skills/typesafe-ai/SKILL.md
  - raw/github/skills/.claude-plugin/plugin.json
  - raw/github/skills/.claude-plugin/marketplace.json
  - raw/x/k2sbhai-2101657436696547773-image.md
  - raw/x-repos/ryana__jevify.md
jev_version: "jev-1.13.0"
summary: "Install, update, and invoke the typesafe-ai agent skill (Claude Code plugin typesafe 0.5.7, MIT), plus a faithful digest of the guidance SKILL.md gives agents."
---

# The typesafe-ai agent skill and Claude Code plugin

> **TL;DR** `claude plugin marketplace add typesafe-ai/skills` then `claude plugin install typesafe@typesafe-ai` (Claude Code), or `npx skills add typesafe-ai/skills --skill typesafe-ai` (other agents, `-g` for global). Invoke with `/typesafe:typesafe-ai` or by saying "use the TypeSafe skill". The skill's core instruction to agents is that the **live docs are the source of truth** — and Mintlify serves any docs page as Markdown by appending `.md`.

## Facts

| Field | Value | Source |
|---|---|---|
| Skill name | `typesafe-ai` | SKILL.md frontmatter `name` |
| Plugin name | `typesafe` | `.claude-plugin/plugin.json` |
| Plugin version | `0.5.7` | `.claude-plugin/plugin.json` |
| Marketplace name | `typesafe-ai` | `.claude-plugin/marketplace.json` |
| Plugin description | "Agent skills for building with the TypeSafe System One API." | plugin.json |
| Marketplace plugin entry description | "Full context on the TypeSafe API: question types, architectural patterns, and best practices" | marketplace.json |
| Plugin source | `./` (repo root) | marketplace.json |
| Author / owner | TypeSafe AI, https://typesafe.ai | plugin.json, marketplace.json |
| Homepage | https://typesafe.ai | plugin.json |
| Repository | https://github.com/typesafe-ai/skills | plugin.json |
| License | MIT | plugin.json, SKILL.md frontmatter, repo `LICENSE` ("Copyright (c) 2026 TypeSafe AI") |
| Skill path in repo | `skills/typesafe-ai/SKILL.md` | README.md |
| Raw SKILL.md URL | https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md | docs + README |
| Repo commit captured | `65a39f393687675ce170e6094757de20370365b9` | raw/MANIFEST.json |

Note the version mismatch to be aware of: the **plugin** is at `0.5.7` while the Python and JS SDKs are at `0.6.0`. The plugin version does not track the SDK version.

## What it is

From `raw/docs/agent-skill.md`: "Drop-in skill for Claude Code, Codex, and other agent environments."

> The TypeSafe agent skill gives your AI coding agent full context on the TypeSafe API: the three question [types](/primitives), the architectural [patterns](/patterns), and best practices for structuring evaluations.

The repo README frames it as: "Agent skills for building with [TypeSafe](https://typesafe.ai): typed decisions and probabilities from System One models."

The skill table in the README lists exactly one skill:

| Skill | Purpose |
|---|---|
| `typesafe-ai` | Design TypeSafe workflows, find current docs and cookbooks, and compose typed judgments in code |

SKILL.md's own `description` frontmatter says when an agent should load it: "Use when a feature needs programmable common sense, when brainstorming what AI could make possible in an app, or when an LLM prompt-and-parse step could become a structured decision. Applications include routing, ranking, extraction, verification, and interactive experiences; these are starting points, not the limits."

## Installation

### Claude Code plugin

> Run these two commands in your terminal:

```bash
claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai
```

### Other agents (skills.sh)

```bash
npx skills add typesafe-ai/skills --skill typesafe-ai
```

> Choose your agent when prompted. Installation is project-local by default; add `-g` to install globally.

```bash
npx skills add typesafe-ai/skills --skill typesafe-ai -g
```

### Copy-to-your-agent prompt

The docs supply a prompt to paste into any coding agent, verbatim:

```text
Install the TypeSafe skill. If you're in Claude Code, run `claude plugin marketplace add typesafe-ai/skills`, then `claude plugin install typesafe@typesafe-ai`. If you're in another agent, run `npx skills add typesafe-ai/skills --skill typesafe-ai` and select your agent. Use one installation method. You can read the skill directly at https://github.com/typesafe-ai/skills/blob/main/skills/typesafe-ai/SKILL.md (raw: https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md). Then use the TypeSafe skill when working on this project.
```

### Manual installation

> For manual installation, copy the entire [skills/typesafe-ai directory](https://github.com/typesafe-ai/skills/tree/main/skills/typesafe-ai), including its reference files, into your agent's skills directory.

**Choose one installation method to avoid duplicate copies.**

### Updates

For the Claude Code plugin:

```bash
claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-ai
```

> Restart Claude Code or run `/reload-plugins` to load the update. To enable automatic updates, open `/plugin`, select **Marketplaces → typesafe-ai → Enable auto-update**.

For skills.sh installations:

```bash
npx skills update
```

> For manual copies, replace the entire skill directory with the latest GitHub version.

## Invocation

> Naming the skill in your prompt — "use the TypeSafe skill" — works in any agent [...] With the Claude Code plugin, you can also invoke `/typesafe:typesafe-ai` directly.

The README's example ask: "Use TypeSafe to route incoming support tickets by department, with human review for uncertain decisions."

Example prompts from the docs, verbatim:

```text
Using the TypeSafe skill, explore the project and find opportunities for using
intelligent judgement to stand in for complex parsing or other fragile code.
```

```text
Using the TypeSafe skill, run some experiments using the TypeSafe API key that I've
exported to `TYPESAFE_API_KEY`. Propose changes based on the most promising results.
```

```text
Using the TypeSafe skill, analyze my code and see if there are any applicable
cookbooks (https://console.typesafe.ai/docs/cookbooks) that show how I could
refactor my code to be less fragile or complex.
```

A longer community prompt for the same job is [`ryana/jevify`](https://github.com/ryana/jevify) (no licence, so linked rather than copied; pointed to by [@mathfax](https://x.com/mathfax/status/2102111616175403215), who appears to work at TypeSafe, as an example of teaching agents to use Jev). It has the agent read the docs, inspect the project, sort opportunities into direct savings, better outcomes and new capabilities, look for design assumptions that only exist because semantic computation used to be expensive, compare each idea with simpler alternatives (rules, caching, embeddings, conventional classifiers), and design an evaluation that could prove the idea wrong. See [[ideas/repos-agents]].

Community audit prompt (not from TypeSafe; circulated by [@k2sbhai](https://x.com/k2sbhai/status/2101657436696547773), 2026-09-20). Read-only, so a safe first step on an existing codebase. With the Claude Code plugin the slash form is `/typesafe:typesafe-ai`, not `/typesafe-ai`. For the same audit without installing the skill, see [[ideas/consult]].

```text
Use /typesafe-ai to audit this project. Find every place where we make a slow or expensive LLM call
that is really a yes or no decision, a ranking, or a classification. For each one, tell me what Jev would
replace, what it would cost, and what would break if the answer is wrong. Then list 3 new features this
project could add if judgments were instant and nearly free. Don't change any code yet. Show me the list first.
```

The docs suggest creating an API key at https://console.typesafe.ai/keys for the experiment prompt — [[guides/quickstart]] cites https://console.typesafe.ai/settings/keys instead. Use https://console.typesafe.ai and navigate to the API keys page; both paths are cited upstream and the console may redirect. See [[entities/typesafe-console]] and [[reference/environment-variables]].

## What SKILL.md tells the agent

### Read the live docs — and fetch them as Markdown

> **The live TypeSafe docs are the source of truth. Read them as part of the task.** This skill gives direction; the docs carry current concepts, prompting guidance, API contracts, SDK usage, models, limits, and worked examples.

Concrete rules it gives:

- Start at the documentation index, https://docs.typesafe.ai/llms.txt, "to discover relevant pages and cookbooks. Use targeted reads rather than loading the entire site."
- **Mintlify serves Markdown by appending `.md` to a page path** — for example https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md. "Follow links from the index; convert extensionless documentation page links to `.md` when useful. Resolve relative links against `https://docs.typesafe.ai`."
- "Before writing an integration, read the current API or chosen SDK page and the question guidance relevant to the design. For a new workflow, also inspect the closest cookbook: it often shows a better decomposition than a generic classifier."
- Fallbacks: "If the index is unavailable, use the direct links below or the site's navigation. If Markdown fetching fails, try the normal page. If live access is unavailable, use available local docs or installed SDK types, state that limitation, and avoid inventing version-dependent details."

The task → docs table, reproduced from SKILL.md (wiki equivalents added in the third column):

| Task | Start here; follow the relevant details | Wiki equivalent |
|---|---|---|
| Understand the programming model | System One (`/concepts/system-one.md`), building guide (`/concepts/how-to-build-with-system-one.md`) | [[concepts/system-one]], [[concepts/how-to-build]] |
| Explore what to build | Use-case map (`/concepts/use-case-map.md`), then relevant cookbooks from the index | [[concepts/use-case-map]], [[cookbooks/overview]] |
| Prepare inputs and questions | State (`/concepts/state.md`), primitives (`/primitives.md`), then the chosen primitive's page | [[concepts/state]], [[concepts/primitives]] |
| Decide how to handle uncertainty | Confidence (`/confidence.md`) | [[concepts/confidence]] |
| Write API code | HTTP API (`/api.md`), Python SDK (`/sdk/python.md`), or JavaScript SDK (`/sdk/javascript.md`) | [[reference/http-api]], [[reference/python-sdk]], [[reference/javascript-sdk]] |
| Update an older integration | Migration guide (`/migrating-to-v1.md`) and the installed SDK's current reference | [[reference/migrating-to-v1]] |

### Find the useful shape

> Start from the behavior the user wants: what will the application show, select, change, or hand off? Work backward to the judgments it needs. Keep known rules, calculations, exact lookups, and execution in code. Preserve the user's chosen stack and scope; add TypeSafe where semantic understanding helps.

> When brainstorming or choosing an architecture, consider more than classification. The patterns below are starting points: combine primitives around the user's goal, including ideas that do not fit an established recipe.

The six directions it lists, with the cookbooks each points at:

| Direction | What it means | Pointers |
|---|---|---|
| **Route and fill known arguments** | "A request can select a handler and its typed parameters. Ask useful branch-specific questions up front and consume only the relevant answers." | [[cookbooks/function-calling]], [[patterns/fan-out]] |
| **Select instead of generate** | "Find candidate values or source spans in code, use a judgment to select the intended one, then copy or normalize it. Code can also assemble source text into a formatted document or reading guide." | [[cookbooks/pre-parsed-value-extraction]], [[cookbooks/autoformat]] |
| **Find and judge evidence** | "Retrieve candidates, compare their relevance to a query, and select useful context." | [[cookbooks/rerank]], [[cookbooks/hierarchical-classification]] |
| **Turn judgments into reusable data** | "Score dimensions once, then let code or user controls change weights, thresholds, rankings, and views. With labeled outcomes, those signals can become classical ML features." | [[patterns/composite-scoring]], [[cookbooks/autoresearch-feature-discovery]] |
| **Verify and escalate** | "Check specific claims or fields against their evidence; send uncertain or failing cases to a person or reasoning model." | [[cookbooks/citation-check]], [[cookbooks/sde-cascade]] |
| **Respond to changing state** | "Code can retain goals and observations while fresh judgments guide the next bounded step. Keep inferred state distinct from observed facts, and check freshness before applying a result to a changed situation." | [[concepts/state]] |

> For open-ended requests, offer the few directions that best serve the user's goal and recommend a starting point. For a concrete request, choose the relevant pattern and build; a brainstorm is not a mandatory detour.

### Design the judgments

The primitive-selection table, reproduced:

| Need | Primitive | Important distinction |
|---|---|---|
| One of a defined set | [[concepts/choice\|Choice]] | "Picks one option; its distribution compares competing options" |
| Whether a condition holds | [[concepts/noul\|Noul]] | "Probability of yes; no separate confidence; use one per label when several may apply" |
| Degree along a described dimension | [[concepts/score\|Score]] | "Probability-weighted position on ordered levels; use comparable per-item Scores for graded ranking" |

Rules it gives agents about question construction:

- "Give each question enough relevant **state** to answer: source text, identities, relationships, policies, and current facts. Prefer named JSON fields when context has several parts."
- "Put the judgment in **instructions** and define its possible answers in **criteria**."
- "Question IDs are for code and are not sent to the model; include complete meaning in the question."
- "Reference nested state with backticked paths such as `` `ticket.messages[0].text` ``."
- "Ask one narrow, coherent judgment per question. Split independently useful dimensions, without destroying the relationship being judged. A bounded action selection or contextual interpretation is valid; atomic does not mean literal fact extraction or a one-sentence limit."
- "Strings work for simple questions. Use structured objects or arrays when definitions, contrasts, exclusions, or examples clarify instructions or criteria." See [[concepts/advanced-structure]].
- "Score levels must describe concrete situations and stand on their own."
- "Keep the needed answers available. Include a no-match outcome when nothing may fit; use a separate presence judgment when it is independently useful. For source-value selection, check candidate coverage: the model cannot choose an omitted value."

### Compose and verify

- "**Ask independent questions over the same state together**, including useful speculative questions. They run in parallel and cannot see one another's answers. State each speculative premise explicitly; code consumes the applicable answers." See [[patterns/fan-out]].
- "A second request is warranted when an earlier answer is needed to fetch evidence, construct new state, or determine the next options. Extra questions still use tokens; measure actual request budgets, cost, and end-to-end latency."
- "Use probabilities and confidence to guide behavior, with thresholds evaluated on the user's data and consequences. Choice/Score confidence summarizes distribution concentration, not overall workflow correctness or permission to act. A Noul near 0.5 means similar probability for yes and no, not medium intensity. Several acceptable alternatives can also spread probability; low confidence need not invalidate a harmless preference choice. Ignore uncertainty on unused branches."
- "Keep policy explicit and raw judgments reusable. Weighted scores suit compensating preferences; an 'any serious violation' rule needs separate conditions. Changing a weight or display filter need not rerun inference when evidence and question meanings are unchanged."
- "Typed output guarantees the interface, not truth. System One models are trained for calibrated decisions; validate their performance in the target domain."
- "Test representative cases and the resulting application behavior. For failures, inspect the exact state, questions, candidates, answers, composition, and observed outcome. Separate missing evidence, model errors, code errors, and service failures."
- "Treat cookbook thresholds and demo results as examples to evaluate, not universal rules or permanent model limitations."
- "**Keep API credentials server-side in web apps.**"

## Good vibe coding principles

The docs page's four rules for humans working with an agent that has the skill, verbatim:

1. "Talk it out with your agent, using the example prompts above as a starting point."
2. "Review the plan and ensure it makes sense before implementing it."
3. "Put the constants (questions and thresholds) in a single place so they're easy to review. Agents aren't great at writing questions, so expect to edit collaboratively with them."
4. "Don't take assertions at face value; encourage the agent to validate its assumptions."

## Common issues

| Symptom | Fix (from `raw/docs/agent-skill.md`) |
|---|---|
| The agent isn't using the skill | "With the Claude Code plugin, invoke `/typesafe:typesafe-ai`. In other agents, ask to 'use the TypeSafe skill'. If it still does not load, confirm the installer targeted the agent you are using, then restart the agent." |
| Routing isn't working like you expect | "Check the questions and thresholds. It's possible that your thresholds are either set too high (causing false negatives) or too low (causing false positives). You may also need to tweak your questions to be more specific." |
| You're using confidence thresholds everywhere | "If all you care about is choosing the best option, you just need to choose the option with the highest confidence (rather than setting a confidence threshold). If you have a specific statistical algorithm in mind, you should probably be using probabilities instead of confidence." |
| It's difficult to review TypeSafe code | "The most important thing for humans to review is the questions and any threshold constants used in your TypeSafe code. These should be defined in a single code file so that they're easy to find without too much spelunking." |
| The agent invents request or response fields | "A stale skill can cause this. Update it using your installation method above and retry." |

## Version notes

- Plugin `typesafe` version `0.5.7`, MIT, captured at repo commit `65a39f393687675ce170e6094757de20370365b9` (GitHub org listing puts the last push to `typesafe-ai/skills` at 2026-09-12).
- SKILL.md carries no version field of its own; it is versioned with the plugin.
- The skill deliberately hard-codes as little as possible — versioned details (models, limits, SDK signatures) are delegated to the live docs, which is why a stale skill mainly shows up as invented fields rather than wrong numbers.

## Related

- [[entities/github-repos]] — the `typesafe-ai/skills` repo in context
- [[guides/agent-integration-playbook]] — the wiki's own version of this guidance
- [[guides/quickstart]] — "Vibe it: the agent skill" is step four of the quickstart
- [[concepts/primitives]] — the three question types the skill routes you to
- [[cookbooks/overview]] — the cookbook index the skill tells agents to consult
- [[patterns/overview]] — the patterns the skill names as starting points
- [[entities/typesafe-console]] — where the API key comes from

## Sources

- raw/x/k2sbhai-2101657436696547773-image.md (https://x.com/k2sbhai/status/2101657436696547773) — community audit prompt
- raw/docs/agent-skill.md (https://docs.typesafe.ai/agent-skill)
- raw/github/skills/README.md (https://github.com/typesafe-ai/skills)
- raw/github/skills/skills/typesafe-ai/SKILL.md (https://github.com/typesafe-ai/skills/blob/main/skills/typesafe-ai/SKILL.md)
- raw/github/skills/.claude-plugin/plugin.json (https://github.com/typesafe-ai/skills)
- raw/github/skills/.claude-plugin/marketplace.json (https://github.com/typesafe-ai/skills)