Support Anthropic Skills built-in tool

[mattbrandman]

Description

Add support for native and custom anthropic skills via API as documented here. I think it’s mainly an addition to the code interpreter built in tool https://docs.claude.com/en/api/skills-guide

References

No response

[DouweM]

@mattbrandman OK so this feature requires the following things:

1. Somehow let users specify skills to be passed to the API as container.skills with the skills-2025-10-02 beta header
2. Store response.container.id (likely on ModelResponse.provider_metadata) and pass it in again when continuing a run (https://docs.claude.com/en/api/skills-guide#multi-turn-conversations)
3. Handle pause_turn (https://docs.claude.com/en/api/skills-guide#long-running-operations): Fix Anthropic pause_turn handling to allow agent continuation #3051
4. Handle the bash_code_execution_tool_result event type (https://docs.claude.com/en/api/skills-guide#downloading-generated-files), store the result in ModelResponse, and make sure generated file_ids can be read easily.
   1. It looks like this is a newer version of the code execution tool than the one we currently support: https://docs.claude.com/en/docs/agents-and-tools/tool-use/code-execution-tool.

It makes sense to me to consider this a feature of the CodeExecutionTool as you suggest; since it's so Anthropic specific, I think it should be a new anthropic_skills field that takes their own skill objects.

I don't think we need to concern ourselves with creating skills or uploading files into a container.

Regarding handling generated files: OpenAI Code Interpreter can generate images that we turn into a FilePart with BinaryContent in ModelResponse.parts (see second example at https://ai.pydantic.dev/builtin-tools/#usage_1), but in this case we don't get the actual file binary content, just a file ID. So it wouldn't make sense to make that a FilePart, unless we automatically download the file which could be unexpected. So until we have a native way to represent uploaded files (#2574) the file IDs would only be available on the BuiltinToolReturnPart.content, which is annoying but better than nothing. It'd require similar logic to get the ID as the extract_file_ids function in Anthropic's examples.

@mattbrandman Would you be up for working on this? :)

[mattbrandman]

@DouweM i definitely would be! Don't have a ton of time as I have a few other pressing projects but if they wrap up when I hope could potentially tackle late this month early next.

[chetanreddyv]

@DouweM @mattbrandman I would love to work on this, it will be my First Issue. Hope its fine?

[mattbrandman]

Don't have to ask me I'm not a maintainer :) also generally I think the attitude of this project (and most OSS i've been involved in) has been always feel free to make a PR!

[DouweM]

@chetanreddyv Feel free to work on this, but be warned that for your first issue I would have recommended picking something simpler 😄 I'll gladly review your PR either way, but I'd expect this one to be a lot easier for someone who has more experience with the code base like @mattbrandman.

[mattbrandman]

@DouweM started on this trying to break it up as much as possible. Need to also add logic to force a specific container or force a new one since they expire frequently

[alamkanak]

While the current discussion focuses on implementing native support for Anthropic's API-driven skills, I’d like to propose a broader approach.

The "AgentSkill" structure (as defined in the Anthropic Skills Overview) is effectively a standardized capability proposal. Even for models that don't natively support this on the server side (like OpenAI or local models), we could technically implement this pattern pydantic ai side.

The Idea:

• Model Agnostic: Treat the "Skill" format as a universal way to package tools and instructions.
• Prompt-Based Implementation: For non-Anthropic models, we could inject the skill definitions into the system prompt and provide standardized tools (e.g., bash, skill_call) for the model to interact with.
• Consistent UX: The agent would consume skill files and present them to the LLM in the Anthropic-style structure, but the execution and orchestration would be handled by pydantic ai (or the user of pydantic ai) rather than the provider’s server.

Why this matters:
Instead of building a feature that only works for Claude, we could leverage this standardized structure to give any LLM the same "skill-based" power.

Is it too far-fetched to consider an implementation that allows the anthropic_skills field (or a more generic skills field) to be utilized by other providers via client-side orchestration?

[DougTrajano]

I completely agree with @alamkanak

I created a Python package that introduces a tool-calling-based approach to use Agent Skills with Pydantic AI.

DougTrajano/pydantic-ai-skills: Pydantic AI with Agent Skills.

The dev experience is something like that:

pip install -U pydantic-ai-skills

from pydantic_ai import Agent
from pydantic_ai_skills import SkillsToolset

# Initialize Skills Toolset with one or more skill directories
skills_toolset = SkillsToolset(directories=["./skills"])

# Create agent with skills as a toolset
agent = Agent(
    model='openai:gpt-4o',
    instructions="You are a helpful research assistant.",
    toolsets=[skills_toolset]
)

# Add skills system prompt to agent
@agent.system_prompt
async def add_skills_to_system_prompt() -> str:
    return skills_toolset.get_skills_system_prompt()

# Use agent - skills tools are available for the agent to call
user_prompt = "What are the last 3 papers on arXiv about machine learning?"

nodes = []
async with agent.iter(user_prompt) as agent_run:
    async for node in agent_run:
        nodes.append(node)
        print(node)

Output:

UserPromptNode(user_prompt='What are the last 3 papers on arXiv about machine learning?', instructions_functions=[], system_prompts=('You are a helpful research assistant.',), system_prompt_functions=[SystemPromptRunner(function=<function add_skills_to_system_prompt at 0x110e951c0>, dynamic=False, _takes_ctx=False, _is_async=False)], system_prompt_dynamic_functions={})
ModelRequestNode(request=ModelRequest(parts=[SystemPromptPart(content='You are a helpful research assistant.', timestamp=datetime.datetime(2025, 12, 18, 23, 27, 16, 616893, tzinfo=datetime.timezone.utc)), SystemPromptPart(content="# Skills\n\nYou have access to skills that extend your capabilities. Skills are modular packages\ncontaining instructions, resources, and scripts for specialized tasks.\n\n## Available Skills\n\nThe following skills are available to you. Use them when relevant to the task:\n\n- **arxiv-search**: Search arXiv preprint repository for papers in physics, mathematics, computer science, quantitative biology, and related fields.\n- **pydanticai-docs**: Use this skill for requests related to Pydantic AI framework - building agents, tools, dependencies, structured outputs, and model integrations.\n- **web-research**: Use this skill for requests related to web research; it provides a structured approach to conducting comprehensive web research.\n## How to Use Skills\n\n**Progressive disclosure**: Load skill information only when needed.\n\n1. **When a skill is relevant to the current task**: Use `load_skill(skill_name)` to read the full instructions.\n2. **For additional documentation**: Use `read_skill_resource(skill_name, resource_name)` to read FORMS.md, REFERENCE.md, or other resources.\n3. **To execute skill scripts**: Use `run_skill_script(skill_name, script_name, args)` with appropriate command-line arguments.\n\n**Best practices**:\n- Select skills based on task relevance and descriptions listed above\n- Use progressive disclosure: load only what you need, when you need it, starting with load_skill\n- Follow the skill's documented usage patterns and examples\n", timestamp=datetime.datetime(2025, 12, 18, 23, 27, 16, 617375, tzinfo=datetime.timezone.utc)), UserPromptPart(content='What are the last 3 papers on arXiv about machine learning?', timestamp=datetime.datetime(2025, 12, 18, 23, 27, 16, 617384, tzinfo=datetime.timezone.utc))]))
CallToolsNode(model_response=ModelResponse(parts=[ToolCallPart(tool_name='load_skill', args='{"skill_name":"arxiv-search"}', tool_call_id='call_WGBvmGWJQvOliYoG5AeP6BMh')], usage=RequestUsage(input_tokens=717, output_tokens=17, details={'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}), model_name='gpt-4o-2024-08-06', timestamp=datetime.datetime(2025, 12, 18, 23, 27, 16, tzinfo=TzInfo(0)), provider_name='openai', provider_details={'finish_reason': 'tool_calls'}, provider_response_id='chatcmpl-CoHgqj5YugHHE2ZJvnQtXx3U74Uib', finish_reason='tool_call'))
ModelRequestNode(request=ModelRequest(parts=[ToolReturnPart(tool_name='load_skill', content='# Skill: arxiv-search\n**Description:** Search arXiv preprint repository for papers in physics, mathematics, computer science, quantitative biology, and related fields.\n**Path:** /Users/dougtrajano/Library/CloudStorage/OneDrive-Personal/dev/vscode/macbook/GitHub/pydantic-ai-skills/examples/skills/arxiv-search\n\n**Available Scripts:**\n- arxiv_search\n\n---\n\n# arXiv Search Skill\n\nThis skill provides access to arXiv, a free distribution service and open-access archive for scholarly articles in physics, mathematics, computer science, quantitative biology, quantitative finance, statistics, electrical engineering, systems science, and economics.\n\n## When to Use This Skill\n\nUse this skill when you need to:\n\n- Find preprints and recent research papers before journal publication\n- Search for papers in computational biology, bioinformatics, or systems biology\n- Access mathematical or statistical methods papers relevant to biology\n- Find machine learning papers applied to biological problems\n- Get the latest research that may not yet be in PubMed\n\n## Skill Scripts\n\n### arxiv_search\n\nThe `arxiv_search` script accepts the following arguments:\n\n- First argument (required): Search query string (e.g., "neural networks protein structure", "single cell RNA-seq")\n- `--max-papers` (optional): Maximum number of papers to retrieve (default: 10)\n\n### Usage Pattern\n\nUse the `run_skill_script` tool to execute the `arxiv_search` script. For example:\n\n```python\nrun_skill_script(\n    skill_name="arxiv-search",\n    script_name="arxiv_search",\n    args=["your search query", "--max-papers", "5"]\n)\n```\n\nSearch for computational biology papers (default 10 results):\n\n```python\nrun_skill_script(\n    skill_name="arxiv-search",\n    script_name="arxiv_search",\n    args=["protein folding prediction"]\n)\n```\n\n## Output Format\n\nThe script returns formatted results with:\n\n- **Title**: Paper title\n- **Summary**: Abstract/summary text\n- **URL**: Direct link to the paper on arXiv\n\nEach paper is separated by blank lines for readability.\n\n## Features\n\n- **Relevance sorting**: Results ordered by relevance to query\n- **Fast retrieval**: Direct API access with no authentication required\n- **Simple interface**: Clean, easy-to-parse output\n- **No API key required**: Free access to arXiv database\n\n## Dependencies\n\nThis skill requires the `arxiv` Python package. If not installed, you\'ll see an error message.\n\nTo install the package:\n\n```bash\npip install arxiv\n```\n\nThe package is not included by default since it\'s skill-specific. Install it when you first use this skill.\n\n## Notes\n\n- arXiv is particularly strong for:\n  - Computer science (cs.LG, cs.AI, cs.CV)\n  - Quantitative biology (q-bio)\n  - Statistics (stat.ML)\n  - Physics and mathematics\n- Papers are preprints and may not be peer-reviewed\n- Results include both recent uploads and older papers\n- Best for computational/theoretical work in biology', tool_call_id='call_WGBvmGWJQvOliYoG5AeP6BMh', timestamp=datetime.datetime(2025, 12, 18, 23, 27, 17, 430875, tzinfo=datetime.timezone.utc))]))
CallToolsNode(model_response=ModelResponse(parts=[ToolCallPart(tool_name='run_skill_script', args='{"skill_name":"arxiv-search","script_name":"arxiv_search","args":["machine learning","--max-papers","3"]}', tool_call_id='call_oDXHSlx4bpoV3Frm8fvWU8j4')], usage=RequestUsage(input_tokens=1395, output_tokens=38, details={'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}), model_name='gpt-4o-2024-08-06', timestamp=datetime.datetime(2025, 12, 18, 23, 27, 17, tzinfo=TzInfo(0)), provider_name='openai', provider_details={'finish_reason': 'tool_calls'}, provider_response_id='chatcmpl-CoHgraqy3S9OKCsFIP0Y3c1Sg6tqC', finish_reason='tool_call'))
ModelRequestNode(request=ModelRequest(parts=[ToolReturnPart(tool_name='run_skill_script', content='Title: Changing Data Sources in the Age of Machine Learning for Official Statistics\nSummary: Data science has become increasingly essential for the production of official statistics, as it enables the automated collection, processing, and analysis of large amounts of data. With such data science practices in place, it enables more timely, more insightful and more flexible reporting. However, the quality and integrity of data-science-driven statistics rely on the accuracy and reliability of the data sources and the machine learning techniques that support them. In particular, changes in data sources are inevitable to occur and pose significant risks that are crucial to address in the context of machine learning for official statistics.\n  This paper gives an overview of the main risks, liabilities, and uncertainties associated with changing data sources in the context of machine learning for official statistics. We provide a checklist of the most prevalent origins and causes of changing data sources; not only on a technical level but also regarding ownership, ethics, regulation, and public perception. Next, we highlight the repercussions of changing data sources on statistical reporting. These include technical effects such as concept drift, bias, availability, validity, accuracy and completeness, but also the neutrality and potential discontinuation of the statistical offering. We offer a few important precautionary measures, such as enhancing robustness in both data sourcing and statistical techniques, and thorough monitoring. In doing so, machine learning-based official statistics can maintain integrity, reliability, consistency, and relevance in policy-making, decision-making, and public discourse.\nURL: http://arxiv.org/abs/2306.04338v1\n\nTitle: DOME: Recommendations for supervised machine learning validation in biology\nSummary: Modern biology frequently relies on machine learning to provide predictions and improve decision processes. There have been recent calls for more scrutiny on machine learning performance and possible limitations. Here we present a set of community-wide recommendations aiming to help establish standards of supervised machine learning validation in biology. Adopting a structured methods description for machine learning based on data, optimization, model, evaluation (DOME) will aim to help both reviewers and readers to better understand and assess the performance and limitations of a method or outcome. The recommendations are formulated as questions to anyone wishing to pursue implementation of a machine learning algorithm. Answers to these questions can be easily included in the supplementary material of published papers.\nURL: http://arxiv.org/abs/2006.16189v4\n\nTitle: Learning Curves for Decision Making in Supervised Machine Learning: A Survey\nSummary: Learning curves are a concept from social sciences that has been adopted in the context of machine learning to assess the performance of a learning algorithm with respect to a certain resource, e.g., the number of training examples or the number of training iterations. Learning curves have important applications in several machine learning contexts, most notably in data acquisition, early stopping of model training, and model selection. For instance, learning curves can be used to model the performance of the combination of an algorithm and its hyperparameter configuration, providing insights into their potential suitability at an early stage and often expediting the algorithm selection process. Various learning curve models have been proposed to use learning curves for decision making. Some of these models answer the binary decision question of whether a given algorithm at a certain budget will outperform a certain reference performance, whereas more complex models predict the entire learning curve of an algorithm. We contribute a framework that categorises learning curve approaches using three criteria: the decision-making situation they address, the intrinsic learning curve question they answer and the type of resources they use. We survey papers from the literature and classify them into this framework.\nURL: http://arxiv.org/abs/2201.12150v2', tool_call_id='call_oDXHSlx4bpoV3Frm8fvWU8j4', timestamp=datetime.datetime(2025, 12, 18, 23, 27, 18, 930364, tzinfo=datetime.timezone.utc))]))
CallToolsNode(model_response=ModelResponse(parts=[TextPart(content='Here are the last three papers from arXiv about machine learning:\n\n1. **Title:** Changing Data Sources in the Age of Machine Learning for Official Statistics\n   - **Summary:** This paper discusses the increasing importance of data science in official statistics production, highlighting risks and uncertainties related to changing data sources in machine learning contexts. It covers issues like concept drift, bias, and data validity, and offers measures to maintain the reliability and integrity of machine learning-based statistics.\n   - **URL:** [Link to Paper](http://arxiv.org/abs/2306.04338v1)\n\n2. **Title:** DOME: Recommendations for supervised machine learning validation in biology\n   - **Summary:** The paper provides a set of community-wide recommendations for machine learning validation in biology, emphasizing the importance of a structured methods description using DOME (data, optimization, model, evaluation). These guidelines aim to improve the scrutiny of machine learning performance and facilitate better understanding and assessment of methods.\n   - **URL:** [Link to Paper](http://arxiv.org/abs/2006.16189v4)\n\n3. **Title:** Learning Curves for Decision Making in Supervised Machine Learning: A Survey\n   - **Summary:** This survey covers the concept of learning curves in machine learning, which assess algorithm performance concerning resources like training examples. The paper categorizes learning curve approaches based on decision-making situations, and it surveys literature to classify various models within this framework.\n   - **URL:** [Link to Paper](http://arxiv.org/abs/2201.12150v2)')], usage=RequestUsage(input_tokens=2177, cache_read_tokens=1408, output_tokens=322, details={'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}), model_name='gpt-4o-2024-08-06', timestamp=datetime.datetime(2025, 12, 18, 23, 27, 19, tzinfo=TzInfo(0)), provider_name='openai', provider_details={'finish_reason': 'stop'}, provider_response_id='chatcmpl-CoHgtHBD9LUsRKbILVar99GtAGKHM', finish_reason='stop'))
End(data=FinalResult(output='Here are the last three papers from arXiv about machine learning:\n\n1. **Title:** Changing Data Sources in the Age of Machine Learning for Official Statistics\n   - **Summary:** This paper discusses the increasing importance of data science in official statistics production, highlighting risks and uncertainties related to changing data sources in machine learning contexts. It covers issues like concept drift, bias, and data validity, and offers measures to maintain the reliability and integrity of machine learning-based statistics.\n   - **URL:** [Link to Paper](http://arxiv.org/abs/2306.04338v1)\n\n2. **Title:** DOME: Recommendations for supervised machine learning validation in biology\n   - **Summary:** The paper provides a set of community-wide recommendations for machine learning validation in biology, emphasizing the importance of a structured methods description using DOME (data, optimization, model, evaluation). These guidelines aim to improve the scrutiny of machine learning performance and facilitate better understanding and assessment of methods.\n   - **URL:** [Link to Paper](http://arxiv.org/abs/2006.16189v4)\n\n3. **Title:** Learning Curves for Decision Making in Supervised Machine Learning: A Survey\n   - **Summary:** This survey covers the concept of learning curves in machine learning, which assess algorithm performance concerning resources like training examples. The paper categorizes learning curve approaches based on decision-making situations, and it surveys literature to classify various models within this framework.\n   - **URL:** [Link to Paper](http://arxiv.org/abs/2201.12150v2)'))

My implementation consists of two main components:

• The SkillsToolset provides tools to use skills: list_skills(), load_skill(), read_skill_resource(), run_skill_script().
• The SkillsToolset().get_skills_system_prompt() provides the available skills and how to use them effectively to the agent.

If you guys like the implementation, I will be glad to collaborate and move it to the Pydantic AI repo.

[DouweM]

@alamkanak I completely agree that now that Skills are a standard that's been adopted by multiple providers, Pydantic AI should natively support it in a generic way that works across all model providers.

It could leverage native support when available, but I'm not sure that actually make sense considering access to local files, running scripts etc. If we do go that route (under some conditions, like there being no scripts), note that it's also how we're planning to support deferred loading of tools and programmatic tool calling: #3666 (comment), by essentially falling back from the "builtin tool" to a Pydantic AI side implementation if the builtin tool is not supported by a given model: #3212

@DougTrajano Nice work!

As it happens, @DEENUU1 at VStorm.co also just built a SkillsToolset as part of https://github.com/vstorm-co/pydantic-deepagents, which they're adding to our "Third Party Toolsets" docs in #3747 (comment), after which they'll be looking at extracting it into a separate package and possibly upstreaming it.

As a first step, so that our users can find these toolsets ASAP, would you mind submitting a PR to add your package to those docs as well? (you may get there before they do, in which case they can add their link to your existing section, so write it to allow for multiple implementations)

Then as a next step I'd gladly receive a PR to add this to Pydantic AI, but I suggest you have a look at their implementation as well so we can take take the best bits of both.

[DougTrajano]

Hi @DouweM ok, I will prepare a PR to add pydantic-ai-skills to the docs.

Yeap, I actually used the @DEENUU1 package as a reference, great project, btw! However, I made some changes to use anyio when calling scripts to be async-first and anyio is already used in pydantic-ai, decouple from pydantic and pydantic-settings (as per Pydantic AI philosophy), and make it very lightweight; it only needs pydantic-ai-slim, anyio, and pyyaml (new dep).

I essentially separated the Agent Skills implementation from Deep Agents and made some refinements to improve performance and usability.

I will submit a PR and tag you and @DEENUU1 for review.

[jbnitorum]

Been following along on this thread. Just wanted to share in case anyone here hasn’t seen that this has moved from “effectively a standard” to “literally a standard”.

The MCP playbook worked. Now we're doing it again.
Agent Skills — our format for giving agents procedural knowledge — is now an open standard. Already adopted by Microsoft, Cursor, GitHub, and others.
Spec + SDK: agentskills.io

They reference a tool based approach to integration but don’t offer any sort of implementation guidance.