skyvern (Agent Skills)

# Skyvern Agent Guide
This AGENTS.md file provides comprehensive guidance for AI agents working with the Skyvern codebase. Follow these guidelines to ensure consistency and quality in all contributions.

## Project Structure for Agent Navigation

- `/skyvern`: Main Python package
  - `/cli`: Command-line interface components
  - `/client`: Client implementations and integrations
  - `/forge`: Core automation logic and workflows
  - `/library`: Shared utilities and helpers
  - `/schemas`: Data models and validation schemas
  - `/services`: Business logic and service layers
  - `/utils`: Common utility functions
  - `/webeye`: Web interaction and browser automation
- `/skyvern-frontend`: Frontend application
- `/integrations`: Third-party service integrations
- `/alembic`: Database migrations
- `/scripts`: Utility and deployment scripts

## Coding Conventions for Agents

### Python Standards

- Use Python 3.11+ features and type hints
- Follow PEP 8 with a line length of 100 characters
- Use absolute imports for all modules
- Document all public functions and classes with Google-style docstrings
- Use `snake_case` for variables and functions, `PascalCase` for classes

### Asynchronous Programming

- Prefer async/await over callbacks
- Use `asyncio` for concurrency
- Always handle exceptions in async code
- Use context managers for resource cleanup

### Error Handling

- Use specific exception classes
- Include meaningful error messages
- Log errors with appropriate severity levels
- Never expose sensitive information in error messages

## Pull Request Process

1. **Branch Naming**
   - `feature/descriptive-name` for new features
   - `fix/issue-description` for bug fixes
   - `chore/task-description` for maintenance tasks

2. **PR Guidelines**
   - Reference related issues with `Fixes #123` or `Closes #123`
   - Include a clear description of changes
   - Update relevant documentation
   - Ensure all tests pass
   - Get at least one approval before merging

3. **Commit Message Format**
   ```
   [Component] Action: Brief description
   
   More detailed explanation if needed.
   
   - Bullet points for additional context
   - Reference issues with #123
   ```

## Code Quality Checks

Before submitting code, run:
```bash
pre-commit run --all-files
```

## Performance Considerations
- Optimize database queries
- Use appropriate data structures
- Implement caching where beneficial
- Monitor memory usage

## Security Best Practices
- Never commit secrets or credentials
- Validate all inputs
- Use environment variables for configuration
- Follow the principle of least privilege
- Keep dependencies updated

## Getting Help
- Check existing issues before opening new ones
- Reference relevant documentation
- Provide reproduction steps for bugs
- Be specific about the problem and expected behavior

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Python Backend Commands
- **Install dependencies**: `uv sync`
- **Run Skyvern service**: `skyvern run all` (starts both backend and UI)
- **Run backend only**: `skyvern run server`
- **Run UI only**: `skyvern run ui`
- **Check status**: `skyvern status`
- **Stop services**: `skyvern stop all`
- **Quickstart**: `skyvern quickstart` (for first-time setup with DB migrations)

### Code Quality & Testing
- **Lint**: `ruff check` and `ruff format`
- **Type checking**: `mypy skyvern`
- **Run tests**: `pytest tests/`
- **Pre-commit hooks**: `pre-commit run --all-files`

### Frontend Commands (in skyvern-frontend/)
- **Install dependencies**: `npm install`
- **Development**: `npm run dev`
- **Build**: `npm run build`
- **Lint**: `npm run lint`
- **Format**: `npm run format`

### Database Management
- **Run migrations**: `alembic upgrade head`
- **Create migration**: `alembic revision --autogenerate -m "description"`

## Architecture Overview

Skyvern is a browser automation platform that uses LLMs and computer vision to interact with websites. The architecture consists of:

### Core Components
- **Agent System** (`skyvern/forge/agent.py`): LLM-powered agent loop for web navigation and task execution
- **Public Library** (`skyvern/library/`): User-facing `from skyvern import Skyvern` interface and SDK-style page/browser/locator wrappers
- **Browser Engine** (`skyvern/webeye/`): Playwright-based browser automation with computer vision
- **Workflow Engine** (`skyvern/services/`): Orchestrates complex multi-step workflows
- **API Layer** (`skyvern/forge/`): FastAPI-based REST API and WebSocket support

### Key Directories
- `skyvern/forge/agent.py` + `skyvern/forge/agent_functions.py`: LLM-powered agent loop for web interaction
- `skyvern/library/`: Public `Skyvern` class and library-facing SDK wrappers
- `skyvern/webeye/`: Browser automation, DOM scraping, action execution
- `skyvern/forge/`: FastAPI server, API endpoints, request handling
- `skyvern/forge/sdk/`: Internal SDK — DB, routes, schemas, workflow, copilot, executor, cache
- `skyvern/services/`: Business logic for tasks, workflows, and browser sessions
- `skyvern/cli/`: Command-line interface
- `skyvern/client/`: Generated Python client SDK
- `skyvern-frontend/`: React-based UI for task management and monitoring
- `alembic/`: Database migrations

### Workflow System
- **Blocks**: Modular components (navigation, extraction, validation, loops, etc.)
- **Parameters**: Dynamic values passed between blocks
- **Runs**: Execution instances of workflows
- **Browser Sessions**: Persistent browser state across workflow steps

### Data Flow
1. User creates tasks/workflows via UI or API
2. Agent system plans actions using LLM analysis of screenshots
3. Browser engine executes actions via Playwright
4. Results are captured, processed, and stored
5. Workflow orchestrator manages multi-step sequences

## Development Notes

### Environment Setup
- Requires Python 3.11+ and Node.js
- Uses UV for Python dependency management
- PostgreSQL database (managed via Docker or local install)
- Browser dependencies installed via Playwright

### LLM Configuration
Configure via environment variables or the interactive `skyvern init` wizard:
- Supports OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Gemini, Ollama
- Uses `LLM_KEY` to specify which model to use
- `SECONDARY_LLM_KEY` for lightweight agent operations

### Testing Strategy
- Unit tests in `tests/unit_tests/`
- Integration tests require browser automation setup
- Use `pytest` with async support for testing

### Code Style
- Python: Ruff for linting and formatting (configured in pyproject.toml)
- TypeScript: ESLint + Prettier (configured in skyvern-frontend/)
- Line length: 120 characters
- Use type hints and async/await patterns