pydantic-ai-common-pitfalls
Avoid common mistakes and debug issues in PydanticAI agents. Use when encountering errors, unexpected behavior, or when reviewing agent implementations.
Install via CLI (Recommended)
clawhub install openclaw/skills/skills/anderskev/pydantic-ai-common-pitfallsWhat This Skill Does
The pydantic-ai-common-pitfalls skill acts as a diagnostic and reference engine for developers building AI agents with PydanticAI. It provides expert-level pattern matching to identify frequent architectural mistakes, such as improper tool decorator usage, incorrectly ordered RunContext parameters, and Pydantic dependency injection failures. By using this skill, developers can reduce debugging time for common 'UserError' messages and ensure their agent implementations adhere to the official PydanticAI library specifications.
Installation
To integrate this skill into your environment, run the following command in your terminal:
clawhub install openclaw/skills/skills/anderskev/pydantic-ai-common-pitfalls
Use Cases
This skill is best utilized during the iterative development phase of an AI agent. Use it when:
- You receive a
UserErrorregarding tool signature mismatch orRunContextissues. - You are troubleshooting agent crashes that occur during the
agent.run_syncoragent.runexecution lifecycle due to missing dependencies. - You are refactoring existing code to transition from standard functions to decorated tools.
- You need to verify if your custom tool registration pattern is valid under the current version of PydanticAI.
Example Prompts
- 'I am getting a UserError saying RunContext annotations can only be used with tools that take context. Can you check my tool implementation?'
- 'Why is my agent failing when I try to run it with deps? Here is the code snippet for my Agent instantiation.'
- 'Help me debug this error: First parameter of tools that take context must be annotated with RunContext.'
Tips & Limitations
This skill is designed as an analytical tool. When using it, always provide the specific snippet of code causing the issue, including the Agent definition and the relevant tool function signatures. Note that while this skill covers core PydanticAI pitfalls, it cannot diagnose runtime logic errors or issues external to the PydanticAI framework. Always ensure your environment uses compatible versions of Pydantic and PydanticAI, as breaking changes in the framework may render some diagnostic patterns obsolete. Always favor official documentation if the agent's suggestion conflicts with the latest release notes.
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-anderskev-pydantic-ai-common-pitfalls": {
"enabled": true,
"auto_update": true
}
}
}Tags(AI)
Flags: code-execution
Related Skills
explanation-docs
Explanation documentation patterns for understanding-oriented content - conceptual guides that explain why things work the way they do
tutorial-docs
Tutorial patterns for documentation - learning-oriented guides that teach through guided doing
pytest-code-review
Reviews pytest test code for async patterns, fixtures, parametrize, and mocking. Use when reviewing test_*.py files, checking async test functions, fixture usage, or mock patterns.
reference-docs
Reference documentation patterns for API and symbol documentation. Use when writing reference docs, API docs, parameter tables, or technical specifications. Triggers on reference docs, API reference, function reference, parameters table, symbol documentation.
serde-code-review
Reviews serde serialization code for derive patterns, enum representations, custom implementations, and common serialization bugs. Use when reviewing Rust code that uses serde, serde_json, toml, or any serde-based serialization format. Covers attribute macros, field renaming, and format-specific pitfalls.