Pydantic AI Skills

Production-ready Claude Code configuration for Python development.

Agents, skills, hooks, commands, and rules optimized for Python/FastAPI projects with uv, ruff, mypy, and pytest.

New to this plugin? Check out the Getting Started Guide with step-by-step tutorials.

---

Quick Start

Option 1: Install as Plugin (Recommended)

# Add this repo as a marketplace
/plugin marketplace add Fuenfgeld/pydantic-ai-skills

# Install the plugin
/plugin install pydantic-ai-skills@pydantic-ai-skills

Option 2: Manual Installation

git clone https://github.com/Fuenfgeld/pydantic-ai-skills.git
cd pydantic-ai-skills

# Copy to your Claude config
cp -r agents skills commands rules ~/.claude/

---

What's Inside

pydantic-ai-skills/
|-- .claude-plugin/          # Plugin metadata
|-- agents/                  # Specialized subagents
|   |-- tdd-guide.md               # pytest TDD workflow
|   |-- build-error-resolver.md    # mypy/ruff error fixing
|   |-- code-reviewer.md           # Python code review
|   |-- security-reviewer.md       # bandit/safety security checks
|   |-- architect.md               # FastAPI architecture
|   |-- e2e-runner.md             # pytest + httpx E2E testing
|   |-- refactor-cleaner.md       # vulture/autoflake cleanup
|   |-- doc-updater.md            # Docstring and codemap sync
|
|-- skills/                  # Domain knowledge and patterns
|   |-- tdd-workflow/             # pytest Red-Green-Refactor
|   |-- backend-patterns/         # FastAPI, SQLAlchemy, Pydantic
|   |-- coding-standards/         # PEP 8, type hints, ruff
|   |-- fastapi-patterns/         # Routers, dependencies, middleware
|   |-- pydantic-validation/      # Pydantic v2 patterns
|   |-- sqlalchemy-patterns/      # SQLAlchemy 2.0 async
|   |-- async-python/             # asyncio patterns
|   |-- security-review/          # Python security
|   |-- verification-loop/        # Continuous verification
|
|-- commands/                # Slash commands
|   |-- tdd.md                    # /tdd - Test-driven development
|   |-- build-fix.md              # /build-fix - Fix mypy/ruff errors
|   |-- test-coverage.md          # /test-coverage - pytest-cov
|   |-- e2e.md                    # /e2e - E2E test generation
|   |-- refactor-clean.md         # /refactor-clean - Dead code removal
|   |-- setup-pm.md               # /setup-pm - Package manager setup
|
|-- rules/                   # Always-follow guidelines
|   |-- coding-style.md           # PEP 8, type hints
|   |-- testing.md               # pytest, 80% coverage
|   |-- security.md              # Python security
|   |-- patterns.md              # FastAPI patterns
|
|-- hooks/                   # Event-based automations
|   |-- hooks.json               # All hooks configuration
|
|-- scripts/                 # Python utilities
|   |-- lib/                      # Shared libraries
|   |   |-- package_manager.py    # Package manager detection
|   |   |-- utils.py              # File and path utilities
|   |-- hooks/                    # Hook implementations
|   |   |-- session_start.py      # Load context on session start
|   |   |-- session_end.py        # Save state on session end
|   |   |-- pre_compact.py        # Pre-compaction state saving
|   |   |-- suggest_compact.py    # Strategic compaction
|   |   |-- evaluate_session.py   # Pattern extraction
|   |-- setup_package_manager.py  # Interactive PM setup
|
|-- tests/                   # Test suite
|   |-- scripts/                  # Script tests

---

Package Manager Support

The plugin automatically detects your Python package manager:

Manager	Lock File	Detection Priority
uv (default)	uv.lock	1st
poetry	poetry.lock	2nd
pdm	pdm.lock	3rd
pipenv	Pipfile.lock	4th
pip	requirements.txt	5th
conda	environment.yml	6th

Configure Package Manager

# Interactive setup
python scripts/setup_package_manager.py

# Or use the command
/setup-pm

---

Key Features

Hooks

Auto-format on edit:

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.py$\"",
  "hooks": [{
    "type": "command",
    "command": "ruff format \"$file_path\""
  }]
}

Type check on edit:

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.py$\"",
  "hooks": [{
    "type": "command",
    "command": "mypy --no-error-summary \"$file_path\""
  }]
}

Block print() statements:

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.py$\"",
  "hooks": [{
    "type": "command",
    "command": "grep -n 'print(' \"$file_path\" && echo '[Hook] Use logging instead'"
  }]
}

Commands

Command	Description
/tdd	Start pytest TDD workflow
/build-fix	Fix mypy/ruff errors
/test-coverage	Run pytest-cov and improve coverage
/e2e	Generate E2E tests with httpx
/refactor-clean	Remove dead code with vulture
/setup-pm	Configure package manager
/code-review	Python code quality review

Agents

Agent	Purpose
tdd-guide	pytest TDD with fixtures and parametrize
build-error-resolver	Fix mypy type errors, ruff violations
code-reviewer	PEP 8, security, best practices
security-reviewer	bandit, safety, pip-audit
architect	FastAPI architecture, repository pattern
e2e-runner	pytest + httpx API testing

---

Python Tooling

ruff (Linting + Formatting)

# pyproject.toml
[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM"]

[tool.ruff.format]
quote-style = "double"

mypy (Type Checking)

[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
disallow_untyped_defs = true

pytest (Testing)

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"
addopts = "-v --tb=short"

[tool.coverage.run]
source = ["src"]
branch = true

---

Example FastAPI Pattern

# src/api/routes/users.py
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.ext.asyncio import AsyncSession

from src.core.deps import get_db
from src.models.user import User
from src.schemas.user import UserCreate, UserResponse
from src.services.user_service import UserService

router = APIRouter(prefix="/users", tags=["users"])


@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
async def create_user(
    user_data: UserCreate,
    db: AsyncSession = Depends(get_db),
) -> User:
    """Create a new user."""
    service = UserService(db)
    return await service.create(user_data)

---

Running Tests

# Run all tests
uv run pytest tests/ -v

# With coverage
uv run pytest tests/ --cov=src --cov-report=html

# Run script tests
uv run pytest tests/scripts/ -v

---

Context Window Management

Important: Don't enable all MCPs at once. Keep under 10 enabled per project.

{
  "disabledMcpServers": ["vercel", "cloudflare-*"]
}

---

Contributing

Contributions welcome! See CONTRIBUTING.md.

Ideas for Contributions

• Django/Flask agents and skills
• ML/data engineering patterns
• Cloud deployment skills (AWS, GCP)
• Database-specific patterns (PostgreSQL, Redis)

---

Links

• This Repo: Fuenfgeld/pydantic-ai-skills
• Based on: affaan-m/everything-claude-code

---

License

MIT - Use freely, modify as needed, contribute back if you can.