Skip to content
Back to search

pydantic-ai-skills

This package implements Agent Skills (https://agentskills.io) support with progressive disclosure for Pydantic AI. Supports filesystem and programmatic skills.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/DougTrajano/pydantic-ai-skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/DougTrajano/pydantic-ai-skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dougtrajano--pydantic-ai-skills/badge.svg)](/listings/dougtrajano--pydantic-ai-skills)

HTML

<a href="/listings/dougtrajano--pydantic-ai-skills"><img src="/api/listings/dougtrajano--pydantic-ai-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

uv add pydantic-ai-skills

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 175 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # pydantic-ai-skills
  2. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![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)
  5. Remote skill registries and bundled-file execution for [Agent Skills](https://agentskills.io/home)
  6. in [Pydantic AI](https://ai.pydantic.dev/).
  7. **Agent Skills** are modular packages of instructions, resources, and scripts that teach an agent to
  8. handle a specialized task. On disk, a skill is just a folder: a `SKILL.md` file holding a name, a
  9. description, and Markdown instructions, plus any reference documents and executable scripts the task
  10. needs.
  11. Your agent starts out seeing only the name and description of each skill. When a task calls for one,
  12. it loads that skill's full instructions, and reads a reference document or runs a script only if it
  13. actually needs to. This is *progressive disclosure*: your skill library can grow without every skill
  14. paying for space in the prompt.
  15. 📖 **[Full documentation](https://dougtrajano.github.io/pydantic-ai-skills)** — including
  16. [video tutorials](https://dougtrajano.github.io/pydantic-ai-skills/quick-start/#video-tutorials).
  17. ## How This Relates to `pydantic-ai-harness`
  18. [`pydantic-ai-harness`](https://github.com/pydantic/pydantic-ai-harness) ships a `Skills` capability
  19. that reads `SKILL.md` packages from local directories and turns each into a deferred Pydantic AI
  20. capability. It stops there by design — it
  21. [does not enumerate, read, or execute bundled files](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/skills),
  22. and it has no notion of a remote source.
  23. `pydantic-ai-skills` is the companion that fills those gaps. It **requires harness and delegates to
  24. it**, so `SKILL.md` parsing, validation, the catalog and instruction rendering are all upstream's,
  25. and adds:
  26. - **Remote registries** — Git and S3 sources, with composition (filter, prefix, rename, merge).
  27. - **Bundled files** — `read_skill_resource` and `run_skill_script`, so a skill that ships a
  28. reference document or a script (including those in
  29. [Anthropic's skills repository](https://github.com/anthropics/skills)) runs as written.
  30. - **Sandboxed execution** — keep untrusted scripts off the host.
  31. - **`${SKILL_DIR}` resolution** — harness leaves the placeholder in place; this substitutes the path.
  32. - **Programmatic skills** — skills defined in Python, in the same catalog.
  33. If your skills are instructions and nothing else, use harness directly — it is a smaller dependency
  34. and identical behaviour. Feature-by-feature:
  35. [comparison](https://dougtrajano.github.io/pydantic-ai-skills/comparison/).
  36. > **Upgrading from v1?** v2 is a clean break: `SkillsToolset`, `SkillsDirectory`, `reload()` and the
  37. > `list_skills` / `load_skill` tools are gone, replaced by harness and Pydantic AI's own
  38. > `load_capability`. See the
  39. > [migration guide](https://dougtrajano.github.io/pydantic-ai-skills/migration-v2/).
  40. ## Installation
  41. ```bash
  42. uv add pydantic-ai-skills
  43. ```
  44. Millennials may continue to use `pip install pydantic-ai-skills`. It still works, like your Spotify
  45. playlist from 2013.
  46. ## Quick Start
  47. Point a `SkillsCapability` at one or more skill libraries and add it to your agent:
  48. ```python
  49. from pydantic_ai import Agent
  50. from pydantic_ai_skills import SkillsCapability
  51. agent = Agent(
  52. model='gateway/openai:gpt-5.2',
  53. instructions='You are a helpful research assistant.',
  54. capabilities=[SkillsCapability('./skills')],
  55. )
  56. result = await agent.run('What are the last 3 papers on arXiv about machine learning?')
  57. print(result.output)
  58. ```
  59. Or pull them from a repository:
  60. ```python
  61. from pydantic_ai_skills import GitSkillsRegistry, SkillsCapability
  62. capability = SkillsCapability(
  63. './skills',
  64. registries=[GitSkillsRegistry('https://github.com/anthropics/skills', path='skills')],
  65. )
  66. ```
  67. Each skill becomes its own **deferred capability**: the model sees names and descriptions up front,
  68. loads the ones it needs with Pydantic AI's built-in `load_capability`, then reaches that skill's
  69. files with the two tools this package adds:
  70. | Tool | Purpose |
  71. | --- | --- |
  72. | `read_skill_resource(skill_name, resource_name)` | Read a bundled file such as `references/FORMS.md` |
  73. | `run_skill_script(skill_name, script_name, args)` | Run a bundled script with named arguments |
  74. Both stay behind the same boundary as the skill's instructions: by default they refuse a skill the
  75. model has not loaded.
  76. See [Quick Start](https://dougtrajano.github.io/pydantic-ai-skills/quick-start/).
  77. ## Anatomy of a Skill
  78. ```md
  79. my-skill/
  80. ├── SKILL.md # Required: YAML frontmatter + Markdown instructions
  81. ├── REFERENCE.md # Optional: extra docs, read on demand
  82. ├── scripts/ # Optional: executable scripts
  83. └── resources/ # Optional: templates, data files
  84. ```
  85. ```markdown
  86. ---
  87. name: my-skill
  88. description: Brief description of what this skill does and when to use it
  89. ---
  90. # My Skill
  91. ## When to Use This Skill
  92. Use this skill when you need to...
  93. ## Instructions
  94. 1. Step 1
  95. 2. Step 2
  96. ```
  97. `name` (max 64 chars, lowercase letters, numbers and hyphens; it must match the directory) and
  98. `description` (max 1024 chars) are the fields the runtime acts on. Other frontmatter is accepted but
  99. inert — including behavioural fields such as `allowed-tools`, which do **not** restrict anything
  100. here. See
  101. [Creating Skills](https://dougtrajano.github.io/pydantic-ai-skills/creating-skills/).
  102. ## Beyond the Filesystem
  103. - **[Programmatic skills](https://dougtrajano.github.io/pydantic-ai-skills/programmatic-skills/)** — define skills in Python with decorators or dataclasses.
  104. - **[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).
  105. - **[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`.
  106. - **[Sandboxing](https://dougtrajano.github.io/pydantic-ai-skills/sandbox/)** — run a skill's scripts in a container or virtual filesystem instead of on the host.
  107. - **[Advanced features](https://dougtrajano.github.io/pydantic-ai-skills/advanced/)** — custom script executors, `${SKILL_DIR}` resolution, and rebuild strategies.
  108. ## Security
  109. Only use skills from sources you trust. Skills give agents new capabilities through instructions and
  110. code, so a malicious skill can direct an agent to invoke tools or execute code in ways that don't
  111. match its stated purpose — with risks including data exfiltration and unauthorized system access.
  112. Audit any skill from an unknown source before use. See
  113. [Security & Deployment](https://dougtrajano.github.io/pydantic-ai-skills/security/).
  114. ## Related Resources
  115. - [Agent Skills Specification](https://agentskills.io/specification)
  116. - [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)
  117. - [Agent Skills Cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/skills)
  118. - [Pydantic AI Documentation](https://ai.pydantic.dev/)
  119. ## Contributing
  120. Contributions are welcome — see [Contributing](https://dougtrajano.github.io/pydantic-ai-skills/contributing/).
  121. ## Acknowledgments
  122. Thanks to **Anthropic** for the [Agent Skills](https://agentskills.io/home) open format, the
  123. **Pydantic AI team** for the framework, and the **community** for feedback and contributions.
  124. This project was highly inspired by [pydantic-deepagents](https://github.com/vstorm-co/pydantic-deepagents),
  125. which provided foundational ideas and patterns for agent skills and progressive disclosure in Pydantic AI.
  126. ## License
  127. MIT License — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.