[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6DMZJXAX85BM7H5VV89CF26":3,"skill-same:01M6DMZJXAX85BM7H5VV89CF26":74},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":49,"commitSha":50,"skillDirectory":51,"forksCount":14,"repositoryHtmlUrl":52,"repositoryHomepageUrl":6,"ownerHtmlUrl":53,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":54,"install":55,"resources":68},"01M6DMZJXAX85BM7H5VV89CF26","typesafe-ai",null,"TypeSafe integration craft for System One models (sometimes called Decision Models) such as Jev, which answer typed questions about text, images, and application state with calibrated probabilities. Use when building, reviewing, or debugging code that calls TypeSafe; when writing its questions or state; when replacing an LLM prompt-and-parse step, keyword matching, or a brittle heuristic with a typed question; or when brainstorming where programmable common sense fits in an app.","mpsuesser\u002Fworkspace","mpsuesser","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F190225290?v=4","01M6DMPVWVMNH3BATZ4453DY1D","Marc Suesser","01M6DMPW3HYXDNP9RZ81APC5DF",0,"MIT","https:\u002F\u002Fgithub.com\u002Fmpsuesser\u002Fworkspace\u002Fblob\u002Fmain\u002Fdotconfig\u002Fagents\u002Fskills\u002Ftypesafe-ai\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"typesafe ai","common","app","as","matching","craft","models","images","use","question","prompt","writing","decision","text","system","integration","state","code","debugging","brainstorming","2026-11-10 10:12:30",false,"---\nname: typesafe-ai\nlicense: MIT\ndescription: >\n  TypeSafe integration craft for System One models (sometimes called Decision Models) such as Jev,\n  which answer typed questions about text, images, and application state with calibrated\n  probabilities. Use when building, reviewing, or debugging code that calls TypeSafe; when writing\n  its questions or state; when replacing an LLM prompt-and-parse step, keyword matching, or a\n  brittle heuristic with a typed question; or when brainstorming where programmable common sense\n  fits in an app.\n---\n\n# Build with TypeSafe\n\nTypeSafe's **Jev**, the first public **System One model**, answers typed questions about state your\napplication supplies. State is the text, images, and application data your code sends with a\nrequest. Jev can answer a Choice among options, a Noul (the probability that a statement is true), a\nScore on levels you describe, or a Box that locates something in an image. Each answer comes back as\ntyped data with calibrated probabilities, for your code to use.\n\nThe rest of this skill is guidance: patterns that tend to produce reliable integrations. None of it\nis absolute. Models change, applications differ, and edge cases exist. When a situation calls for\nsomething else, test the alternative and use your judgment.\n\n## Judgments from Jev, decisions in code\n\nIntegrations tend to work best when Jev makes the judgments and code decides what to do with\nthem. Think of each decision as a **truth table**. Jev supplies the inputs, such as \"Does the\ncustomer sound frustrated?\" or \"Which product is the message about?\". Code holds the logic that\nmaps those inputs to an action.\n\nA question that asks Jev to make the decision, such as \"Should this ticket be escalated?\" or \"What\nshould the agent do next?\", usually means the question is at the wrong layer. Instead, break the\ndecision into the judgments it depends on, and write the decision itself in code, where it's\nvisible and testable. Writing out the table often shows gaps in the business logic too. A\ncombination of judgments with no defined outcome is a design question about the system, and it is\nbest settled in code.\n\n## Live docs\n\nThe live docs are the source of truth for request syntax, SDKs, question types, limits, and current\nmodel behavior. Read the relevant pages as part of the task.\n\n- Start at the [documentation index](https:\u002F\u002Fdocs.typesafe.ai\u002Fllms.txt). Append `.md` to a page\n  path to get the page as Markdown, and resolve relative links against `https:\u002F\u002Fdocs.typesafe.ai`.\n- Exact request and response schemas: the [OpenAPI spec](https:\u002F\u002Fapi.typesafe.ai\u002Fopenapi.json) and\n  the [HTTP API](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fapi.md) page. For an SDK, see the\n  [Python](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fpython-sdk.md) or\n  [JavaScript](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fjs-sdk.md) page and the types in the installed package.\n- Question types: [primitives](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fprimitives.md) and each type's own page,\n  [structured instructions and criteria](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fadvanced.md), and\n  [images](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fimages.md).\n- Models, context limits, and rate limits: [models](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fmodels.md). Known\n  model weak spots and their workarounds are on the\n  [jaggedness page](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fjaggedness.md).\n- Architecture: [how to build with TypeSafe](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fhow-to-build.md),\n  [patterns](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fpatterns.md), and\n  [cookbooks](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fcookbooks.md). The cookbook closest to your use case is a\n  good starting point for a new workflow.\n\nIf you can't reach the live docs, use the installed SDK's types or local docs, and tell the user\nyou did. Leave out details that depend on the version rather than guessing them.\n\n## Workflow\n\n1. **Start from the decision logic.** Begin with what the application will show, select, change,\n   or hand off. Sketch the truth table or rules that decide it, and list the inputs they need.\n   Inputs that need an understanding of language or images make good questions. Arithmetic, dates,\n   exact lookups, and policy usually belong in code. Aim for every question to feed the table, and\n   give every combination of answers an outcome, including the case where a Noul lands between your\n   thresholds. If code alone can already make the decision reliably, tell the user.\n2. **Keep all question wording in one place.** Questions, options, criteria, and thresholds are the\n   parts of an integration people audit and edit most. Keeping them together in one module makes\n   that easier. [Design the state](#design-the-state) and\n   [Write the questions](#write-the-questions) describe what tends to work.\n3. **Probe the live API**: send test requests as described in\n   [Test with the live API](#test-with-the-live-api). Use representative cases, hard cases, and\n   negative cases. Keep going until the application behaves as intended.\n4. **Integrate.** A few habits help here. Expose or log the exact request payload. When a call to\n   the API fails, surface it as an error, not as an answer; for example, don't treat a failed call\n   as a \"no\". Keep API keys on the server.\n\nIf the user's request is open-ended, offer the few directions from [Cookbooks](#cookbooks) that\nbest serve their goal, and recommend one. If the request is concrete, build it.\n\n## Design the state\n\nA useful check for any question is the **human test**: could a smart person, shown only this state\nand this question, answer quickly by intuition? When a question fails the test, the fix is usually\nin the state, not in the wording.\n\n- **Give what a person would look at.** That means who sent each message, the full thread rather\n  than a truncated last line, names rather than raw IDs or @-mention markup, and the item the\n  question is about rather than the whole catalogue. State facts your code already knows, such as\n  \"all messages in `replies` were sent after the refund was issued\", rather than leaving the model\n  to work them out again.\n- **Supply facts the model may lack**, such as what an internal product name or codename refers\n  to.\n- **Ensure every field in the state is relevant.** Irrelevant detail clutters the context and\n  reduces accuracy. A field added for one question can sway the answer to another, and the model\n  can read an empty list as a signal.\n- **Be mindful when truncating.** Truncate long strings only when you need to, and check that the\n  cut doesn't remove context the questions need.\n- **Structure with named fields.** JSON objects with descriptive keys work better than a string of\n  serialized JSON. They also let a question refer to each part by its path. Stable names such as\n  `candidates.refund_policy` are easier to refer to than array positions.\n- **Consider leaving out what no person could judge**, such as an unreadable crop or a distinction\n  experts dispute. The model's answer there tends to be noise, and code will treat that noise as\n  signal.\n\n## Write the questions\n\nBreak complex judgments or decisions into their parts, and combine the answers in code with\nweighted sums, boolean logic, thresholds, or other heuristics to reach the final decision. For\nexample, rather than asking \"Is this fraud?\" or \"Is this spam?\", ask the set of atomic questions\nabout what might make something fraud or spam. Each question tends to work best when it asks for\n**one judgment** that a person could make at a glance.\n\n- **Ask the concrete, observable thing.** Aim for something a person could point to: \"Is a SQL\n  query built by string concatenation here?\" rather than \"Are there SQL injection risks?\".\n- **One judgment per question; beware the \"or\".** Two conditions joined by \"or\" or \"and\" usually\n  work better as two questions. Likewise, a list of rules usually works better as one question per\n  rule.\n- **Anchor intent to the goal.** When the judgment is about what someone wants, it helps to name\n  their goal: \"Which of these files does the user want copied?\" rather than \"Which of these names\n  the main input?\".\n- **Name the subject directly.** \"Where is the coffee mug in `photo`?\" reads better than \"Where is\n  `target` in `photo`?\" with the target defined somewhere else. Context that only one question\n  needs, including an image, usually fits best in that question's instructions (the question text)\n  or its criteria (the descriptions of its options, its levels, or what yes and no mean). Context\n  that many questions share can go in the state once, and each question can refer to it by its\n  exact path in backticks. When you ask the same question about many items, it usually works better\n  to put each item into its own question than to give an ID the model has to look up in a shared\n  list.\n- **Each question is answered on its own.** Questions in a request can't see each other or each\n  other's answers. Any context a question relies on belongs in the state or in that question.\n- **Write plainly.** A question isn't an LLM prompt. Preambles, \"consider X, Y, and Z\" lists, and\n  output-format instructions add noise. Descriptions of the options belong in the criteria, not in\n  the question. Phrase the question so that a true answer means yes. Watch for double negatives,\n  and for presuppositions such as \"the next step\".\n- **Name the case that causes confusion.** If answers keep mixing up two outcomes, say in the\n  criteria what separates them, using the specific case. For example, for \"Is this a refund\n  request?\", note that a question about the refund policy is not a request. A vague exclusion such\n  as \"not other kinds of message\" helps less, and can draw attention to the wrong answer.\n\n### Criteria\n\n- **Ask about the null case separately.** A Box always returns a location and a Choice always picks\n  an option, even when nothing fits. Pair either one with a Noul in the same request that asks\n  whether anything fits (\"Is there a coffee mug in `photo`?\", \"Does `message` name any of our\n  products?\"), so code can tell when nothing does. As of Jev 1.14, this companion Noul usually works\n  better than a \"none of the above\" option.\n- **Option names are sent to the model; question IDs are not.** Names that describe the content\n  (`refund_request`, `shipping_delay`) help the model. Positional names (`A`, `left`, `option_1`)\n  give it nothing meaningful to go on and can bias the answer.\n- **Keep options distinct and concrete.** Wording that options share with each other, or with the\n  input, can pull probability toward those options. An option that covers several meanings is\n  often worth splitting, because its probability can't tell code which meaning applied. Direction\n  and magnitude usually work better as separate questions, so that the answer to one doesn't get\n  mixed into the other.\n- **Describe each Score level as a situation.** Each level should make sense when read on its own:\n  \"The customer mentions a minor inconvenience\" rather than \"More upset than the previous level\".\n- **Describe a Noul's `false` criterion as a concrete situation**, such as \"the package arrived on\n  time\", rather than as \"not late\".\n- **Use a Noul per statement when more than one can be true.** A Choice picks one option, so a\n  message that is both a refund request and a complaint forces it to split probability between the\n  two. Separate Nouls let each one be true on its own.\n\n## Compose requests\n\n**Bundle questions that share state.** A handy heuristic: if two calls would send the same state\nwith different questions, they can likely be one call. Questions are cheap and run in parallel, and\nthe state is read and paid for once. See\n[parallel questions](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fparallel_questions.md).\n\n**Ask speculatively**, meaning ask a question before you know whether you'll need its answer. A\nquestion that only matters in some cases can go in the same request as the question that\nidentifies the case. Ask \"Is `order` a return request?\" and \"Which item in `order.items` is being\nreturned?\" together, and have code read the second answer only when the first is yes. The second\nquestion doesn't need an \"if\" clause, because code handles the condition. See\n[speculative fan-out](https:\u002F\u002Fdocs.typesafe.ai\u002Fpatterns\u002Ffan-out.md).\n\nA second request is usually worth it when:\n\n- code needs an answer to build the next state, fetch evidence, or choose the next options;\n- a state field needed for one question measurably misleads another;\n- different sets of questions need to be cached or versioned separately.\n\n## Read the answers\n\n### Confidence is rarely the gate\n\nNaive implementations often use an answer's `confidence` as the check that decides whether code\nacts. Confidence measures how concentrated an answer's probability distribution is, which is not\nthe same as how likely the answer is to be correct. Think about what the probabilities should look\nlike in your use case; another calculation over them may suit it better.\n\n### Probabilities and thresholds\n\n- **A probability is the likelihood that an answer is correct.** Jev isn't a calculator for\n  probability problems. Ask it for judgments, and do any math on odds or probabilities in code. A\n  Noul near 0.5 usually means the state doesn't settle the question.\n- **The top answer is a good default**: the Choice's top option, or the Score's position.\n- **0.7 and 0.3 make good starting thresholds for a Noul**: above 0.7 reads as yes, below 0.3 as no,\n  and the band between means the question isn't settled, which can get its own row in the truth\n  table. Adjust them when the application calls for it, and be wary of over-fitting them to a\n  handful of test cases.\n- **Look at Score distributions.** The Score's position can get pulled toward the middle and hide\n  two-peaked answers, so look at the level probabilities before deciding which value your code\n  reads.\n\n## Test with the live API\n\nSending test requests to the live API is a great way to test questions against your data. Ask the\nuser for permission first. Get a budget for experimentation (TypeSafe is very inexpensive, so a\nlittle can go a very long way), disclose what data will be sent (point out any personal or private\ndata), and say that their `TYPESAFE_API_KEY` will be used.\n\n- Start with a few representative cases, plus hard ones and some whose answer is \"no\" or \"nothing\n  fits\".\n- Compare wordings by sending each variant as a separate question in one request, over the same\n  state.\n- Read individual answers, not only aggregates.\n- Keep the exact request payload for each case so any result can be rerun.\n- Check each change against cases you didn't use while tuning.\n\nMake sure any agent that sends test requests has network access to the API endpoint.\n\n### When an answer looks wrong\n\nCheck these, in this order:\n\n1. the payload as actually sent;\n2. the state, against the human test;\n3. the options and candidates: is the right answer among them?\n4. the scope of the questions: can each one be broken down into smaller judgments?\n5. the wording.\n\nIf a clear question with complete state still gets an answer you're confident is wrong, check the\njaggedness page for the model you're using. It lists known weak spots and how to work around them.\nIf the behavior isn't listed, the TypeSafe team welcomes examples through the channel linked on\nthat page. In the meantime, work out an alternative approach with the user that avoids the weak\nspot.\n\n### Yellow flags\n\nTypically, a good change is one that makes the definition clearer or improves the state. Check each\nchange on cases you didn't tune on. Wording written to produce a particular value is **prompt\ngymnastics**, and it tends to break on new inputs and on the next model version. Some yellow flags:\n\n- criteria that name specific test items, or that gain a clause for each failing case;\n- caveats that explain away a model quirk;\n- thresholds fitted to particular cases;\n- tests that assert an exact probability;\n- code that quietly overrides answers.\n\nThe structural fix is usually better state, a separate question, or code.\n\n## Cookbooks\n\nEach of these starting points combines questions to serve one goal. Ideas outside this list are\nwelcome.\n\n- **Route and fill arguments.** One request identifies what the user is asking for and which\n  values go in each argument. Code then calls the handler. See\n  [function calling](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Ffunction_calling.md) and\n  [intent routing](https:\u002F\u002Fdocs.typesafe.ai\u002Fpatterns\u002Fintent-routing.md).\n- **Select instead of generate.** Code finds candidate values or spans of text, the model picks\n  the intended one, and code copies or normalizes it. See\n  [value extraction](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fpre_parsed_value_extraction_cookbook.md),\n  [date extraction](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fdate_extraction_cookbook.md), and\n  [structure recovery](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fautoformat.md).\n- **Find and judge evidence.** Retrieve candidates and ask how relevant each one is. See\n  [line-by-line search](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fsemantic_find.md),\n  [re-ranking](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Frerank_typesafe.md), and\n  [classifying RAG passages](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fclassifying_rag_passages.md).\n- **Turn answers into data.** Score each dimension once, then let code or users change the weights\n  and views. If you have labeled outcomes, the answers can become features for a model. See\n  [composite scoring](https:\u002F\u002Fdocs.typesafe.ai\u002Fpatterns\u002Fcomposite-scoring.md) and\n  [feature discovery](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fautoresearch_feature_discovery.md).\n- **Verify and escalate.** Check claims or fields against their evidence, and send the cases that\n  fail to a person or a reasoning model. See\n  [citation checks](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fcitation_check.md) and\n  [extraction cascades](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fsde_cascade.md).\n\nThe TypeSafe team is constantly adding cookbooks of well-tested patterns to the live documentation.\nIt's a good idea to check the [cookbooks index](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fcookbooks.md) for one\nthat fits the problem you're solving.\n","# Build with TypeSafe\n\nTypeSafe's **Jev**, the first public **System One model**, answers typed questions about state your\napplication supplies. State is the text, images, and application data your code sends with a\nrequest. Jev can answer a Choice among options, a Noul (the probability that a statement is true), a\nScore on levels you describe, or a Box that locates something in an image. Each answer comes back as\ntyped data with calibrated probabilities, for your code to use.\n\nThe rest of this skill is guidance: patterns that tend to produce reliable integrations. None of it\nis absolute. Models change, applications differ, and edge cases exist. When a situation calls for\nsomething else, test the alternative and use your judgment.\n\n## Judgments from Jev, decisions in code\n\nIntegrations tend to work best when Jev makes the judgments and code decides what to do with\nthem. Think of each decision as a **truth table**. Jev supplies the inputs, such as \"Does the\ncustomer sound frustrated?\" or \"Which product is the message about?\". Code holds the logic that\nmaps those inputs to an action.\n\nA question that asks Jev to make the decision, such as \"Should this ticket be escalated?\" or \"What\nshould the agent do next?\", usually means the question is at the wrong layer. Instead, break the\ndecision into the judgments it depends on, and write the decision itself in code, where it's\nvisible and testable. Writing out the table often shows gaps in the business logic too. A\ncombination of judgments with no defined outcome is a design question about the system, and it is\nbest settled in code.\n\n## Live docs\n\nThe live docs are the source of truth for request syntax, SDKs, question types, limits, and current\nmodel behavior. Read the relevant pages as part of the task.\n\n- Start at the [documentation index](https:\u002F\u002Fdocs.typesafe.ai\u002Fllms.txt). Append `.md` to a page\n  path to get the page as Markdown, and resolve relative links against `https:\u002F\u002Fdocs.typesafe.ai`.\n- Exact request and response schemas: the [OpenAPI spec](https:\u002F\u002Fapi.typesafe.ai\u002Fopenapi.json) and\n  the [HTTP API](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fapi.md) page. For an SDK, see the\n  [Python](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fpython-sdk.md) or\n  [JavaScript](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fjs-sdk.md) page and the types in the installed package.\n- Question types: [primitives](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fprimitives.md) and each type's own page,\n  [structured instructions and criteria](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fadvanced.md), and\n  [images](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fimages.md).\n- Models, context limits, and rate limits: [models](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fmodels.md). Known\n  model weak spots and their workarounds are on the\n  [jaggedness page](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fjaggedness.md).\n- Architecture: [how to build with TypeSafe](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fhow-to-build.md),\n  [patterns](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fpatterns.md), and\n  [cookbooks](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fcookbooks.md). The cookbook closest to your use case is a\n  good starting point for a new workflow.\n\nIf you can't reach the live docs, use the installed SDK's types or local docs, and tell the user\nyou did. Leave out details that depend on the version rather than guessing them.\n\n## Workflow\n\n1. **Start from the decision logic.** Begin with what the application will show, select, change,\n   or hand off. Sketch the truth table or rules that decide it, and list the inputs they need.\n   Inputs that need an understanding of language or images make good questions. Arithmetic, dates,\n   exact lookups, and policy usually belong in code. Aim for every question to feed the table, and\n   give every combination of answers an outcome, including the case where a Noul lands between your\n   thresholds. If code alone can already make the decision reliably, tell the user.\n2. **Keep all question wording in one place.** Questions, options, criteria, and thresholds are the\n   parts of an integration people audit and edit most. Keeping them together in one module makes\n   that easier. [Design the state](#design-the-state) and\n   [Write the questions](#write-the-questions) describe what tends to work.\n3. **Probe the live API**: send test requests as described in\n   [Test with the live API](#test-with-the-live-api). Use representative cases, hard cases, and\n   negative cases. Keep going until the application behaves as intended.\n4. **Integrate.** A few habits help here. Expose or log the exact request payload. When a call to\n   the API fails, surface it as an error, not as an answer; for example, don't treat a failed call\n   as a \"no\". Keep API keys on the server.\n\nIf the user's request is open-ended, offer the few directions from [Cookbooks](#cookbooks) that\nbest serve their goal, and recommend one. If the request is concrete, build it.\n\n## Design the state\n\nA useful check for any question is the **human test**: could a smart person, shown only this state\nand this question, answer quickly by intuition? When a question fails the test, the fix is usually\nin the state, not in the wording.\n\n- **Give what a person would look at.** That means who sent each message, the full thread rather\n  than a truncated last line, names rather than raw IDs or @-mention markup, and the item the\n  question is about rather than the whole catalogue. State facts your code already knows, such as\n  \"all messages in `replies` were sent after the refund was issued\", rather than leaving the model\n  to work them out again.\n- **Supply facts the model may lack**, such as what an internal product name or codename refers\n  to.\n- **Ensure every field in the state is relevant.** Irrelevant detail clutters the context and\n  reduces accuracy. A field added for one question can sway the answer to another, and the model\n  can read an empty list as a signal.\n- **Be mindful when truncating.** Truncate long strings only when you need to, and check that the\n  cut doesn't remove context the questions need.\n- **Structure with named fields.** JSON objects with descriptive keys work better than a string of\n  serialized JSON. They also let a question refer to each part by its path. Stable names such as\n  `candidates.refund_policy` are easier to refer to than array positions.\n- **Consider leaving out what no person could judge**, such as an unreadable crop or a distinction\n  experts dispute. The model's answer there tends to be noise, and code will treat that noise as\n  signal.\n\n## Write the questions\n\nBreak complex judgments or decisions into their parts, and combine the answers in code with\nweighted sums, boolean logic, thresholds, or other heuristics to reach the final decision. For\nexample, rather than asking \"Is this fraud?\" or \"Is this spam?\", ask the set of atomic questions\nabout what might make something fraud or spam. Each question tends to work best when it asks for\n**one judgment** that a person could make at a glance.\n\n- **Ask the concrete, observable thing.** Aim for something a person could point to: \"Is a SQL\n  query built by string concatenation here?\" rather than \"Are there SQL injection risks?\".\n- **One judgment per question; beware the \"or\".** Two conditions joined by \"or\" or \"and\" usually\n  work better as two questions. Likewise, a list of rules usually works better as one question per\n  rule.\n- **Anchor intent to the goal.** When the judgment is about what someone wants, it helps to name\n  their goal: \"Which of these files does the user want copied?\" rather than \"Which of these names\n  the main input?\".\n- **Name the subject directly.** \"Where is the coffee mug in `photo`?\" reads better than \"Where is\n  `target` in `photo`?\" with the target defined somewhere else. Context that only one question\n  needs, including an image, usually fits best in that question's instructions (the question text)\n  or its criteria (the descriptions of its options, its levels, or what yes and no mean). Context\n  that many questions share can go in the state once, and each question can refer to it by its\n  exact path in backticks. When you ask the same question about many items, it usually works better\n  to put each item into its own question than to give an ID the model has to look up in a shared\n  list.\n- **Each question is answered on its own.** Questions in a request can't see each other or each\n  other's answers. Any context a question relies on belongs in the state or in that question.\n- **Write plainly.** A question isn't an LLM prompt. Preambles, \"consider X, Y, and Z\" lists, and\n  output-format instructions add noise. Descriptions of the options belong in the criteria, not in\n  the question. Phrase the question so that a true answer means yes. Watch for double negatives,\n  and for presuppositions such as \"the next step\".\n- **Name the case that causes confusion.** If answers keep mixing up two outcomes, say in the\n  criteria what separates them, using the specific case. For example, for \"Is this a refund\n  request?\", note that a question about the refund policy is not a request. A vague exclusion such\n  as \"not other kinds of message\" helps less, and can draw attention to the wrong answer.\n\n### Criteria\n\n- **Ask about the null case separately.** A Box always returns a location and a Choice always picks\n  an option, even when nothing fits. Pair either one with a Noul in the same request that asks\n  whether anything fits (\"Is there a coffee mug in `photo`?\", \"Does `message` name any of our\n  products?\"), so code can tell when nothing does. As of Jev 1.14, this companion Noul usually works\n  better than a \"none of the above\" option.\n- **Option names are sent to the model; question IDs are not.** Names that describe the content\n  (`refund_request`, `shipping_delay`) help the model. Positional names (`A`, `left`, `option_1`)\n  give it nothing meaningful to go on and can bias the answer.\n- **Keep options distinct and concrete.** Wording that options share with each other, or with the\n  input, can pull probability toward those options. An option that covers several meanings is\n  often worth splitting, because its probability can't tell code which meaning applied. Direction\n  and magnitude usually work better as separate questions, so that the answer to one doesn't get\n  mixed into the other.\n- **Describe each Score level as a situation.** Each level should make sense when read on its own:\n  \"The customer mentions a minor inconvenience\" rather than \"More upset than the previous level\".\n- **Describe a Noul's `false` criterion as a concrete situation**, such as \"the package arrived on\n  time\", rather than as \"not late\".\n- **Use a Noul per statement when more than one can be true.** A Choice picks one option, so a\n  message that is both a refund request and a complaint forces it to split probability between the\n  two. Separate Nouls let each one be true on its own.\n\n## Compose requests\n\n**Bundle questions that share state.** A handy heuristic: if two calls would send the same state\nwith different questions, they can likely be one call. Questions are cheap and run in parallel, and\nthe state is read and paid for once. See\n[parallel questions](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fparallel_questions.md).\n\n**Ask speculatively**, meaning ask a question before you know whether you'll need its answer. A\nquestion that only matters in some cases can go in the same request as the question that\nidentifies the case. Ask \"Is `order` a return request?\" and \"Which item in `order.items` is being\nreturned?\" together, and have code read the second answer only when the first is yes. The second\nquestion doesn't need an \"if\" clause, because code handles the condition. See\n[speculative fan-out](https:\u002F\u002Fdocs.typesafe.ai\u002Fpatterns\u002Ffan-out.md).\n\nA second request is usually worth it when:\n\n- code needs an answer to build the next state, fetch evidence, or choose the next options;\n- a state field needed for one question measurably misleads another;\n- different sets of questions need to be cached or versioned separately.\n\n## Read the answers\n\n### Confidence is rarely the gate\n\nNaive implementations often use an answer's `confidence` as the check that decides whether code\nacts. Confidence measures how concentrated an answer's probability distribution is, which is not\nthe same as how likely the answer is to be correct. Think about what the probabilities should look\nlike in your use case; another calculation over them may suit it better.\n\n### Probabilities and thresholds\n\n- **A probability is the likelihood that an answer is correct.** Jev isn't a calculator for\n  probability problems. Ask it for judgments, and do any math on odds or probabilities in code. A\n  Noul near 0.5 usually means the state doesn't settle the question.\n- **The top answer is a good default**: the Choice's top option, or the Score's position.\n- **0.7 and 0.3 make good starting thresholds for a Noul**: above 0.7 reads as yes, below 0.3 as no,\n  and the band between means the question isn't settled, which can get its own row in the truth\n  table. Adjust them when the application calls for it, and be wary of over-fitting them to a\n  handful of test cases.\n- **Look at Score distributions.** The Score's position can get pulled toward the middle and hide\n  two-peaked answers, so look at the level probabilities before deciding which value your code\n  reads.\n\n## Test with the live API\n\nSending test requests to the live API is a great way to test questions against your data. Ask the\nuser for permission first. Get a budget for experimentation (TypeSafe is very inexpensive, so a\nlittle can go a very long way), disclose what data will be sent (point out any personal or private\ndata), and say that their `TYPESAFE_API_KEY` will be used.\n\n- Start with a few representative cases, plus hard ones and some whose answer is \"no\" or \"nothing\n  fits\".\n- Compare wordings by sending each variant as a separate question in one request, over the same\n  state.\n- Read individual answers, not only aggregates.\n- Keep the exact request payload for each case so any result can be rerun.\n- Check each change against cases you didn't use while tuning.\n\nMake sure any agent that sends test requests has network access to the API endpoint.\n\n### When an answer looks wrong\n\nCheck these, in this order:\n\n1. the payload as actually sent;\n2. the state, against the human test;\n3. the options and candidates: is the right answer among them?\n4. the scope of the questions: can each one be broken down into smaller judgments?\n5. the wording.\n\nIf a clear question with complete state still gets an answer you're confident is wrong, check the\njaggedness page for the model you're using. It lists known weak spots and how to work around them.\nIf the behavior isn't listed, the TypeSafe team welcomes examples through the channel linked on\nthat page. In the meantime, work out an alternative approach with the user that avoids the weak\nspot.\n\n### Yellow flags\n\nTypically, a good change is one that makes the definition clearer or improves the state. Check each\nchange on cases you didn't tune on. Wording written to produce a particular value is **prompt\ngymnastics**, and it tends to break on new inputs and on the next model version. Some yellow flags:\n\n- criteria that name specific test items, or that gain a clause for each failing case;\n- caveats that explain away a model quirk;\n- thresholds fitted to particular cases;\n- tests that assert an exact probability;\n- code that quietly overrides answers.\n\nThe structural fix is usually better state, a separate question, or code.\n\n## Cookbooks\n\nEach of these starting points combines questions to serve one goal. Ideas outside this list are\nwelcome.\n\n- **Route and fill arguments.** One request identifies what the user is asking for and which\n  values go in each argument. Code then calls the handler. See\n  [function calling](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Ffunction_calling.md) and\n  [intent routing](https:\u002F\u002Fdocs.typesafe.ai\u002Fpatterns\u002Fintent-routing.md).\n- **Select instead of generate.** Code finds candidate values or spans of text, the model picks\n  the intended one, and code copies or normalizes it. See\n  [value extraction](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fpre_parsed_value_extraction_cookbook.md),\n  [date extraction](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fdate_extraction_cookbook.md), and\n  [structure recovery](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fautoformat.md).\n- **Find and judge evidence.** Retrieve candidates and ask how relevant each one is. See\n  [line-by-line search](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fsemantic_find.md),\n  [re-ranking](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Frerank_typesafe.md), and\n  [classifying RAG passages](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fclassifying_rag_passages.md).\n- **Turn answers into data.** Score each dimension once, then let code or users change the weights\n  and views. If you have labeled outcomes, the answers can become features for a model. See\n  [composite scoring](https:\u002F\u002Fdocs.typesafe.ai\u002Fpatterns\u002Fcomposite-scoring.md) and\n  [feature discovery](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fautoresearch_feature_discovery.md).\n- **Verify and escalate.** Check claims or fields against their evidence, and send the cases that\n  fail to a person or a reasoning model. See\n  [citation checks](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fcitation_check.md) and\n  [extraction cascades](https:\u002F\u002Fdocs.typesafe.ai\u002Fcookbooks\u002Fsde_cascade.md).\n\nThe TypeSafe team is constantly adding cookbooks of well-tested patterns to the live documentation.\nIt's a good idea to check the [cookbooks index](https:\u002F\u002Fdocs.typesafe.ai\u002Fgo\u002Fcookbooks.md) for one\nthat fits the problem you're solving.\n",{"name":5,"license":15,"description":7},"main","7892e7a2b466a7a3f71bd4d094b8c3d5eaadafe6","dotconfig\u002Fagents\u002Fskills\u002Ftypesafe-ai","https:\u002F\u002Fgithub.com\u002Fmpsuesser\u002Fworkspace","https:\u002F\u002Fgithub.com\u002Fmpsuesser","2026-10-28 10:59:26",{"source":8,"skillName":5,"commands":56,"prompt":66,"zipAvailable":67},[57,60,63],{"tool":58,"command":59},"npx","npx skills add mpsuesser\u002Fworkspace --skill typesafe-ai",{"tool":61,"command":62},"bunx","bunx skills add mpsuesser\u002Fworkspace --skill typesafe-ai",{"tool":64,"command":65},"pnpm","pnpm dlx skills add mpsuesser\u002Fworkspace --skill typesafe-ai","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmpsuesser\u002Fworkspace\u002Fblob\u002Fmain\u002Fdotconfig\u002Fagents\u002Fskills\u002Ftypesafe-ai\u002FSKILL.md",true,[69],{"path":70,"resourceType":70,"resourceTypeDesc":71,"sizeBytes":72,"sourceHtmlUrl":73},"LICENSE","许可证",1068,"https:\u002F\u002Fgithub.com\u002Fmpsuesser\u002Fworkspace\u002Fblob\u002Fmain\u002Fdotconfig\u002Fagents\u002Fskills\u002Ftypesafe-ai\u002FLICENSE",[75,98,122,146,169,198],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":44},"01M6DNA9XXSD8G5NKB6RBPVZDG","mintlify","Build and maintain documentation sites with Mintlify. Use when creating docs pages, configuring navigation, adding components, or setting up API references.","https:\u002F\u002Fgithub.com\u002Fmpsuesser\u002Fworkspace\u002Fblob\u002Fmain\u002Fdotconfig\u002Fpi\u002Fagent\u002Fskills\u002F__techs__\u002F.unused\u002Fmintlify\u002FSKILL.md",[],[77,82,83,84,85,86,87,88,89,90,32,91,92,93,94,95,96,97],"cli","docs","workflow","components","documentation","git","api","js","node","up","navigation","references","build","maintain","pages","sites",{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":110,"publishedAt":44},"01M6DNA29MQJJZCVPM31FJAD3B","mintlify-api","Interact with the Mintlify REST API to manage deployments, trigger builds, and query documentation site metadata programmatically.","https:\u002F\u002Fgithub.com\u002Fmpsuesser\u002Fworkspace\u002Fblob\u002Fmain\u002Fdotconfig\u002Fpi\u002Fagent\u002Fskills\u002F__techs__\u002F.unused\u002Fmintlify-api\u002FSKILL.md",[104,109],{"categoryNo":105,"categoryName":106,"taxonomyType":107,"taxonomyTypeDesc":108},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[88,77,111,86,112,113,114,115,116,117,118,119,120,121],"mintlify api","http","authentication","metadata","REST","site","deployments","manage","query","rest api","trigger",{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":134,"publishedAt":44},"01M6DN85XZR9FEF7YNAMDFPZEP","humanize-ai-writing","Remove signs of AI-generated writing — inflated symbolism, promotional language, em-dash overuse, rule of three, AI vocabulary, passive voice, negative parallelisms, filler. Use when editing or reviewing text to sound more natural and human-written.","https:\u002F\u002Fgithub.com\u002Fmpsuesser\u002Fworkspace\u002Fblob\u002Fmain\u002Fdotconfig\u002Fpi\u002Fagent\u002Fskills\u002F.deprecated\u002Fhumanize-ai-writing\u002FSKILL.md",[128,131],{"categoryNo":129,"categoryName":130,"taxonomyType":107,"taxonomyTypeDesc":108},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":132,"categoryName":133,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000036","内容创作者",[35,135,136,137,138,37,139,140,141,32,142,143,144,145],"humanize","humanize ai","humanize ai writing","voice","editing","generated","remove","language","vocabulary","three","human",{"skillNo":147,"name":148,"nameZh":6,"description":149,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":150,"categories":151,"keywords":152,"publishedAt":44},"01M6DN14JMJVPCSNJHEJS6ATXS","web-typography","Select, pair, and implement typefaces for web projects. Use when the user mentions \"font pairing\", \"which typeface\", \"line height\", \"responsive typography\", \"web font loading\", \"type hierarchy\", \"variable fonts\", \"FOUT\u002FFOIT\", \"typographic scale\", or \"the text is hard to read\". Also trigger when choosing between system fonts and web fonts, optimizing font-loading performance, or designing readable long-form content. Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.","https:\u002F\u002Fgithub.com\u002Fmpsuesser\u002Fworkspace\u002Fblob\u002Fmain\u002Fdotconfig\u002Fagents\u002Fskills\u002Fweb-typography\u002FSKILL.md",[],[153,154,155,156,157,158,159,160,161,162,163,164,38,37,165,32,166,167,121,168],"web","typography","web typography","design","css","performance","implement","design systems","Optimization","refactoring","performance optimization","projects","select","ui design","type","long",{"skillNo":170,"name":171,"nameZh":6,"description":172,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":173,"categories":174,"keywords":181,"publishedAt":44},"01M6DN0VGGT88N3BY21B11HB7P","ux-heuristics","Evaluate and improve interface usability using heuristic analysis. Use when the user mentions \"usability audit\", \"users are confused\", \"form usability\", \"navigation problems\", \"Nielsen heuristics\", \"cognitive walkthrough\", or \"is this easy to use\". Also trigger when reviewing a design for usability issues, improving form-completion rates, or evaluating information architecture and navigation. Covers Krug's laws, Nielsen's 10 heuristics, severity ratings, dark-pattern recognition, and accessibility. For visual design fixes, see refactoring-ui. For conversion-focused audits, see cro-methodology.","https:\u002F\u002Fgithub.com\u002Fmpsuesser\u002Fworkspace\u002Fblob\u002Fmain\u002Fdotconfig\u002Fagents\u002Fskills\u002Fux-heuristics\u002FSKILL.md",[175,178],{"categoryNo":176,"categoryName":177,"taxonomyType":107,"taxonomyTypeDesc":108},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":179,"categoryName":180,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000032","设计师",[182,183,184,156,185,186,187,188,189,190,191,192,162,193,32,194,195,196,197,121],"ux","heuristics","ux heuristics","architecture","issues","audit","ui","severity","analysis","walkthrough","improve","cro","usability","conversion","visual design","pattern",{"skillNo":199,"name":200,"nameZh":6,"description":201,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":202,"categories":203,"keywords":204,"publishedAt":44},"01M6DMZA31N28SPS7DCCW12PRX","storybrand-messaging","Clarify brand messaging using narrative structure that positions the customer as hero. Use when the user mentions \"brand message\", \"website copy\", \"elevator pitch\", \"one-liner\", \"brand script\", \"StoryBrand framework\", \"customer as hero\", or \"my messaging isnt resonating\". Also trigger when rewriting homepage copy, crafting email nurture sequences, or creating consistent messaging across sales and marketing collateral. Covers landing page copy, marketing collateral, and consistent communication. For memorable messaging, see made-to-stick. For product positioning, see obviously-awesome.","https:\u002F\u002Fgithub.com\u002Fmpsuesser\u002Fworkspace\u002Fblob\u002Fmain\u002Fdotconfig\u002Fagents\u002Fskills\u002Fstorybrand-messaging\u002FSKILL.md",[],[205,206,207,208,209,210,211,212,213,214,215,216,32,217,218,219,220,221,27,121],"messaging","storybrand messaging","customer","communication","product","website","email","page","brand","clarify","landing","sales","message","structure","positioning","landing page copy","across"]