DougTrajano/pydantic-ai-skills

What it solves

It enables AI agents to scale their capabilities without bloating the prompt. By using "progressive disclosure," agents only see a high-level catalog of available skills (names and descriptions) and only load the full instructions, reference documents, or executable scripts when a specific task requires them.

How it works

The project implements a system for managing "Agent Skills"—modular packages containing a SKILL.md file for instructions, along with optional scripts and resources. It extends pydantic-ai-harness by adding:

• Remote Registries: The ability to pull skills from Git repositories or S3 buckets.
• Bundled File Execution: Tools (read_skill_resource and run_skill_script) that allow the agent to read bundled documentation or execute scripts associated with a skill.
• Sandboxing: Support for running untrusted scripts in containers or virtual filesystems to protect the host machine.
• Programmatic Definition: The ability to define skills directly in Python code using decorators or dataclasses.

Who it’s for

Developers building agents with Pydantic AI who need to manage a large library of specialized tasks and want to integrate external skill repositories (like Anthropic's skills repository) while maintaining security and prompt efficiency.

Highlights

• Progressive Disclosure: Prevents prompt overflow by loading detailed instructions only on demand.
• Remote Sourcing: Supports Git and S3 registries with filtering and merging capabilities.
• Secure Execution: Includes sandboxing options for executing bundled skill scripts.
• Dynamic Resolution: Automatically handles ${SKILL_DIR} path placeholders within skill files.