agentleFS
DougTrajanoDougTrajano/pydantic-ai-skills/AGENTS.md

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.

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
  1. Distinctive:

    If a change would duplicate something harness already does, it belongs upstream, not here.

    line 11
  2. Distinctive:

    Keep this file to agent-critical defaults.

    line 13
  3. Very specific:

    Every tool function registered in _toolset.py takes ctx: RunContext[Any] as its first parameter.

    line 57
  4. Distinctive:

    Do not regress path-traversal and symlink checks in indexing, staging, or download paths.

    line 60
  5. Very specific:

    Never write executor or LocalSkillScriptExecutor() — use is None.

    line 63
  6. Distinctive:

    Prefer small, surgical diffs.

    line 71
  7. Distinctive:

    Add or update tests in tests/ for any behavior change.

    line 73
  8. Distinctive:

    If the request is ambiguous or a simpler approach exists, say so before implementing.

    line 74

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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:

ModuleRole
types.pySkill, SkillResource, SkillScript, SkillWrapper, the @skill decorator; name normalization
_parsing.pyMinimal frontmatter reading — only what runs before harness sees a library
packages.pyindex_libraries, SkillPackage — the bundled-file index
local.pyScript execution via AnyIO subprocess; file-backed resources/scripts
registries/SkillRegistry ABC + Git/S3/Local sources + composition wrappers (filtered/prefixed/renamed/combined)
_toolset.pySkillFilesToolset — the two model-facing tools
capability.pySkillsCapability — 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. SkillsCapability constructs pydantic_ai_harness.Skills and re-emits its leaves — during construction before harness 0.52, and from for_run (per run, reading a LocalWorkspaceBackend, never the run's workspace) from 0.52. Never let the undecomposed Skills (id skills) into the tree apply yields. Never reimplement SKILL.md parsing, validation, naming, or the catalog, and never import from pydantic_ai_harness.skills._loader — only the public Skills surface, 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 through apply(). A toolset parked on a leaf is silently never registered.
  • apply() must visit self when a toolset is contributed. The run's capability registry is built from apply(), and CapabilityOwnedToolset raises at first tool call if the owner is missing from it.
  • Discovery mirrors harness exactly — immediate children of a library containing SKILL.md. index_libraries and 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 Skill objects. sync() is the whole contract; anything that parses a SKILL.md in 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/D107 are ignored — see pyproject.toml). Test functions need docstrings too (D103 applies to tests/).
  • Skill names: lowercase-with-hyphens, max 64 chars, no consecutive or leading/trailing hyphens. _parsing.validate_skill_name mirrors 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.EndOfStream explicitly.
  • Never write executor or LocalSkillScriptExecutor() — use is 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]) and boto3 ([s3]) are optional extras — import them lazily and raise a clear ImportError naming the extra, as registries/s3.py does.
  • TestModel does not work with deferred capabilities: it calls load_capability with a synthesized id and exhausts the retry budget. Use FunctionModel to 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:

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.