Pydantic AI Skills

0.10.0 verified Sat May 09 auth: no python

A lightweight agent skill implementation for Pydantic AI, providing a framework for defining, loading, and executing reusable skills (tools) for AI agents. Current version 0.10.0 supports programmatic and filesystem-based skills, Git registries, and integration with pydantic-ai agents. Released on a rapid cadence (~monthly).

pip install pydantic-ai-skills

Common errors

error AttributeError: module 'pydantic_ai_skills' has no attribute 'Skill' ↓

cause Using an older version (<0.5.0) where Skill was not re-exported, or importing from wrong submodule.

fix

Upgrade to v0.5.0+ or import from pydantic_ai_skills.models.Skill (deprecated).

error ImportError: cannot import name 'SkillException' from 'pydantic_ai_skills' ↓

cause SkillException was removed in v0.10.0.

fix

Use ModelRetry from pydantic_ai.exceptions or stdlib exceptions instead.

Warnings

breaking In v0.10.0, SkillException hierarchy was replaced with ModelRetry and stdlib exceptions. Code catching SkillException will break. ↓

fix Replace `except SkillException:` with `except ModelRetry:` or appropriate stdlib exception (e.g., ValueError).

breaking v0.9.0 dropped compatibility with pydantic-ai versions earlier than 1.74. Older pydantic-ai versions are no longer supported. ↓

fix Upgrade pydantic-ai to >=1.74.

deprecated SkillsToolset auto_reload parameter (introduced in v0.6.0) is now deprecated. Use reload() method explicitly. ↓

fix Remove `auto_reload=True` and call `.reload()` manually when needed.

Imports

SkillsToolset
wrong
```
from pydantic_ai_skills.toolset import SkillsToolset
```
correct
```
from pydantic_ai_skills import SkillsToolset
```
SkillsToolset is re-exported from the top-level package; the submodule path changed in v0.5.0.

Skill

wrong

from pydantic_ai_skills.models import Skill

correct

from pydantic_ai_skills import Skill

Skill class moved to top-level in v0.5.0.

Quickstart

Quickstart: create a programmatic skill and use it with a pydantic-ai agent.

from pydantic_ai import Agent
from pydantic_ai_skills import SkillsToolset, Skill

# Define a skill programmatically
skill = Skill(
    name="greet",
    description="Greet the user by name.",
    content="Greet the user politely.",
    scripts=[
        {
            "language": "python",
            "code": "def greet(name: str) -> str:\n    return f'Hello, {name}!'",
            "entrypoint": "greet"
        }
    ]
)

# Create agent with skills toolset
agent = Agent('openai:gpt-4o', tools=SkillsToolset(skills=[skill]))

# Run agent
result = agent.run_sync('Greet Alice')
print(result.data)