NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #3635 most downloaded on PyPI
Remote skill registries and bundled-file execution for Pydantic AI Agent Skills
Last release today
04 Oct 2026
Ships fairly regularly
a new release about every 2 weeks
Nearly every release is documented
notes for 22 of 23 stable releases
Nothing withdrawn
no release was ever pulled
9 months old
23 releases · first in 2025
One column per month.
Nothing published for this version
This is a clean break. There are no deprecation shims.
pydantic-ai-harnessv2 stops reimplementing Agent Skills and becomes a companion to
pydantic-ai-harness.
harness now ships a Skills capability that covers levels 1 and 2 of the
Agent Skills spec — discovery, SKILL.md parsing, validation, the catalog,
and instruction rendering — and Pydantic AI's own load_capability tool loads a skill on demand.
v1 did all of that itself, which meant a parallel implementation guaranteed to drift from upstream.
So v2 delegates it, and keeps only what harness deliberately does not do:
references/, assets/ and scripts/, indexed and served${SKILL_DIR} resolution — harness leaves the placeholder in the instructions; thisIf your skills are instructions and nothing else — no references/, no scripts/, no remote
sources — you no longer need this package. Use pydantic_ai_harness.Skills directly: smaller
dependency, identical behaviour.
This is a clean break. There are no deprecation shims.
| v1 | v2 | |
|---|---|---|
pydantic-ai-slim |
>=1.105 |
>=2.38 |
pydantic-ai-harness |
not used | >=0.28, required |
| Python | >=3.10 |
>=3.10 |
harness sets a pydantic-ai-slim>=2.37 floor of its own; this package needs 2.38 for
AbstractCapability.visit_and_replace, which SkillsCapability overrides.
# v1
from pydantic_ai_skills import SkillsToolset
agent = Agent(model, toolsets=[SkillsToolset(directories=['./skills'])])
# v2
from pydantic_ai_skills import SkillsCapability
agent = Agent(model, capabilities=[SkillsCapability('./skills')])| v1 | v2 |
|---|---|
SkillsToolset |
SkillsCapability, passed via capabilities= |
list_skills tool |
The deferred-capability catalog, in the prompt |
load_skill tool |
Pydantic AI's load_capability |
SkillsDirectory, discover_skills() |
harness discovers; packages.index_libraries() indexes bundled files |
parse_skill_md(), validate_skill_metadata() |
harness parses and always validates |
Skill.from_file() |
harness loads directory-backed skills |
instruction_template= |
harness renders # Skill: <name> |
max_depth= |
Immediate children only, matching harness |
validate= |
harness always validates |
exclude_tools= |
resources=False / scripts=False |
reload(), auto_reload= |
Construct a new SkillsCapability |
defer_loading= on the capability |
Every skill is individually deferred |
SkillRegistry.search/get/install/update |
SkillRegistry.sync() -> Path |
SkillRegistry.get_skills() |
skill_infos() / skill_names() |
script_executor= on a registry |
script_executor= on SkillsCapability |
load_capability(id='pdf-processing'), notload_skill('pdf-processing'). Update any prompts or evals that name the old tool.max_depth for SKILL.md; v2 looks only at aSKILL.md whose frontmatter name disagrees withSkill objects. sync() subsumes install/update: it__init__ when auto_install=True; v2 clones on the firstsync(), so constructing a registry no longer touches the network.filtered() predicate now receives a SkillInfoSkill, and prefixed() / renamed() rewrite each staged package's frontmattername, because harness requires it to match the directory.SkillsCapability |
One composite over harness's Skills, carrying the bundled-file tools |
LocalSkillsRegistry |
A local directory that can take part in composition |
GitSkillsRegistry.revision() |
The commit SHA the local clone is on |
S3SkillsRegistry.revision(name) |
The newest object modification time for a skill |
SkillRegistry.__or__ |
a | b builds a CombinedRegistry |
require_loaded= |
Refuse file reads for a skill the model has not loaded, keeping bundled files behind the same boundary as the instructions |
resolve_skill_dir= |
Substitute ${SKILL_DIR} / ${CLAUDE_SKILL_DIR} in instructions with the real path |
list_bundled_files= |
Append a "Bundled files" section naming a skill's resources and scripts to its instructions |
@skill |
A standalone decorator for Python-defined skills, replacing @toolset.skill() |
Bundled-file ergonomics. The file tools key on skill-relative paths (scripts/aggregate.py),
while a SKILL.md names its own files in prose. So each loaded skill's instructions now list the
exact resource_name / script_name values — behind load_capability, never in the always-on
catalog — and both tools additionally accept an unambiguous shorthand (aggregate and
aggregate.py reach scripts/aggregate.py; two files sharing a name resolve to neither, and the
retry names both).
Full guide, including agent-spec changes and the reloading pattern for long-lived servers:
[Migrating from v1](https://dougtrajano.github.io/pydantic-ai-skills/migration-v2/)
pydantic-ai-harness +pydantic-ai-slim; the two move together, because pinning pydantic-ai-slim alone becomestests/test_harness_compat.py pins the harness surface this package depends on — harness is on0.x and documents that its API may change between minor releases.claude/skills/Full Changelog: 1.4.0...2.0.0
Update AGENTS.md by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/64
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/1.3.0...1.4.0
Full Changelog: 1.3.0...1.4.0
Add example with Pydantic AI Gateway/Logfire and Ollama Cloud Models by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/56
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/1.2.0...1.3.0
Full Changelog: 1.2.0...1.3.0
feat: discover all readable text files as skill resources (added exclude_resources arg (#54) by @DougTrajano in https://github.com/DougTrajano/pydanti
exclude_resources arg (#54) by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/55Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/1.1.0...1.2.0
exclude_resources arg (#54) by @DougTrajano in #55Full Changelog: 1.1.0...1.2.0
feat: support agent specs for SkillsCapability by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/53
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/1.0.0...1.1.0
Full Changelog: 1.0.0...1.1.0
pydantic-ai-skills has been stable and in production use for several months. This release marks the official v1.0.0, signaling a committed, stable pub
pydantic-ai-skills has been stable and in production use for several months. This release marks the official v1.0.0, signaling a committed, stable public API. It also brings the package fully in line with Pydantic AI v2 (capabilities-first/harness design) while keeping support for the v1 line back to 1.105.
1.105.0, 2.0.0, and latest in CI. SkillsCapability integrates cleanly with the v2 capabilities=[...] API.SkillsCapability now supports defer_loading=True (with a stable id and optional description), so the entire skills system can stay hidden behind the agent's load_capability tool until the model needs it. Useful for agents that bundle many capabilities. When deferred, the catalog entry is auto-summarized from the available skill names, overridable via description.pydantic-ai-slim>=1.105 (where on-demand / deferred capability loading was introduced). ⚠️ Breaking for environments pinned below 1.105.RunContext usage to the public pydantic_ai.RunContext import.from pydantic_ai.toolsets.skills import ... → pydantic_ai_skills across 44 docstring/doc examples (the old module path does not exist and would fail on copy-paste)._griffe, _function_schema, _utils) so future upstream changes fail loudly in CI.pydantic-ai-version axis (1.105.0, 2.0.0, latest).Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.11.0...1.0.0
feat: add S3SkillsRegistry for S3 and S3-compatible storage by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/48
S3SkillsRegistry for S3 and S3-compatible storage by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/48Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.10.1...0.11.0
S3SkillsRegistry for S3 and S3-compatible storage by @DougTrajano in #48Full Changelog: 0.10.1...0.11.0
feat: coerce JSON string args to dict in run_skill_script by @MateEggDeHome in https://github.com/DougTrajano/pydantic-ai-skills/pull/46
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.10.0...0.10.1
Full Changelog: 0.10.0...0.10.1
feat(DEV-1194): replace SkillException hierarchy with ModelRetry + stdlib exceptions by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-ski
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.9.0...0.10.0
Full Changelog: 0.9.0...0.10.0
DEV-1192: drop pre-1.74 pydantic-ai compatibility shims by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/41
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.8.0...0.9.0
Full Changelog: 0.8.0...0.9.0
Added env_vars and context_env_vars_extractor in the LocalSkillScriptExecutor() to inject variables into file system scripts by @DougTrajano in https:
env_vars and context_env_vars_extractor in the LocalSkillScriptExecutor() to inject variables into file system scripts by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/39Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.7.0...0.8.0
feat: Support non-Python scripts (sh, bash, etc.) by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/35
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.6.0...0.7.0
feat: Add SkillsToolset.reload() method and auto_reload parameter by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/29
SkillsToolset.reload() method and auto_reload parameter by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/29SkillsCapability feature (pydantic-ai>=1.71) by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/34Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.5.1...0.6.0
Standardize scheme-qualified naming conventions by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/22
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.5.0...0.5.1
You can now point your agent at any Git repository and have its skills available instantly, no manual copying required. The new GitSkillsRegistry clon
You can now point your agent at any Git repository and have its skills available instantly, no manual copying required. The new GitSkillsRegistry clones (or pulls) the repo on first use, discovers every SKILL.md inside it, and hands them directly to SkillsToolset.
from pydantic_ai_skills import SkillsToolset
from pydantic_ai_skills.registries import GitSkillsRegistry, GitCloneOptions
toolset = SkillsToolset(
registries=[
GitSkillsRegistry(
repo_url="https://github.com/anthropics/skills",
path="skills",
target_dir="./cached-skills",
clone_options=GitCloneOptions(depth=1, single_branch=True),
)
]
)
Key capabilities:
token, set GITHUB_TOKEN, use an ssh_key_file, or rely on anonymous access for public repos.FilteredRegistry, PrefixedRegistry, RenamedRegistry, and CombinedRegistry.auto_install=False to skip network calls entirely.source_url, repo, and version (HEAD commit SHA) for full auditability.Install with the git extra:
pip install "pydantic-ai-skills[git]"
/llms.txt & /llms-full.txt)The documentation site now exposes /llms.txt and /llms-full.txt — machine-readable summaries of the docs that LLMs can consume directly, following the emerging llms.txt convention.
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.4.1...0.5.0
Remove native integration notice from README by @mtessar in https://github.com/DougTrajano/pydantic-ai-skills/pull/11
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.4.0...0.4.1
some refactoring and new functionalities (skills_toolset decorators, etc.) by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/7
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.3.0...0.4.0
This release introduces comprehensive support for creating skills programmatically in Python code, providing a powerful alternative to filesystem-base
This release introduces comprehensive support for creating skills programmatically in Python code, providing a powerful alternative to filesystem-based skills.
Skill class with metadata, content, resources, and scripts@skill.resource decorator that can generate content on-demand and access RunContext[Deps] for state/dependencies@skill.script decorator with full parameter type safety and RunContext supportSkillsToolsetSkillMetadata into Skill class - skills now contain both metadata and content directlyFileBasedSkillResource and FileBasedSkillScript subclasses for filesystem variantslocal.py): Separate executors for file-based (LocalSkillScriptExecutor) and callable (CallableSkillScriptExecutor) scriptsSkillsToolset now accepts both directories and skills parameters for hybrid usageSkill.resource() decorator - Register callable resources with optional RunContext accessSkill.script() decorator - Register executable functions with parameter validationLocalSkillScriptExecutor - Execute file-based scripts via subprocessCallableSkillScriptExecutor - Wrap custom execution logic for scriptsFileBasedSkillResource - File-based resource with disk loadingFileBasedSkillScript - File-based script with subprocess executionexamples/programatic_skills.py demonstrating HR analytics use casefrom pydantic_ai import Agent, RunContext
from pydantic_ai_skills import Skill, SkillsToolset
# Create a programmatic skill
my_skill = Skill(
name='data-analytics',
description='Data analysis capabilities',
content='Use this skill for data analysis tasks.'
)
# Add dynamic resources
@my_skill.resource
async def get_schema(ctx: RunContext[MyDeps]) -> str:
"""Get database schema from dependencies."""
return await ctx.deps.get_schema()
# Add executable scripts
@my_skill.script
async def run_query(ctx: RunContext[MyDeps], query: str) -> str:
"""Execute SQL query.
Args:
query: SQL query string to execute
"""
result = await ctx.deps.execute(query)
return str(result)
# Use with SkillsToolset (can mix with file-based skills)
toolset = SkillsToolset(
directories=["./skills"], # File-based skills
skills=[my_skill] # Programmatic skills
)
agent = Agent(
model='openai:gpt-5.2',
deps_type=MyDeps,
toolsets=[toolset]
)
None - this release is fully backward compatible. All existing filesystem-based skills continue to work unchanged.
Existing users don't need to change anything. New users can choose:
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.2.0...0.3.0 Closes: #2
We did a huge internal refactoring to support more flexibility and native integration with the Pydantic AI as we are working on the https://github.com
We did a huge internal refactoring to support more flexibility and native integration with the Pydantic AI as we are working on the https://github.com/pydantic/pydantic-ai/pull/3780
Some of these changes include:
SkillsToolset.get_system_prompt() by SkillsToolset.get_instructions().# Add skills instructions to agent (includes skill names and descriptions)
@agent.instructions
async def add_skills(ctx: RunContext) -> str | None:
"""Add skills instructions to the agent's context."""
return await skills_toolset.get_instructions(ctx)
Skill, SkillResource, SkillScript, SkillScriptExecutor, which introduces more flexibility for remote or programmatic skills, a future path for https://github.com/DougTrajano/pydantic-ai-skills/issues/2Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.1.1...0.2.0
Added python_executable as an argument in the SkillsToolset class.
python_executable as an argument in the SkillsToolset class.anyio in the dependencies.Integrated with SonarQube and fixed some minor issues.
Full Changelog: https://github.com/DougTrajano/pydantic-ai-skills/compare/0.0.2...0.1.0
We're excited to introduce pydantic-ai-skills - a standardized framework for building and managing Agent Skills within the Pydantic AI ecosystem.
🎉 Initial Release
We're excited to introduce pydantic-ai-skills - a standardized framework for building and managing Agent Skills within the Pydantic AI ecosystem.
list_skills() - Discover available skillsload_skill() - Load full instructions when neededread_skill_resource() - Access additional documentationrun_skill_script() - Execute skill scripts with argumentspip install pydantic-ai-skills
Full documentation: https://dougtrajano.github.io/pydantic-ai-skills
Your coding agent can read these notes before it upgrades. Set up the MCP server →