pydantic-ai-common-pitfalls
Avoid common mistakes and debug issues in PydanticAI agents. Use when encountering errors, unexpected behavior, or when reviewing agent implementations.
npx skills add majiayu000/claude-skill-registry --skill pydantic-ai-common-pitfalls --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# PydanticAI Common Pitfalls and Debugging ## Tool Decorator Errors ### Wrong: RunContext in tool_plain ```python # ERROR: RunContext not allowed in tool_plain @agent.tool_plain async def bad_tool(ctx: RunContext[MyDeps]) -> str: return "oops" # UserError: RunContext annotations can only be used with tools that take context ``` **Fix**: Use `@agent.tool` if you need context: ```python @agent.tool async def good_tool(ctx: RunContext[MyDeps]) -> str: return "works" ``` ### Wrong: Missing RunContext in tool ```python # ERROR: First param must be RunContext @agent.tool def bad_tool(user_id: int) -> str: return "oops" # UserError: First parameter of tools that take context must be annotated with RunContext[...] ``` **Fix**: Add RunContext as first parameter: ```python @agent.tool def good_tool(ctx: RunContext[MyDeps], user_id: int) -> str: return "works" ``` ### Wrong: RunContext not first ```python # ERROR: RunContext must be first parameter @agent.tool def bad_tool(user_id: int, ctx: RunContext[MyDeps]) -> str: return "oops" ``` **Fix**: RunContext must always be the first parameter. ## Valid Patterns (Not Errors) ### Raw Function Tool Registration The following pattern IS valid and s
- Tool Decorator Errors
- Wrong: RunContext in toolplain
- Wrong: Missing RunContext in tool
- Wrong: RunContext not first
- Valid Patterns (Not Errors)
- Raw Function Tool Registration
- Dependency Type Mismatches
- Wrong: Missing deps at runtime
- Wrong: Wrong deps type
- Output Type Issues
- Pydantic validation fails
- Complex nested types
- Async vs Sync Mistakes
- Wrong: Calling async in sync context
What does the pydantic-ai-common-pitfalls skill do?
Avoid common mistakes and debug issues in PydanticAI agents. Use when encountering errors, unexpected behavior, or when reviewing agent implementations.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill pydantic-ai-common-pitfalls --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.