Pydantic AI Skills
Add progressively disclosed skills, remote registries, bundled resources, and script execution to Pydantic AI.
- Source repo
- DougTrajano/pydantic-ai-skills
- Stars
- ★ 380
- Last updated
- 6d ago
- License
- MIT
- Primary language
- Python
- FA score
- 86/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Pydantic AI team with a large skill library wants the model to see only names and descriptions initially, loading detailed instructions and references only for relevant tasks.
- Not a fit if
- Teams with instruction-only skills should use pydantic-ai-harness directly instead
- Applications on a runtime other than Pydantic AI need their own integration
- Teams that cannot audit third-party skills, given exfiltration and access risks
- Source review
- 86/100 · Good
What does this agent do, and when should you use it?
Pydantic AI Skills is a Python package that brings the Agent Skills format to Pydantic AI while limiting prompt growth through progressive disclosure. It relies on pydantic-ai-harness for SKILL.md parsing, validation, catalog construction, and instruction rendering, then adds Git, S3, and custom registries with filtering, prefixing, renaming, and merging. SkillsCapability exposes each skill as a deferred Pydantic AI capability, so the model initially sees only its name and description and uses load_capability when full instructions are needed. Once a skill is loaded, the agent can read bundled files through read_skill_resource or execute named scripts with arguments through run_skill_script; both reject unloaded skills by default. The package also supports Python-defined programmatic skills, ${SKILL_DIR} substitution, and script isolation in a container or virtual filesystem. It is a fit for Pydantic AI applications that need complete skill packages and remote distribution, while instruction-only libraries are better served by the smaller pydantic-ai-harness dependency.
Developers pass one or more local skill directories to SkillsCapability and can add Git repositories through GitSkillsRegistry; the documentation also identifies S3 and custom sources. pydantic-ai-harness parses and validates SKILL.md, builds the catalog, and renders instructions, while this package registers each skill as a deferred Pydantic AI capability. The model first receives only each skill's name and description, then calls Pydantic AI's built-in load_capability when it needs the complete instructions. After loading, read_skill_resource(skill_name, resource_name) reads bundled files such as references or resources, and run_skill_script(skill_name, script_name, args) executes a bundled script with named arguments. The runtime can resolve ${SKILL_DIR} and isolate execution through custom executors, containers, or virtual filesystems. The package does not prescribe the business output; results are produced by the surrounding Pydantic AI Agent, its configured model, and the selected skill.
- A Pydantic AI team with a large skill library wants the model to see only names and descriptions initially, loading detailed instructions and references only for relevant tasks.
- A developer wants to reuse skills stored in Git, S3, or custom sources and compose registries by combining, filtering, prefixing, renaming, or merging their contents.
- A team adopting the Agent Skills directory format has packages containing reference documents or scripts and needs Pydantic AI to read and run those bundled files.
- A multi-agent application shares one skill library but needs include and exclude rules to expose a different subset to each agent.
- A deployment team needs to run third-party skill scripts while reducing host exposure through a container, virtual filesystem, or custom script executor.
How do you install or deploy this agent?
Python 3.10 or later is required. Install with uv:
uv add pydantic-ai-skillsAlternatively, install with pip:
pip install pydantic-ai-skillsThe package depends on pydantic-ai-harness and is used with Pydantic AI. The supplied material does not document the gateway setup, credential variable, or credential-acquisition steps needed by the example model gateway/openai:gpt-5.2; those must be configured through the corresponding Pydantic AI model setup before running it. Remote Git or S3 registries also require network access, and the source does not provide S3 authentication instructions.
How do you use this agent?
Add a local skill directory to a Pydantic AI Agent through SkillsCapability. The supplied first invocation assumes an asynchronous context in which await is valid:
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('./skills')],
)
result = await agent.run('What are the last 3 papers on arXiv about machine learning?')
print(result.output)To pull skills from a Git repository, configure GitSkillsRegistry:
from pydantic_ai_skills import GitSkillsRegistry, SkillsCapability
capability = SkillsCapability(
'./skills',
registries=[GitSkillsRegistry('https://github.com/anthropics/skills', path='skills')],
)Every skill directory requires a SKILL.md with YAML frontmatter containing at least name and description. The name must match the directory, be no longer than 64 characters, and contain only lowercase letters, digits, and hyphens; description is limited to 1,024 characters. Once the model loads a skill, it can use read_skill_resource for bundled files and run_skill_script for scripts. The default boundary refuses access to a skill that has not been loaded.
What are this agent's strengths and limitations?
- Progressive disclosure exposes only skill names and descriptions up front, loading full instructions, references, and scripts on demand.
- It extends pydantic-ai-harness with Git, S3, and custom remote sources plus filtering, prefixing, renaming, merging, and other registry composition.
- The read_skill_resource and run_skill_script interfaces cover bundled documents and executable scripts that harness alone does not enumerate or execute.
- It supports programmatic Python skills, ${SKILL_DIR} resolution, and container, virtual-filesystem, or custom script execution.
- Adoption requires Pydantic AI and pydantic-ai-harness; applications using another runtime would need their own integration.
- Skill instructions and code can create data-exfiltration or unauthorized-access risks, so unknown sources require auditing.
- Behavioral frontmatter such as allowed-tools is accepted but inert and cannot be treated as an authorization boundary.
- Version 2 is a breaking change from version 1: SkillsToolset, SkillsDirectory, reload(), list_skills, and load_skill were removed in favor of harness and load_capability.
- For instruction-only skills, the project recommends using pydantic-ai-harness directly, making this package unnecessary overhead in simpler deployments.
How does this agent compare with similar options?
Compared with pydantic-ai-harness, this project delegates SKILL.md parsing, validation, catalog management, and instruction rendering to harness rather than replacing it. Harness's Skills capability reads local SKILL.md packages and exposes deferred capabilities, but it does not enumerate, read, or execute bundled files and has no remote-source abstraction. Pydantic AI Skills adds Git, S3, and custom registries, registry composition, read_skill_resource, run_skill_script, sandboxed execution, ${SKILL_DIR} substitution, and programmatic skills. The documentation recommends harness alone for instruction-only skills; this package is the broader option when remote distribution or bundled resources and scripts are required.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Pydantic AI Skills This agent | 86 · Good | Library / SDKFree + model costs | ★ 380 | 6d ago | Python | OpenAI API |
| VT Code | 66 · Some gaps | CLIFree + model costs | ★ 884 | today | Rust | OpenAI API |
| FastAgent | 46 · Major gaps | CLIFree + model costs | ★ 3.9k | 1d ago | Python | Codex · OpenAI API · Claude API |
| AgenticX Multi-Agent Platform | 64 · Some gaps | CLIFree + model costs | ★ 593 | today | Python | Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: bundled-file tools refuse unloaded skills by default with an explicit retry-prompt path tested; sandbox staging skips symlink escapes with a warning; workdir avoids /tmp; SECURITY.md states the trust boundary honestly ('loading an untrusted skill is equivalent to running untrusted code'). Deductions: the default executor still runs scripts as host subprocesses — sandboxing is an opt-in extra, not the default; there is no human-confirmation mechanism, only load gating; no evidence of a rollback/recovery path for registry syncs. least_privilege and external_effects score 2 for the host-execution default; user_confirmation 1; rollback 1.
Evidence shows: construction-time validation errors surface verbatim from harness; include/exclude typos raise errors listing available skills; missing extras raise ImportErrors naming the extra; sandbox reuse, restage-on-edit, and lifetime expiry are all pinned by tests. Dependency floors (pyyaml 6.0.1, pytest-asyncio 0.23.5) are actually exercised in a CI test-lowest-versions job. All three criteria are fully supported with no identifiable deduction.
Evidence shows: audience (Pydantic AI developers) and scenarios clearly split — instructions-only skills should use harness directly, this package adds remote registries and bundled files, with a comparison link; boundaries stated honestly ('allowed-tools ... do not restrict anything here'); Python 3.10–3.14 CI matrix and per-feature extras, with localsandbox degrading cleanly on 3.10/3.11. Deduction: trigger precision depends on the model autonomously calling load_capability, which static evidence cannot verify — trigger_precision scores 2.
Evidence shows: MIT LICENSE matches pyproject metadata; hatch-vcs versioning from git tags with a tarball fallback; a v1→v2 migration guide enumerating breaking changes; SECURITY.md with private advisory reporting and a 7-day response commitment; strict docs build in CI. Deductions: no CHANGELOG file is present in the provided sources; examples/FAQ live mostly in external docs not verifiable here; maintenance rests on a single author. versioning_changelog, examples_and_faq, and maintenance_responsibility score 2.
Evidence shows: output usability pinned end to end (load_capability → read_resource → run_script); marginal value is explicit and honest — the README itemizes what it adds over harness and recommends harness alone for instructions-only skills; cost is managed via inventory truncation ('...and 10 more') and not registering tools no skill can use. All three criteria fully earned with concrete file evidence.
Evidence shows: nearly every behavioral claim in the README (load gating, placeholder resolution, SKILL.md-only discovery, name/directory match) maps to a dedicated pinning test, giving strong claim traceability. Deductions: the external docs site (security model, comparison page) is outside the reviewed sources, so cross-source corroboration is only partial; the SonarCloud badge status cannot be verified statically. cross_source_corroboration and fact_inference_separation score 2; claim_traceability scores 3.
- The default script executor runs skill scripts as host subprocesses; when consuming untrusted registry (Git/S3) skills, explicitly configure a sandbox executor or scripts execute directly on the host.
- Behavioural frontmatter fields such as allowed-tools are entirely inert in this package — do not assume they constrain a skill.
- The load gate only blocks reading files before loading the skill; it is not a defense against a malicious skill's instructions or its scripts' side effects. The source itself warns that untrusted skill = untrusted code.
- Verify the external security-model documentation yourself before adoption; this static review could not cover off-site pages.
- Single-author maintenance and no CHANGELOG file; watch the test-lowest-versions CI job when upgrading, especially the coupled pydantic-ai-slim/harness floors.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
2.1.0 v2.1.0
Release notes excerpt
<!-- Release notes generated using configuration in .github/release.yml at main --> What's Changed 🔧 Other Changes * chore: upstream watch 2026-09-11 (no changes needed) by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/86 * chore: upstream watch 2026-09-18 (no changes needed) by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/87 * chore: upstream watch 2026-09-25 (no changes needed) by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/88 …View on GitHub ↗ -
2.0.0 v2.0.0
Release notes excerpt
v2.0.0 — rebuilt on pydantic-ai-harness v2 stops reimplementing Agent Skills and becomes a companion to [pydantic-ai-harness](https://github.com/pydantic/pydantic-ai-harness). harness now ships a Skills capability that covers levels 1 and 2 of the [Agent Skills spec](https://agentskills.io) — 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. …View on GitHub ↗ -
1.4.0 v1.4.0
Release notes excerpt
What's Changed * Update AGENTS.md by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/64 * chore: upstream watch 2026-08-01 (no changes needed) by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/66 * chore: upstream watch 2026-08-07 (no changes needed) by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/67 * chore: upstream watch 2026-08-14 (no changes needed) by @DougTrajano in https://github.com/DougTrajano/pydantic-ai-skills/pull/68 …View on GitHub ↗