Skip to content
Get packs

Guide · Agent skill

How to use the Guidance constrained generation agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The Guidance skill teaches an AI agent to use the Guidance Python library, a Microsoft Research framework that limits what a language model can write so the output follows a set pattern, such as valid JSON, a date, an email address, or one label from a fixed list. It is aimed at Python developers and teams whose downstream code needs predictable model output. After this guide you will know what the skill does, how to add it to Claude, how to phrase requests that trigger it, and what you need installed before the examples will run.

Guidance Constrained GenerationOrchestra-Research/AI-Research-SKILLs · MIT

Quick start

  1. 1Download the skill ZIP. Get the Guidance ZIP from this page. It contains SKILL.md and three reference files.
  2. 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project.
  3. 3Install the guidance package. Run pip install guidance, adding the transformers or llama_cpp extra if you plan to use local models.
  4. 4Set your API key. Export ANTHROPIC_API_KEY or OPENAI_API_KEY so the hosted model classes can read it.
  5. 5Ask for a constrained output. Describe the format you need, such as a date, JSON object or one label from a list, and mention that a program will read it.
  6. 6Review and test the code. Check the generated code, fix any incomplete lines, and run it on sample inputs.

What does the Guidance skill make the agent do?

Normally you ask a language model for JSON or a date and hope the reply is well formed. The Guidance skill changes the approach: the agent writes code that restricts generation so the output must match a pattern. The source describes this as constrained generation, using regex or grammars to control the syntax of the output.

The skill also covers building multi-step workflows by chaining several generation steps together with ordinary Python control flow such as loops and conditionals.

  • Regex constraints for fields like emails, dates (YYYY-MM-DD) and phone numbers
  • Selection constraints that force one answer from a list, such as positive, negative or neutral
  • Grammar-based generation for nested structures such as JSON objects
  • Reusable functions built with the @guidance decorator

How do you install the Guidance agent skill?

You can add the skill in one of two ways. For Claude Code, download the ZIP from this page and unzip it into your personal skills folder ~/.claude/skills/ or into a project's .claude/skills/ folder. Alternatively, in the Claude apps, go to Settings, then Capabilities, then Skills, and upload the ZIP there.

The skill itself is instructions for the agent. To run the code examples you also need the guidance Python package, which the skill's own installation section gives as pip install guidance.

  • Personal: ~/.claude/skills/
  • Project: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP
pip install guidance

How do you set up the Python environment and API keys?

The source lists Python, the guidance package, and an API key for hosted models (Anthropic or OpenAI) as requirements. Local models are optional. For Hugging Face models you install the Transformers extra; for llama.cpp models, the llama_cpp extra.

The Anthropic and OpenAI model classes read the key from an environment variable (ANTHROPIC_API_KEY or OPENAI_API_KEY) if you do not pass one in the code. Keep keys out of shared files.

  • Required: Python and the guidance package
  • Optional for local models: transformers or llama_cpp
  • Required for hosted models: an Anthropic or OpenAI API key
pip install guidance[transformers] # Hugging Face models pip install guidance[llama_cpp] # llama.cpp models

How do you trigger the skill with a natural request?

You do not need special syntax. Describe the output shape you need and mention the goal, such as parsing a field or classifying text. The agent should then reach for constrained generation. Naming the format (JSON, a date, one of a fixed set of labels) makes the trigger clearer.

Be specific about the downstream use. Saying the output will be read by a script tells the agent to prioritise strict format over prose.

  • "Use guidance to extract the invoice date from this text as YYYY-MM-DD."
  • "Write a guidance script that classifies support tickets as billing, bug or other."
  • "Generate a user profile as valid JSON with name, age and email using guidance."

What does a basic example look like?

The simplest pattern is to add a prompt and a constrained gen call. In the Anthropic example from the skill, a date is forced to match a regex, and a sentiment is limited to three choices with select.

