Skip to content
Get packs

Guide · Agent skill

How to use the Outlines structured generation agent skill

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

The Outlines skill teaches an AI agent how to use the Outlines Python library, which forces a language model to produce output that follows a fixed structure such as valid JSON matching a schema, one of several choices, or text matching a pattern. Instead of hoping the model formats its answer correctly, the library restricts which tokens the model can produce at each step. This guide explains what the skill does, how to install it, how to trigger it, and what you need before running the code it produces.

Outlines Structured GenerationOrchestra-Research/AI-Research-SKILLs · MIT

Quick start

  1. 1Download the skill. Download the ZIP for the outlines skill from this page.
  2. 2Unzip it into a skills folder. Unzip into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project.
  3. 3Install the Python packages. Run pip install outlines, plus transformers, llama-cpp-python or vllm for your chosen backend.
  4. 4Prepare a model. Download a local model, or have an OpenAI API key ready if you use that backend.
  5. 5Ask for structured output. Describe the output you need in plain language, such as a Pydantic model or a list of choices.
  6. 6Run and check the code. Review the generated script, run it on realistic input, and check the returned values.

What does the Outlines skill make the agent do?

An agent skill is a folder of instructions and reference files that Claude loads when a request matches it. This skill covers the Outlines library from dottxt.ai. Its SKILL.md gives the agent working code for setting up models with Hugging Face Transformers, llama.cpp, vLLM and OpenAI, and for generating typed Python objects from a Pydantic model.

The skill's core idea is constrained generation. According to the source, Outlines converts a schema into a grammar, turns that grammar into a finite state machine, and filters invalid tokens at each generation step. The skill also notes that it can fast-forward through steps where only one token is valid.

  • Choice generation: the output is one of a list you provide
  • JSON generation: the output matches a Pydantic model or JSON schema
  • Regex generation: the output matches a pattern
  • Integer and float generation: the output is a number of that type

How do you install the Outlines skill?

Download the skill ZIP from this page. Then choose one of two routes. For Claude Code, unzip it into ~/.claude/skills/ to make it available everywhere, or into a project's .claude/skills/ folder to limit it to that project. In the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

The skill itself does not install the Python library. You install that separately with pip, as shown below. Add transformers, llama-cpp-python or vllm only for the backend you plan to use.

pip install outlines pip install outlines transformers pip install outlines llama-cpp-python pip install outlines vllm

How do you trigger the skill with a natural request?

You do not need a special command. Ask for the outcome you want in plain language and mention that the output must follow a structure. The agent should recognise requests about guaranteed JSON, Pydantic models, choices, or regex-constrained output as matching this skill.

Name the backend if you have a preference, such as a local Hugging Face model or vLLM. The skill's guidance covers local models first, and it treats OpenAI support as limited.

  • Write me a script that extracts name, age and email from a paragraph into a Pydantic model using Outlines.
  • Use Outlines to classify support tickets as positive, negative or neutral, returning only one of those choices.
  • Set up Outlines with a local llama.cpp GGUF model and generate JSON matching my schema.
  • Generate a phone number in the format 555-123-4567 using an Outlines regex generator.

What do the examples look like?

The skill includes short examples for each generator. A typical pattern loads a model, defines a Pydantic class, and calls the JSON generator on a prompt. The result is a Python object, so fields can be read directly.

The reference files go further. references/examples.md contains production-style examples for data extraction, classification, form processing, multi-entity extraction, code generation and batch processing. references/json_generation.md covers nested structures, field constraints and performance, and references/backends.md covers device setup and backend configuration.

from pydantic import BaseModel import outlines class User(BaseModel): name: str age: int email: str model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct") generator = outlines.generate.json(model, User) user = generator("Generate user: Alice, 25, alice@example.com") print(user.name)

What do you need before running the skill?

You need Python and the outlines package. Depending on the backend, you also need transformers, llama-cpp-python or vllm, plus pydantic for typed models. For local models you need a model download, and for the OpenAI backend you need an API key. A GPU is recommended for larger models.

The skill runs scripts and uses the network, because model weights are downloaded and API backends make calls. Review any code the agent writes before running it, and only run it where you are comfortable with those network and script actions.

  • Python with the outlines package
  • Optional: transformers, llama-cpp-python or vllm, depending on backend
  • pydantic for typed models
  • A local model download, or an OpenAI API key if you use that backend
  • A GPU is recommended for larger models

What tips help the output work well?

Structure guarantees the shape of the output, not its quality. Give the prompt enough context for the model to fill the fields sensibly, and check the values in your own code. The skill's examples are short, so test your pipeline on realistic inputs before relying on it.

Behaviour depends on the model and backend you choose. Use constraints such as Field(ge=0, le=120) or a Literal type to narrow values, and keep schemas as small as the task allows.

  • Use Literal or Enum fields when the answer must be one of a few options
  • Add Field constraints such as minimum and maximum values to typed fields
  • Test each backend you plan to use, because behaviour varies
  • Prefer local backends if you need the most complete feature support

What people use it for

  • Extracting name, date and amount fields from invoices or emails into a fixed schema
  • Classifying text into one of a few labels such as positive, negative or neutral
  • Generating phone numbers or IDs that must match a fixed pattern
  • Producing typed Python objects from unstructured text for a data pipeline
  • Running batch extraction over many documents with a local open-weight model

Frequently asked questions

Is the Outlines skill free to use?

The skill is published under the MIT licence, as stated in its source. The Outlines library is a separate package you install with pip, and this page does not state pricing for it or for any model or API you connect to.

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

You need Python and the outlines pip package. Add transformers, llama-cpp-python or vllm depending on the backend, and pydantic for typed models. Local models need a download, and the OpenAI backend needs an API key.

Where do I put the skill folder in Claude Code?

Unzip the downloaded ZIP into ~/.claude/skills/ to make it available in all projects, or into a project's .claude/skills/ folder to limit it to that project. In the Claude apps, you can upload it under Settings, then Capabilities, then Skills.

Does Outlines work with OpenAI models?

The skill includes a basic OpenAI backend, but the source notes that some features are limited with API models. For full feature support, the skill's guidance favours local backends such as Transformers, llama.cpp or vLLM.

What is the difference between Outlines and asking the model for JSON in the prompt?

Prompting only asks the model to format its answer correctly, which it may not do. Outlines filters the tokens the model can produce at each step, so the output follows the schema by construction. The skill describes this as guaranteed validity, though you should still check values.

Why does my Outlines output still look wrong?

The structure is guaranteed, but the content depends on the model and backend. Try a clearer prompt with the input text included, tighten field constraints, and test a different backend or model. The skill's examples are short, so validate results against your own data.

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 building a pipeline that needs reliable structured data from a language model, especially with local open-weight models. Skip it for simple chat or writing tasks, where free-form text is enough, and be cautious with OpenAI-hosted models, since the skill notes limited support.

Download the skill