Pydantic AI Skills
Agent Skills support for Pydantic AI with progressive disclosure, remote skill registries, and sandboxed execution of bundled scripts — so your skill library can grow without bloating the prompt.
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.
What does this agent do, and when should you use it?
pydantic-ai-skills is a Python package that implements Agent Skills (agentskills.io) support for Pydantic AI, built around progressive disclosure: the model initially sees only each skill's name and description, and loads full instructions, reference documents, or scripts only when a task requires them. It requires and delegates to pydantic-ai-harness, which handles SKILL.md parsing, validation, cataloging, and instruction rendering; this package adds what harness deliberately leaves out: Git and S3 remote skill registries with composition (filter, prefix, rename, merge), bundled-file access via the read_skill_resource and run_skill_script tools, sandboxed execution, ${SKILL_DIR} placeholder resolution, and programmatic skills defined in Python with decorators or dataclasses. Each skill becomes a deferred Pydantic AI capability that the model activates on demand through Pydantic AI's built-in load_capability tool. The project is MIT-licensed, requires Python 3.10+, and ships full documentation including video tutorials and a v1-to-v2 migration guide.
The package reads skill folders following the agentskills.io spec — each must contain a SKILL.md with YAML frontmatter (name and description fields), optionally alongside reference documents, scripts, and resource files. SkillsCapability points the runtime at local directories; GitSkillsRegistry and other registries pull skills from Git repositories (e.g. anthropics/skills) or S3, with include/exclude to assign skill subsets per agent. The model sees skill names and descriptions first, calls Pydantic AI's load_capability to load a specific skill, then uses read_skill_resource(skill_name, resource_name) to read bundled files and run_skill_script(script_name, script_name, args) to execute bundled scripts; both tools refuse skills the model has not loaded. It also provides ${SKILL_DIR} placeholder resolution, custom script executors, sandboxing in containers or virtual filesystems, and programmatic skills defined via decorators or dataclasses that live in the same catalog.
- Teams building research assistants on Pydantic AI who want task-specific instruction sets (e.g. arXiv search) loaded on demand instead of stuffing every skill into the system prompt
- Teams with a growing skill library who need to distribute skills from a Git repository or S3 and customize per-agent subsets via filter, rename, and merge composition
- Developers using skill packs that ship reference docs and executable scripts — such as Anthropic's skills repository — who need bundled scripts to run as written, not just parsed instructions
- Engineers in security-sensitive environments who want untrusted skill scripts sandboxed in a container or virtual filesystem rather than running on the host
- Teams whose skills are instructions-only and want to evaluate using pydantic-ai-harness directly to keep the dependency footprint smaller
- Existing v1 users migrating to v2 who need to handle removed APIs like SkillsToolset and SkillsDirectory per the migration guide
What are this agent's strengths and limitations?
- Progressive disclosure lets the skill library scale without prompt cost: the model sees only names and descriptions up front, loading everything else on demand
- Builds on harness to add remote registries (Git, S3, plus composition), bundled-file read/execution, and programmatic skills — skill packs from Anthropic's skills repository run as written
- Offers container or virtual-filesystem sandboxing for untrusted scripts, plus include/exclude skill-subset assignment for governance
- Aligned with the open Agent Skills format (agentskills.io) — skills are portable, auditable folders; documentation is thorough with a v2 migration guide
- v2 is a clean break: SkillsToolset, SkillsDirectory, reload(), and the list_skills / load_skill tools are gone; v1 users must follow the migration guide
- Hard dependency on pydantic-ai-harness and the Pydantic AI framework — SKILL.md parsing, validation, and rendering live upstream, so it cannot be used outside that ecosystem
- For instructions-only skills, the README recommends harness directly since it is a smaller dependency with identical behaviour — adopting this package adds unnecessary weight
- Behavioral frontmatter fields such as allowed-tools are accepted but inert and restrict nothing here, which can create security-assumption gaps when migrating from platforms that honor them
- Remote skills introduce supply-chain risk: a malicious skill can direct the agent to invoke tools or execute code contrary to its stated purpose; the docs require auditing any skill from an unknown source
How do you install or deploy this agent?
Requires Python 3.10+. Recommended install with uv:
uv add pydantic-ai-skillsOr with pip:
pip install pydantic-ai-skillsThe package depends on and delegates to pydantic-ai-harness (pulled in automatically). Docs: https://dougtrajano.github.io/pydantic-ai-skillsHow do you use this agent?
Point SkillsCapability at one or more skill directories and add it to your Agent:
python
from pydantic_ai import Agent
from pydantic_ai_skills import SkillsCapabilityagent = 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)Pull skills from a remote repository:
python
from pydantic_ai_skills import GitSkillsRegistry, SkillsCapabilitycapability = SkillsCapability('./skills',
registries=[GitSkillsRegistry('https://github.com/anthropics/skills', path='skills')],
)
Skill anatomy: my-skill/ contains a required SKILL.md (frontmatter name must match the directory, max 64 chars, lowercase/hyphens; description max 1024 chars), plus optional REFERENCE.md, scripts/, and resources/. The model loads skills on demand with load_capability, then accesses files and scripts via read_skill_resource and run_skill_script.
How does this agent compare with similar options?
The README explicitly compares against pydantic-ai-harness: harness's Skills capability reads local SKILL.md packages and turns each into a deferred capability, but by design does not enumerate, read, or execute bundled files and has no remote-source concept. This package delegates to harness and fills those gaps with remote registries, bundled-file execution, sandboxing, and programmatic skills. If your skills are instructions only, use harness directly; a feature-by-feature comparison is in the official comparison docs.