Metadata-Version: 2.4
Name: pydantic-ai-skills
Version: 1.3.0
Summary: A lightweight agent skill implementation for Pydantic AI
Project-URL: Homepage, https://github.com/dougtrajano/pydantic-ai-skills
Project-URL: Source, https://github.com/dougtrajano/pydantic-ai-skills
Author-email: Douglas Trajano <douglas.trajano@outlook.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: anyio>=4.0.0
Requires-Dist: pydantic-ai-slim>=1.105
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: black>=26.5.0; extra == 'dev'
Requires-Dist: isort>=8.0.0; extra == 'dev'
Requires-Dist: mypy>=2.3.0; extra == 'dev'
Requires-Dist: pre-commit>=4.6.0; extra == 'dev'
Requires-Dist: ruff>=0.15.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.5.0; extra == 'docs'
Requires-Dist: mkdocs-llmstxt>=0.2.0; extra == 'docs'
Requires-Dist: mkdocs-material-extensions>=1.3.1; extra == 'docs'
Requires-Dist: mkdocs-material>=9.7.1; extra == 'docs'
Requires-Dist: mkdocs-section-index>=0.3.10; extra == 'docs'
Requires-Dist: mkdocs-tooltips>=0.1.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=1.0.0; extra == 'docs'
Provides-Extra: examples
Requires-Dist: arxiv>=3.0.0; extra == 'examples'
Requires-Dist: datasets>=4.8.0; extra == 'examples'
Requires-Dist: ddgs>=9.14.0; extra == 'examples'
Requires-Dist: gitpython>=3.1.0; extra == 'examples'
Requires-Dist: httpx>=0.28.0; extra == 'examples'
Requires-Dist: langchain-community>=0.4.0; extra == 'examples'
Requires-Dist: logfire>=4.32.0; extra == 'examples'
Requires-Dist: pydantic-ai-slim[logfire,mcp,openai]>=2.0.0; extra == 'examples'
Requires-Dist: python-dotenv>=1.2.0; extra == 'examples'
Requires-Dist: uvicorn>=0.46.0; extra == 'examples'
Provides-Extra: git
Requires-Dist: gitpython>=3.1.40; extra == 'git'
Provides-Extra: s3
Requires-Dist: boto3>=1.26.0; extra == 's3'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: types-pyyaml>=6.0.12; extra == 'test'
Description-Content-Type: text/markdown

# pydantic-ai-skills

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=DougTrajano_pydantic-ai-skills&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=DougTrajano_pydantic-ai-skills)

