Developing Alongside Claude Code: TypeSafe Agent Skill
The first three lessons broke down the official four architecture patterns: parallel questions and speculative fan-out, smart routing, composite scoring. As noted in the stage overview, lesson 4 answers the last question: who writes this code.
The official answer: your coding agent writes it—provided you install the TypeSafe Agent Skill, an official skill that packages TypeSafe question types, architecture patterns, and request syntax into the agent's workflow. This lesson also dismantles a popular misconception: Jev is not meant to replace the model behind Claude Code. The whole lesson takes 10 minutes.
What You'll Be Able to Do After This Lesson
- Install the TypeSafe Agent Skill in Claude Code with two commands, one
npxcommand for other agents (such as Codex), and explain how updates and auto-updates work - Drive the agent with 3 official example prompts: explore the project to find integration points, run cheap experiments with your API key, and propose refactors against the official cookbook
- Explain the division of labor between Jev and the coding agent: the agent writes code, Jev makes judgments in the code—there is no configuration that swaps the model behind the agent for Jev
- Organize Jev integrations around "questions and thresholds in one file" so the agent's output is reviewable and collaboratively editable
- Use the official troubleshooting paths for 5 common issues to locate failures: skill not loading, fabricated fields, routing not matching expectations…
Your Current Predicament
- I asked Claude Code to integrate Jev into my project; it hadn't read the docs and just started writing: field names were made up (e.g., reading
.confidencefrom a Noul answer—Noul doesn't even have that field), and it errored on the first run. I pasted half a page of docs, and after fixing one spot it fabricated another - I like Jev's "fast and cheap, answers with probabilities" and want to find integration points in my project, but the official docs run over a hundred pages and I don't know where to have the agent start reading; picking pieces to translate into the prompt myself, I always miss key rules
- I don't dare ship the agent-written questions: option descriptions are vague, one question crams in three judgments, thresholds are hard-coded arbitrarily. The code runs, but the answers are unstable; during review the question definitions are scattered across five files and impossible to wade through
When to Use This Technique
When you need to:
- Have agents like Claude Code and Codex write correct Jev call code directly—without pasting the docs into the context every time
- Systematically survey an existing project: which complex parsing, keyword tables, and fragile heuristics can be replaced with a typed question
- Have the agent validate question wording with real API experiments instead of asserting "it should work" off the top of its head
And you don't want to:
- Manually feed docs: it costs context, and you can't feed it all
- Repeatedly correct the agent's fabricated fields and outdated usage
- Receive a pile of integration code with question definitions scattered everywhere that no one can review
These are exactly the applicable scenarios written in SKILL.md: when building, reviewing, or debugging code that calls TypeSafe; when replacing "LLM prompt then parse", keyword matching, or fragile heuristics with typed questions; or when brainstorming where "programmable common sense" can fit into your application.
🎒 Prerequisites
- Read the Efficient Workflows stage overview: know that this lesson is lesson 4 of the stage, answering "who writes the code"
- Have Claude Code installed, or another coding agent you use (Codex, Cursor, opencode, etc.)—this lesson does not cover installing the agent itself
- To run the experiment in step 4: the
TYPESAFE_API_KEYfrom the first request lesson still works; if you don't have one, create it at console.typesafe.ai/keys - Ideally have a real project at hand—the example prompt in step 3 has the agent analyze your code
Core Idea
First, get the position of Jev straight. The official coding-agents document states it plainly: Jev is not a direct replacement for the LLM behind Claude Code, Cursor, opencode, Copilot, Muse Spark, Grok Bot, or similar tools; you keep using your coding agent as usual and have it write code that "calls Jev to make decisions".
Jev is System One decision model: it does not generate text, write code, or hold conversations—it only answers typed questions. In the official words: there is no model: "jev-latest" configuration that turns your coding agent into a Jev-driven agent—the two systems solve different problems.
So what does the TypeSafe Agent Skill actually install? It's not a model swap — it gives the agent context. The official definition of a skill: it provides the coding agent with complete context about the TypeSafe API — the task types, architecture patterns, and best practices for organizing requests. Plus a "live docs guide": SKILL.md explicitly instructs the agent to treat docs.typesafe.ai as the source of truth for request syntax, SDKs, and limits, rather than relying on training memory.
| Dimension | Agent without the skill | Agent with the skill |
|---|---|---|
| API fields | Written from memory; field names may be made up | Written per official question types; consult live docs when unsure |
| Question design | Cram all judgments into one prompt, output JSON, then parse | One judgment per question, typed answers, code branches directly |
| Architecture | Written wherever the thought leads | Organized per official patterns: parallel questions, gating, combined scoring |
| Verification | Asserting "it should run" | Actually testing the API, keeping the payload for every case |
The core philosophy the skill teaches the agent: give judgments to Jev, keep decisions in code. SKILL.md treats every decision as a truth table: Jev supplies the inputs ("Does the customer sound frustrated?" "Which product is this message about?"), and code holds the logic mapping inputs to actions. Conversely, questions that ask Jev to decide directly ("Should this ticket be escalated?" "What should the agent do next?") indicate the question is being asked at the wrong layer—break the decision into the judgments it depends on, and write the decision itself into code, where it is visible and testable. The code in the first three lessons is all in this shape: Jev provides intent and complexity, and if/elif decides the routing.
If you came in with other expectations, the official docs also provide a comparison table:
| What you wanted… | The right approach |
|---|---|
| Make your coding agent better atwriting code that calls TypeSafe | Install the TypeSafe agent skill (this lesson) |
| Use Jev in the app you are building for routing, classification, scoring, guardrails | Start from the first request; for patterns, see the first three lessons of this stage |
| Swap the model behind your coding agent | Jev doesn't do this. Keep using your LLM coding agent, and use Jev separately where your product needs fast, calibrated, structured decisions |
| Try Jev without writing code | Open the Playground (console.typesafe.ai/playground), paste state plus questions |
Follow along with me
Step 1: Install the TypeSafe Agent Skill
Why: when an agent has not read the TypeSafe docs, it can only write calls from training memory, and field names are easily made up. The skill loads the official integration experience into the agent's workflow in one go, and every later step builds on it.
Method A (recommended): Claude Code plugin
claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-aiYou should see: both commands finish normally with no errors. The official docs do not give exact output text, so whether the installation succeeded is determined by the verification in the next step.
Method B: other agents (Codex etc., via skills.sh)
npx skills add typesafe-ai/skills --skill typesafe-aiSelect the agent you are using as prompted. It installs to the current project by default; add -g to make it globally available.
Method C: let the agent install it itself
Paste this official prompt to the agent as-is, and it will assess the environment and execute on its own:
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.⚠️ Pick only one method
The official docs explicitly warn: mixing multiple methods produces duplicate copies. If installing manually, copy the skills/typesafe-ai entire directory (including reference files) into the agent's skills directory.
- I used only one installation method
Step 2: Call it by name to confirm the skill is loaded
Why: installed ≠ the agent will use it proactively. The official usage pattern is "name it in the prompt"—saying "use the TypeSafe skill" works in any agent; the Claude Code plugin can also invoke commands directly.
In Claude Code, enter:
/typesafe:typesafe-aiOr write in a message to another agent:
Use the TypeSafe skill when working on this project.You should see: TypeSafe context appear in the agent's response—mentioning state, questions, question types like Choice/Score/Noul, or proactively reading the live docs at docs.typesafe.ai. SKILL.md designates live docs as the source of truth for request syntax and limits, so an agent with the skill installed checks first instead of making things up.
Not loaded? The official troubleshooting has two steps: confirm that the installation command installed the skill for the very agent you are using (Method B prompts you to choose during installation) → restart the agent and try again.
- The agent's reply contains question-type / state / questions context, not free improvisation
Step 3: Use the official example prompt to have the agent find integration points in your project
Why: the best way to start is not telling the agent where to integrate Jev, but letting the skill-equipped agent find out itself. The official docs list this as "a good prompt to start with".
In your project directory, send this to the agent (official 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.You should see: the agent scans the code, points out fragile parsing, keyword lists, and heuristic rules, and proposes which ones could be replaced with "typed questions + code decisions".
The standard for judging proposal quality is that truth table from the core idea: a good proposal looks like "add a Choice / Noul here, and branch the code on the answer"; if the agent proposes "let Jev decide whether to escalate the ticket", it is pushing the decision into the model—SKILL.md explicitly says such questions are asked at the wrong layer, so have it break them into judgments and revise.
- The agent's proposals take the form of "add judgments, branch in code", not "let Jev make the decision"
Step 4: Have the agent run cheap experiments and propose refactors against the cookbook
Why: Finding the location is just planning. Step 3 of the skill workflow is "probe the live API"—validate the question wording with real requests until the application behaves as expected. The official docs provide two ready-made prompts.
First export your key (if you don't have one, create it at console.typesafe.ai/keys):
export TYPESAFE_API_KEY="<你的API Key>"Experiment prompt (official original 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.You should see: the agent asks you for permission first—the SKILL.md requires it to obtain consent first, explain what data will be sent (especially personal or private data), and declare that your key will be used, before sending any test request. The tests use representative cases + hard cases + negative cases whose answer is "no", keeping the full request payload for each case, and finally propose changes based on the most promising results.
Then have the agent look for refactoring opportunities against the official cookbook (official original text):
Using the TypeSafe skill, analyze my code and see if there are any applicable
cookbooks (https://docs.typesafe.ai/cookbooks) that show how I could
refactor my code to be less fragile or complex.What you should see: the agent points out official cookbooks similar to your code—for example, fragile email/phone extraction corresponds to pre-parsed value extraction, complex dispatch logic corresponds to intent routing—and proposes a refactoring plan following the cookbook patterns. The full hands-on implementation of these cookbooks is the next stage's scenario practice.
💡 Experiment budget and safety
SKILL.md's original words: TypeSafe is very cheap, and a little can go a very long way. Give the agent an experiment budget cap, and confirm that its runtime environment can access the API endpoint. When writing into production code, the skill's integration guidelines require the key to stay on the server side.
- The agent asked for my permission before sending requests, and explained what data would be sent
Step 5: Gather the questions and thresholds into a single file, and hand them to a human for review
Why: agents write code fast, but the official guidance warns "Agents aren't great at writing questions"—question wording, option descriptions, and thresholds are the parts of the integration that most need human oversight and are the most frequently changed during review. Centralizing them in one file gives you and the agent a concrete place for collaborative editing.
For example, gather the routing questions from the smart routing lesson into questions.py (the structure follows the official pattern page's style):
# questions.py —— 所有问题与阈值集中在这里;改措辞、调阈值只动这个文件
from typesafe_sdk import Choice, Score
ROUTING_QUESTIONS = {
"intent": Choice(...), # 完整定义见「智能路由」课第 1 步
"complexity": Score(...),
}
# 阈值也收在这里:兜底线与各动作的风险阈值分开
CONFIDENCE_FLOOR = 0.5 # 分类兜底:低于它先转人工
TRANSFER_THRESHOLD = 0.85 # 高危动作:过了它才免确认自动执行The official four collaboration principles (agent-skill.md, "Good vibe coding principles"):
- First talk the plan through with the agent—use the example prompts above as a starting point
- Before implementing, have a human go over the plan first and confirm it makes sense
- Keep constants (questions and thresholds) in one place for easy review; agents aren't good at writing questions, so expect collaborative editing
- Don't take the agent's assertions as fact—encourage it to verify its own assumptions
What you should see: the project has a single file holding all the question definitions and threshold constants. The agent won't touch it when changing business logic later; when tuning question wording, you only review the diff of this one file.
- Questions and thresholds live in one file; I review the agent's proposal before letting it proceed
Checkpoint ✅
- I can state where Jev sits in a coding agent: not the model behind it, but the decision engine in the code the agent writes
- In Claude Code,
/typesafe:typesafe-aican invoke the skill; in other agents, naming "use the TypeSafe skill" works - I have run at least one of the three official example prompts: finding integration points / running experiments / checking against the cookbook
- Questions and thresholds are gathered in one file; changing wording touches only it
- When the agent fabricates fields, I know the first reaction is to update the skill and retry
Pitfall reminders
❌ The skill is installed, but the agent still doesn't use it
Symptom: after the plugin is installed, the agent still improvises when writing Jev code. The official troubleshooting path: call /typesafe:typesafe-ai directly inside Claude Code; for other agents, mention "use the TypeSafe skill" by name in the prompt. If that still doesn't work, confirm that the target agent selected during installation wasn't chosen by mistake, then restart the agent.
❌ The agent fabricates request/response fields
Symptom: fields appear in the code that aren't in the docs—for example, reading .confidence from a Noul answer, while Noul only has noul values in 0–1. Official diagnosis: stale skill. Update it using your installation method and retry:
claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-aiThen restart Claude Code or run /reload-plugins. For peace of mind, you can enable auto-update: /plugin → Marketplaces → typesafe-ai → Enable auto-update. For skills.sh installations use npx skills update; for manual copies, replace the whole directory with the latest version from GitHub.
❌ Results don't match expectations, and the model is the first suspect
Symptom: classification or routing starts misjudging. The official troubleshooting order ischeck the questions and thresholds first: a threshold that's too high causes false negatives (things that should be automated aren't), while one that's too low causes false positives (unsure cases get through); then make the questions more specific. The pitfalls section of the smart routing lesson covers this in depth.
❌ Setting confidence thresholds everywhere
Official reminder: if you only care about picking the best option, just take the answer with the highest confidence; if you have specific statistical algorithm needs, you should use probabilities. This is already covered in depth in the smart routing lesson, so it won't be repeated here.
❌ The TypeSafe code the agent writes is too hard to review
Symptom: during review, question definitions are scattered across five files, and finding a complete set of thresholds takes forever. The officials' advice: what a human should review most is the question wording and threshold constants—keep them in one code file, so there's no need to dig around—which is exactly what Step 5 does.
Advanced tips (optional)
Read SKILL.md itself. The skill is just a 288-line Markdown file (MIT license, github.com/typesafe-ai/skills), with four core blocks: judgment and decision layering (truth tables), the "human test" for state design (looking only at this state, could a smart person answer quickly by intuition?), question wording rules (one judgment per question; option names should describe the content, because question IDs aren't sent to the model), and answer interpretation (confidence is rarely used as a gate, Noul 0.7/0.3 starting thresholds, look at the Score distribution). Most of the rules were covered in earlier lessons (Noul, Confidence); what remains worth reading in full is the "yellow flag checklist".
Use the skill's five-step troubleshooting order to deal with "the answer looks wrong". The check order given by SKILL.md: ① the payload actually sent → ② does the state pass the human test → ③ is the correct answer actually among the options → ④ can the question be split smaller → ⑤ the wording. If it's still wrong after checking everything, look into the model's known weaknesses: Jev 1.13 pitfall manual.
Recognize "yellow flags" (prompt gymnastics). The official yellow flags: criteria hardcoded for specific test items, adding a clause every time a case fails, caveats that rationalize model quirks, thresholds fitted to specific cases, tests asserting exact probabilities, code that silently overrides answers. These "wordings written to produce a specific value" tendencies break on new inputs and the next model version; prefer structural fixes—better state, splitting out a separate question, or changing the code.
Lesson Summary
✅ Install the TypeSafe Agent Skill into Claude Code with two commands (claude plugin marketplace add typesafe-ai/skills → claude plugin install typesafe@typesafe-ai); one npx skills add command for other agents; pick only one method to avoid duplicate copies.
✅ The division of labor between Jev and a coding agent: the agent writes the code, and Jev makes the judgments in the code; there is no model: "jev-latest" configuration that turns the agent into Jev-driven.
✅ Three official example prompts: explore the project to find integration points, run cheap experiments with TYPESAFE_API_KEY, and propose refactors against the cookbook.
✅ Collaboration principles: review the plan before implementing; keep questions and thresholds in a single file; agents are not good at writing questions, so expect collaborative editing; never treat assertions as facts.
✅ Troubleshooting five common issues: not loading → mention it by name / check the target / restart; fabricated fields → update the skill; unexpected results → check thresholds and questions first; only picking the best → don't set a threshold; hard to review → centralize constants.
Key commands at a glance:
| Item | Command / Approach | Source |
|---|---|---|
| Claude Code Install | claude plugin marketplace add typesafe-ai/skills → claude plugin install typesafe@typesafe-ai | docs/agent-skill.md |
| Install for other agents | npx skills add typesafe-ai/skills --skill typesafe-ai (project-level by default, -g for global) | Same as above |
| Claude Code Invoke | /typesafe:typesafe-ai (works with any agent: mention "use the TypeSafe skill" by name) | Same as above |
| Plugin update | claude plugin marketplace update typesafe-ai → claude plugin update typesafe@typesafe-ai, restart or /reload-plugins | Same as above |
| skills.sh update | npx skills update | Same as above |
| Auto-update | /plugin → Marketplaces → typesafe-ai → Enable auto-update | Same as above |
| Skill repository | github.com/typesafe-ai/skills (MIT; 2026-11-03 verified: SKILL.md 288 lines, matching the online version word for word) | Fetched and verified in real time |
Next Lesson Preview
Having practiced all four modes, the agent can now write code for you too. Next stop: bring the whole toolkit into a real project — Scenario Walkthroughs: Choose Your Path, with 15 complete cases built from the official cookbook.
You will learn:
- Pick a case by your path: each case is a complete form of "state design + typed questions + code decisions"
- LLM Guardrails: fully screening the incoming and outgoing messages of an LLM application in a single request
- Citation Check, RAG Passage Gatekeeping — how to implement production-grade tasks like these
- How the patterns from the first three lessons are combined in each case