The skill notes that token healing is on by default, which fixes awkward spacing at the boundary between your prompt and the generated text.

  • gen(name, regex=...) restricts the field to a pattern
  • select([...], name=...) limits the answer to listed options
  • gen(..., max_tokens=...) caps the length
from guidance import models, gen, select lm = models.Anthropic("claude-sonnet-4-5-20250929") lm += "Date: " + gen("date", regex=r"\d{4}-\d{2}-\d{2}") lm += "Sentiment: " + select(["positive", "negative", "neutral"], name="sentiment") print(lm["date"]) print(lm["sentiment"])

How do you use the skill for JSON and classification?

For JSON, the reference examples build the object piece by piece, with each value generated under a regex that matches its type. For classification, a select call restricts the reply to your label set. The skill's reference files also cover data extraction, multi-step workflows and code generation.

Use the backend reference to choose between hosted models (Anthropic, OpenAI) and local ones (Transformers, llama.cpp). Model names in the examples are fixed strings and may change, so check them against the provider's current list.

  • Pattern 1 in SKILL.md: JSON generation with a system and user message
  • Pattern 2 in SKILL.md: classification (see the file for the full example)
  • references/examples.md: data extraction, agent systems and multi-step workflows

What about scripts, network access and safety?

The skill does not run scripts. It does use the network, because the hosted model examples send requests to Anthropic or OpenAI. Your API key and any prompt content you send will go to that provider, so avoid placing sensitive data in prompts unless the provider's terms suit you.

Do not run the examples in production as written. The SKILL.md Anthropic example appears to end with an incomplete bare import line, so check the code before use. Model names and API details may also change over time.

  • Runs scripts: no
  • Uses network: yes, to call hosted model APIs
  • Check the Anthropic example's final line before reusing it
  • Test outputs against your own validation before relying on them

What tips help the skill work well?

Keep each constraint tight. A narrow regex or a short label list gives the model less room to go wrong. For longer structures, use the grammar approach and set max_tokens on each field so a field cannot run on forever.

Use the stop argument when a field should end at a line break, as the reference examples do with stop="\n". Use stateful functions only when you need a loop, such as the ReAct-style agent example in the source.

  • Use select for fixed categories rather than free text
  • Set max_tokens on every gen call inside a grammar
  • Test on a few inputs before scaling up

What people use it for

  • Extracting dates, IDs or email addresses from free text into fields a script can use
  • Classifying support tickets, reviews or documents into a fixed set of labels
  • Generating JSON records that a downstream program parses without errors
  • Building multi-step workflows where one generation feeds the next using Python loops

Frequently asked questions

Is the Guidance agent skill free?

The skill is published under the MIT licence, according to this page. The guidance Python package and model providers have their own terms, and hosted models such as Anthropic and OpenAI are billed by their providers, so check those before you run the examples.

What do I need to install before using the Guidance skill?

You need Python and the guidance package (pip install guidance). For hosted models you also need an Anthropic or OpenAI API key. Local models additionally need the transformers or llama_cpp packages.

Does the Guidance skill run scripts on my machine?

No. The skill is listed as not running scripts. It does use the network, because the hosted model examples call Anthropic or OpenAI APIs.

How do I install the skill in Claude?

Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings, Capabilities, Skills.

Why does the Anthropic example not run as written?

The SKILL.md Anthropic example appears to have an incomplete final line, a bare import. Check and fix that line before use. Model names and API details may also change over time.

How does Guidance compare with simply asking for JSON in the prompt?

Prompting only asks the model to produce the format, while Guidance restricts generation so the output must match a regex or grammar. The source does not include benchmarks, so test both on your own data. For free-form chat or writing, the extra code is not needed.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are a Python developer or team that needs model output parsed reliably, such as dates, IDs, categories or JSON for downstream code. Skip it for simple chat or writing tasks, or if you cannot install the guidance package and an API key, and review the examples carefully before using them in production.

Download the skill