[Agent Skills](https://agentskills.io/home) for [Pydantic AI](https://ai.pydantic.dev/).

**Agent Skills** are modular packages of instructions, resources, and scripts that teach an agent to
handle a specialized task. On disk, a skill is just a folder: a `SKILL.md` file holding a name, a
description, and Markdown instructions, plus any reference documents and executable scripts the task
needs.

Your agent starts out seeing only the name and description of each skill. When a task calls for one,
it loads that skill's full instructions, and reads a reference document or runs a script only if it
actually needs to. This is *progressive disclosure*: your skill library can grow without every skill
paying for space in the prompt.

📖 **[Full documentation](https://dougtrajano.github.io/pydantic-ai-skills)** — including
[video tutorials](https://dougtrajano.github.io/pydantic-ai-skills/quick-start/#video-tutorials).

## Why This and Not `pydantic-ai-harness`

The harness's own `Skills` capability is a minimal reader: it injects `SKILL.md` instructions but
[does not enumerate, read, or execute bundled files](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/skills).
`pydantic-ai-skills` implements the full package — bundled resources, script execution, remote
registries, programmatic skills, and reload at runtime — so skills that ship a reference document or
a script (including those in [Anthropic's skills repository](https://github.com/anthropics/skills))
run as written. Feature-by-feature comparison:
[Why pydantic-ai-skills](https://dougtrajano.github.io/pydantic-ai-skills/comparison/).

## Installation

```bash
uv add pydantic-ai-skills
```

Millennials may continue to use `pip install pydantic-ai-skills`. It still works, like your Spotify
playlist from 2013.

## Quick Start

Point a `SkillsCapability` at one or more skill directories and add it to your agent:

```python
from pydantic_ai import Agent
from pydantic_ai_skills import SkillsCapability

agent = Agent(
    model='gateway/openai:gpt-5.2',
    instructions='You are a helpful research assistant.',
    capabilities=[SkillsCapability(directories=['./skills'])],
)

result = await agent.run('What are the last 3 papers on arXiv about machine learning?')
print(result.output)
```

`SkillsToolset` is the same thing as a toolset, for agents built around `toolsets=[...]`:

```python
from pydantic_ai_skills import SkillsToolset

agent = Agent(model='gateway/openai:gpt-5.2', toolsets=[SkillsToolset(directories=['./skills'])])
```

Both inject the skill catalog into the agent's instructions automatically and expose four tools:

| Tool | Purpose |
| --- | --- |
| `list_skills()` | List available skills (optional — the catalog is already in the prompt) |
| `load_skill(name)` | Read a skill's full instructions |
| `read_skill_resource(skill_name, resource_name)` | Read a bundled file such as `REFERENCE.md` |
| `run_skill_script(skill_name, script_name, args)` | Run a bundled script with named arguments |

See [Quick Start](https://dougtrajano.github.io/pydantic-ai-skills/quick-start/).

## Anatomy of a Skill

```md
my-skill/
├── SKILL.md      # Required: YAML frontmatter + Markdown instructions
├── REFERENCE.md  # Optional: extra docs, read on demand
├── scripts/      # Optional: executable scripts
└── resources/    # Optional: templates, data files
```

```markdown
---
name: my-skill
description: Brief description of what this skill does and when to use it
---

# My Skill

## When to Use This Skill

Use this skill when you need to...

## Instructions

1. Step 1
2. Step 2
```

`name` (max 64 chars, lowercase letters, numbers and hyphens) and `description` (max 1024 chars) are
required; other frontmatter fields are yours to use. See
[Creating Skills](https://dougtrajano.github.io/pydantic-ai-skills/creating-skills/).

## Beyond the Filesystem

- **[Programmatic skills](https://dougtrajano.github.io/pydantic-ai-skills/programmatic-skills/)** — define skills in Python with decorators or dataclasses.
- **[Registries](https://dougtrajano.github.io/pydantic-ai-skills/registries/)** — load skills from Git repositories, S3, or custom sources, and compose them (combine, filter, prefix, rename).
- **[Skill selection](https://dougtrajano.github.io/pydantic-ai-skills/advanced/#selecting-which-skills-to-expose)** — give each agent a subset of a shared library with `include` / `exclude`.
- **[Advanced features](https://dougtrajano.github.io/pydantic-ai-skills/advanced/)** — `reload()` / `auto_reload`, `exclude_tools`, deferred loading, recursive discovery.

## Security

Only use skills from sources you trust. Skills give agents new capabilities through instructions and
code, so a malicious skill can direct an agent to invoke tools or execute code in ways that don't
match its stated purpose — with risks including data exfiltration and unauthorized system access.
Audit any skill from an unknown source before use. See
[Security & Deployment](https://dougtrajano.github.io/pydantic-ai-skills/security/).

## Related Resources

- [Agent Skills Specification](https://agentskills.io/specification)
- [Anthropic Agent Skills docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and [best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
- [Agent Skills Cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/skills)
- [Pydantic AI Documentation](https://ai.pydantic.dev/)

## Contributing

Contributions are welcome — see [Contributing](https://dougtrajano.github.io/pydantic-ai-skills/contributing/).

## Acknowledgments

Thanks to **Anthropic** for the [Agent Skills](https://agentskills.io/home) open format, the
**Pydantic AI team** for the framework, and the **community** for feedback and contributions.

This project was highly inspired by [pydantic-deepagents](https://github.com/vstorm-co/pydantic-deepagents),
which provided foundational ideas and patterns for agent skills and progressive disclosure in Pydantic AI.

## License

MIT License — see [LICENSE](LICENSE).
