pydantic-ai-skills
AGENTS.md381 starsChanged 19 days agoMITView on GitHub
pydantic-ai-skills adds remote skill registries and bundled-file execution to Pydantic AI Agent Skills. It builds on pydantic-ai-harness, which owns SKILL.md discovery, validation and instruction rendering. CLAUDE.md is a symlink to this file — edit this one. Python library (>=3.10) that complements harness's Skills capability rather than reimplementing it. What this package owns: Git/S3 registries and their composition, the bundled references//scripts/ layer, sandboxed script execution, ${SKILL_DIR} resolution, and skills defined in Python. If a change would duplicate something harness already does,…
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
- sonarqubeSkill
The file
We split this AGENTS.md into the rules it gives an agent
8 rules. About 0 are common, 6 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 11
If a change would duplicate something harness already does, it belongs upstream, not here.
- Distinctive: line 13
Keep this file to agent-critical defaults.
- Very specific: line 57
Every tool function registered in _toolset.py takes ctx: RunContext[Any] as its first parameter.
- Distinctive: line 60
Do not regress path-traversal and symlink checks in indexing, staging, or download paths.
- Very specific: line 63
Never write executor or LocalSkillScriptExecutor() — use is None.
- Distinctive: line 71
Prefer small, surgical diffs.
- Distinctive: line 73
Add or update tests in tests/ for any behavior change.
- Distinctive: line 74
If the request is ambiguous or a simpler approach exists, say so before implementing.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
pydantic-ai-skills adds remote skill registries and bundled-file execution to Pydantic AI Agent Skills. It builds on pydantic-ai-harness, which owns SKILL.md discovery, validation and instruction rendering.
This file provides guidance to coding agents (Claude Code, etc.) when working with code in this repository. CLAUDE.md is a symlink to this file — edit this one.
Scope
Python library (>=3.10) that complements harness's Skills capability rather than reimplementing it. What this package owns: Git/S3 registries and their composition, the bundled references//scripts/ layer, sandboxed script execution, ${SKILL_DIR} resolution, and skills defined in Python.
If a change would duplicate something harness already does, it belongs upstream, not here.
Keep this file to agent-critical defaults. Task-specific detail belongs in docs/ (see Link, Don't Duplicate).
Commands
pip install -e ".[test,git,s3,dev]" # full dev install
pytest # all tests (coverage is on by default via pytest.ini)
pytest tests/test_capability.py -v # one file
pytest tests/test_capability.py::test_name -v # one test
pytest -m "not slow" # skip slow markers
pre-commit run --all-files # what CI's lint job runs: ruff + ruff-format + mypy
ruff check pydantic_ai_skills/ && ruff format pydantic_ai_skills/
mkdocs serve # docs, needs pip install -e ".[docs]"pytest.ini sets asyncio_mode = auto — do not add @pytest.mark.asyncio.
Architecture
Layers, in dependency order:
| Module | Role |
| types.py | Skill, SkillResource, SkillScript, SkillWrapper, the @skill decorator; name normalization |
| _parsing.py | Minimal frontmatter reading — only what runs before harness sees a library |
| packages.py | index_libraries, SkillPackage — the bundled-file index |
| local.py | Script execution via AnyIO subprocess; file-backed resources/scripts |
| registries/ | SkillRegistry ABC + Git/S3/Local sources + composition wrappers (filtered/prefixed/renamed/combined) |
| _toolset.py | SkillFilesToolset — the two model-facing tools |
| capability.py | SkillsCapability — the composite over harness's Skills |
The two tools exposed to the model: read_skill_resource, run_skill_script. Loading a skill's instructions is Pydantic AI's own load_capability, not something this package registers.
Invariants to preserve:
- harness owns levels 1 and 2.
SkillsCapabilityconstructspydantic_ai_harness.Skillsand re-emits its leaves — during construction before harness 0.52, and fromfor_run(per run, reading aLocalWorkspaceBackend, never the run's workspace) from 0.52. Never let the undecomposedSkills(idskills) into the treeapplyyields. Never reimplementSKILL.mdparsing, validation, naming, or the catalog, and never import frompydantic_ai_harness.skills._loader— only the publicSkillssurface, pinned by tests/test_harness_compat.py. get_toolset()must stay on the capability, not on a leaf. pydantic-ai collects toolsets from a container's direct children (CombinedCapability.get_toolset) and does not recurse throughapply(). A toolset parked on a leaf is silently never registered.apply()must visitselfwhen a toolset is contributed. The run's capability registry is built fromapply(), andCapabilityOwnedToolsetraises at first tool call if the owner is missing from it.- Discovery mirrors harness exactly — immediate children of a library containing
SKILL.md.index_librariesand harness must never disagree about what a skill is, or the file tools cannot find packages for skills on the catalog. - Skill source priority is programmatic > directories/registries. A programmatic skill shadowing a directory-backed one wins with a
UserWarning, and the harness leaf is dropped so no duplicate capability id reaches the run. - Registries return directories, not
Skillobjects.sync()is the whole contract; anything that parses aSKILL.mdin a registry is a smell.
Conventions and Pitfalls
- Every tool function registered in _toolset.py takes
ctx: RunContext[Any]as its first parameter. - Single-quoted strings, line length 120, Google-style docstrings (Ruff enforces;
D100/D102/D104/D105/D107are ignored — see pyproject.toml). Test functions need docstrings too (D103applies totests/). - Skill names:
lowercase-with-hyphens, max 64 chars, no consecutive or leading/trailing hyphens._parsing.validate_skill_namemirrors harness's rule — keep the two in step. - Do not regress path-traversal and symlink checks in indexing, staging, or download paths.
- Script discovery covers supported extensions and any executable file — not Python only.
- AnyIO process stream readers must handle
anyio.EndOfStreamexplicitly. - Never write
executor or LocalSkillScriptExecutor()— useis None. A falsey custom executor (a pool that is empty at index time) must not silently fall back to running untrusted scripts on the host. - This package imports private pydantic-ai symbols (
pydantic_ai._function_schema,_griffe,_utils). tests/test_pydantic_ai_compat.py exists so an upstream move fails loudly — keep it in sync with what the code actually imports. tests/test_harness_compat.py plays the same role for harness, which is on 0.x and documents that its API may change between minor releases. - CI runs Python 3.10–3.14 against a floor/latest pair of
pydantic-ai-harness+pydantic-ai-slim. New code must work against the floor (pydantic-ai-harness>=0.28,pydantic-ai-slim>=2.38), not just latest. The two move together because harness sets a slim floor of its own. gitpython([git]) andboto3([s3]) are optional extras — import them lazily and raise a clearImportErrornaming the extra, as registries/s3.py does.TestModeldoes not work with deferred capabilities: it callsload_capabilitywith a synthesized id and exhausts the retry budget. UseFunctionModelto script tool calls.
Working Style
- Prefer small, surgical diffs. Every changed line should trace to the request; don't refactor or reformat adjacent code, and mention unrelated dead code rather than deleting it.
- Match surrounding style in pydantic_ai_skills/ even where you'd write it differently.
- Add or update tests in tests/ for any behavior change.
- If the request is ambiguous or a simpler approach exists, say so before implementing.
Link, Don't Duplicate
- Concepts and the division of labour with harness: docs/concepts.md
- How this compares to harness alone: docs/comparison.md
- Creating filesystem skills: docs/creating-skills.md
- Programmatic skills: docs/programmatic-skills.md
- Registries and composition: docs/registries.md
- Security model: docs/security.md
- Advanced patterns: docs/advanced.md
- v1 → v2 migration: docs/migration-v2.md
- Contribution workflow: docs/contributing.md
- API reference: docs/api/
External:
- Pydantic AI integration details: https://ai.pydantic.dev/llms.txt
- pydantic-ai-harness Skills: https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/skills
- Agent Skills specification: https://agentskills.io/home
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

