Skip to content
Get packs

Guide · Agent skill

How to use the Instructor structured output agent skill

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

The Instructor agent skill teaches your AI agent to write Python code that makes an LLM return data in a fixed structure. That structure is a Pydantic model, so the answer is type-checked and can be retried with error feedback when it fails. This guide covers what the skill does, how to install it, how to trigger it, what it needs, and where to be careful, so you can get working extraction code from a single request.

Instructor Structured OutputOrchestra-Research/AI-Research-SKILLs · MIT

Quick start

  1. 1Download the ZIP. Get the skill ZIP from this page on our directory.
  2. 2Unzip into a skills folder. Place it in ~/.claude/skills/ for personal use or in your project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  3. 3Install the Python packages. Run pip install instructor and the provider extra you need, such as instructor[anthropic] or instructor[openai].
  4. 4Set up your API key. Create an account with your LLM provider and make the key available to your code, as the provider sections in the skill describe.
  5. 5Ask for structured output. Describe the fields, types and rules you want, and ask the agent to write code using Instructor.
  6. 6Run and check the result. Run the generated Python yourself and confirm the values match the source text before using them.

What does the Instructor skill make the agent do?

Normally a model returns free text, which is hard to trust in a program. With this skill installed, the agent knows how to use the Instructor library to force the model's answer into a defined data structure, check the types and rules, and retry automatically if the check fails.

The skill covers response models (Pydantic), nested models, optional fields, enums for fixed choices, built-in and custom validators, retries, and streaming partial results. It also shows how to set up providers such as Anthropic and OpenAI.

  • Extract structured data from LLM responses
  • Validate outputs against Pydantic schemas
  • Retry failed extractions with error feedback to the model
  • Parse complex JSON with type safety
  • Stream partial results for real-time processing
  • Use one consistent API across multiple providers

How do I install the Instructor agent skill?

Download the ZIP file from this skill's page on our directory. Then either unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill to apply only to that project.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/ folder
  • Claude apps: Settings → Capabilities → Skills, then upload

Install the Python packages the code needs

The skill writes Python code, so you need Python and the libraries it imports. The base install is the instructor package. Add the provider extra for the model company you plan to use. The source lists instructor, pydantic, and provider SDKs such as openai or anthropic as dependencies.

  • Base library: pip install instructor
  • Anthropic: pip install "instructor[anthropic]"
  • OpenAI: pip install "instructor[openai]"
  • All listed providers: pip install "instructor[all]"
pip install instructor pip install "instructor[anthropic]" pip install "instructor[openai]" pip install "instructor[all]"

How do I trigger the skill with a natural request?

You do not need a special command. Describe the data you want from a model in plain language and say that it should be structured, validated, or parsed into fields. The skill's own list of use cases shows the kinds of requests it fits.

Good requests name the fields, the types, and the rules. For example, you might ask the agent to pull name, age and email from customer messages, with age between 0 and 120 and email in a valid format.

  • "Extract name, age and email from these messages into a Python model with validation."
  • "Write code that gets sentiment from reviews as one of positive, negative or neutral."
  • "Stream partial results from the model so my UI can update while it writes."
  • "Parse this LLM output into a Pydantic model and retry if a field is invalid."

What does a typical example look like?

A basic example defines a Pydantic model with name, age and email fields, creates an Instructor client from an Anthropic client, and calls messages.create with response_model set to that model. The result is a Python object with typed attributes rather than text to parse.

The skill also includes examples for OpenAI (instructor.from_openai with chat.completions.create), nested Address models inside a Person, and an enum-based sentiment classifier. Validators can reject a date that is not in YYYY-MM-DD format or an attendee count below 1.

  • Company info extraction: name, founded year, industry, employees
  • Sentiment classification with an enum and a confidence value between 0.0 and 1.0
  • Date-range checks with a model-level validator
user = client.messages.create( model="claude-sonnet-4-5-20250929", max_tokens=1024, messages=[{"role": "user", "content": "John Doe is 30 years old. His email is john@example.com"}], response_model=User ) print(user.name)

What do I need before the skill works?

You need Python, the packages above, and an API key and account with the LLM provider you choose, such as Anthropic or OpenAI. The skill makes network calls to that provider. It does not run scripts on its own, but the Python code it writes must be run by you or your project.

Each provider section in the skill shows how to pass a key to the client. The source also shows a local-model setup that points an OpenAI client at a localhost base URL, which is covered in the providers reference.

  • Python installed
  • instructor and pydantic packages, plus the provider SDK you use
  • API key and account for your LLM provider
  • Network access to that provider
  • Runs scripts: no. Uses network: yes.

What should I watch out for?

Validation checks format and rules, not whether the answer is true. A retry can still return a value that looks valid but is wrong. Do not use this for decisions that could cause harm without human review.

Retries are capped by max_retries, which defaults to 3 in the examples. Each retry sends the error back to the model. Use the skill only for Python projects, since the library and examples are Python-only.

  • Check important values by hand before acting on them
  • Validation is not fact-checking
  • Keep API keys out of shared code
  • Non-Python projects are not covered

What people use it for

  • Turning customer emails into database rows with typed name, age and email fields
  • Classifying product reviews into a fixed set of sentiment labels
  • Building API payloads from free-text LLM output with validation
  • Streaming partial answers from a model into a user interface
  • Extracting company facts such as founding year and industry from articles

Frequently asked questions

How do I install the Instructor skill?

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

What do I need to use the Instructor skill?

You need Python, the instructor and pydantic packages, a provider SDK such as openai or anthropic, and an API key and account with your chosen LLM provider. The skill makes network calls, so you need internet access.

Is the Instructor skill free to use?

The skill is listed under the MIT licence. The LLM provider you call will usually charge for API use, and the source does not give pricing, so check your provider's terms.

Does the Instructor skill run scripts on my computer?

No. The skill is listed as not running scripts. It produces Python code that you or your project must run, and that code calls your LLM provider over the network.

Why does my extraction keep failing or retrying?

Instructor retries when Pydantic validation fails, up to max_retries, which defaults to 3 in the examples. Check that your fields and validators match what the text actually contains, such as a missing age. Adjust the model or the prompt if retries do not succeed.

Does validation guarantee the extracted data is correct?

No. Validation checks types, formats and rules, not facts. A retry can return a plausible but incorrect value, so review results before using them where errors matter.

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 write Python and want LLM output turned into typed, validated objects with automatic retries across providers like Anthropic and OpenAI. Pick something else if you only need a one-off extraction in a chat window, if your project is not in Python, or if wrong values could cause harm without human review.

Download the skill