diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 8c425c7..4a5ce64 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -84,6 +84,7 @@
       ],
       "skills": [
         "./skills/tools-and-apis/policyengine-api-skill",
+        "./skills/tools-and-apis/policyengine-api-v2-skill",
         "./skills/tools-and-apis/policyengine-core-skill",
         "./skills/domain-knowledge/policyengine-us-skill",
         "./skills/domain-knowledge/policyengine-uk-skill",
@@ -194,6 +195,7 @@
         "./skills/domain-knowledge/policyengine-us-skill",
         "./skills/domain-knowledge/policyengine-uk-skill",
         "./skills/tools-and-apis/policyengine-api-skill",
+        "./skills/tools-and-apis/policyengine-api-v2-skill",
         "./skills/tools-and-apis/policyengine-app-skill",
         "./skills/analysis/policyengine-analysis-skill",
         "./skills/technical-patterns/policyengine-aggregation-skill",
diff --git a/changelog_entry.yaml b/changelog_entry.yaml
index ebe6f77..33ad09b 100644
--- a/changelog_entry.yaml
+++ b/changelog_entry.yaml
@@ -1,4 +1,4 @@
-- bump: patch
+- bump: minor
   changes:
-    changed:
-      - Add critical warning against mixing adds/subtracts with custom formulas in implementation patterns skill
+    added:
+      - Add policyengine-api-v2-skill for working with the next-generation microservices API
diff --git a/skills/tools-and-apis/policyengine-api-v2-skill/SKILL.md b/skills/tools-and-apis/policyengine-api-v2-skill/SKILL.md
new file mode 100644
index 0000000..7aa5058
--- /dev/null
+++ b/skills/tools-and-apis/policyengine-api-v2-skill/SKILL.md
@@ -0,0 +1,348 @@
+---
+name: policyengine-api-v2
+description: PolicyEngine API v2 - Next-generation microservices architecture with monorepo structure
+---
+
+# PolicyEngine API v2
+
+The next-generation PolicyEngine API is a monorepo containing multiple microservices built with modern Python tooling.
+
+## For Users 👥
+
+### What is API v2?
+
+API v2 is the next generation of the PolicyEngine API, currently in active development. When complete, it will replace the current Flask API with a more scalable, maintainable microservices architecture.
+
+**Status:** 🚧 Active development (not yet in production)
+
+**Key improvements over v1:**
+- Microservices architecture for better scalability
+- Modern Python tooling (Python 3.13+, uv package manager)
+- Docker-based development and deployment
+- Auto-generated OpenAPI specs and clients
+- Supabase for database management
+
+## For Analysts 📊
+
+### When to Use v2
+
+Currently, analysts should continue using the v1 API at `https://api.policyengine.org`.
+
+API v2 is not yet ready for production use. Check the repository README for the latest status.
+
+## For Contributors 💻
+
+### Repository
+
+**Location:** PolicyEngine/policyengine-api-v2
+
+**Clone:**
+```bash
+git clone https://github.com/PolicyEngine/policyengine-api-v2
+cd policyengine-api-v2
+```
+
+### Architecture Overview
+
+API v2 is a **monorepo** containing multiple microservices:
+
+**To see current structure:**
+```bash
+tree -L 2 .
+
+# Expected structure:
+# ├── api-full/        - Main API (port 8081)
+# ├── api-simulation/  - Economic simulation (port 8082)
+# ├── api-tagger/      - Deployment management (port 8083)
+# ├── docker-compose.yml
+# └── shared/          - Shared utilities
+```
+
+### Microservices
+
+**1. api-full (port 8081)**
+- Main API service
+- Household calculations
+- Policy management
+- Most endpoints from v1
+
+**2. api-simulation (port 8082)**
+- Economic simulation engine
+- Population-wide impact calculations
+- Resource-intensive operations
+
+**3. api-tagger (port 8083)**
+- Deployment management
+- Version tagging
+- Release coordination
+
+### Technology Stack
+
+**To see current dependencies:**
+```bash
+# Check pyproject.toml in each service
+cat api-full/pyproject.toml
+cat api-simulation/pyproject.toml
+cat api-tagger/pyproject.toml
+```
+
+**Key technologies:**
+- **Python 3.13+** - Latest Python version
+- **uv** - Fast Python package manager
+- **Docker + Docker Compose** - Local development and deployment
+- **Supabase** - PostgreSQL database with auth
+- **OpenAPI** - API specification generation
+- **FastAPI or Flask** - (check current implementation)
+
+### Development Setup
+
+**To start all services locally:**
+```bash
+# See current docker-compose setup
+cat docker-compose.yml
+
+# Start services
+docker-compose up
+
+# Services should be available at:
+# - http://localhost:8081 (api-full)
+# - http://localhost:8082 (api-simulation)
+# - http://localhost:8083 (api-tagger)
+```
+
+**Alternative: Run individual service:**
+```bash
+cd api-full
+uv pip install -e .
+python main.py  # or whatever the entry point is
+```
+
+### Package Management with uv
+
+API v2 uses `uv` instead of `pip` for faster dependency management:
+
+**To see current uv usage:**
+```bash
+# Check if uv is used
+cat pyproject.toml | grep -A 5 "tool.uv"
+
+# Or check for uv.lock files
+find . -name "uv.lock"
+```
+
+**Common uv commands:**
+```bash
+# Install dependencies
+uv pip install -e .
+
+# Add a dependency
+uv add package-name
+
+# Sync dependencies
+uv sync
+```
+
+### Supabase Integration
+
+**To see current Supabase setup:**
+```bash
+# Check for Supabase configuration
+cat .env.example | grep SUPABASE
+grep -r "supabase" . --include="*.py" | head -10
+
+# Supabase client initialization
+grep -r "create_client" . --include="*.py"
+```
+
+**Common patterns:**
+```python
+# Example (check actual implementation)
+from supabase import create_client
+
+supabase = create_client(supabase_url, supabase_key)
+
+# Query
+result = supabase.table('policies').select('*').execute()
+
+# Insert
+supabase.table('policies').insert({'data': policy}).execute()
+```
+
+### Design Tokens Integration
+
+API v2 may integrate with design tokens from `policyengine-app-v2`:
+
+**To check design token usage:**
+```bash
+# Look for design token imports
+grep -r "design.*token\|designTokens" . --include="*.py"
+grep -r "@policyengine/design" package.json
+
+# Check if tokens are in dependencies
+cat package.json | grep -A 5 "dependencies"
+```
+
+**If using npm design tokens:**
+```bash
+# Design tokens from app-v2
+npm install @policyengine/design-tokens
+```
+
+### OpenAPI Specification
+
+**To see current API spec generation:**
+```bash
+# Look for OpenAPI/Swagger setup
+grep -r "openapi\|swagger" . --include="*.py"
+
+# Check for spec files
+find . -name "openapi*.json" -o -name "openapi*.yaml"
+
+# If using FastAPI, specs auto-generated at /docs
+```
+
+### Testing
+
+**To see current test setup:**
+```bash
+ls -la tests/
+cat pytest.ini  # or pyproject.toml for pytest config
+```
+
+**Run tests:**
+```bash
+# All services
+pytest
+
+# Specific service
+cd api-full && pytest
+
+# With docker-compose
+docker-compose run api-full pytest
+```
+
+### Migration from v1
+
+**Key architectural differences:**
+
+| Aspect | v1 (Flask monolith) | v2 (Microservices) |
+|--------|---------------------|-------------------|
+| Structure | Single Flask app | Multiple services |
+| Database | Redis + Cloud SQL | Supabase (PostgreSQL) |
+| Deployment | Google App Engine | Docker containers |
+| Package manager | pip | uv |
+| Python version | 3.9+ | 3.13+ |
+
+**To understand migration patterns:**
+```bash
+# Compare endpoint implementations
+# v1: policyengine-api/policyengine_api/endpoints/
+# v2: api-full/endpoints/ (or similar)
+
+# See what's been ported
+git log --grep="migrate\|port" --oneline
+```
+
+### Common Development Tasks
+
+**Task 1: Add New Endpoint to api-full**
+
+1. **Find current endpoint pattern:**
+   ```bash
+   # Look at existing endpoints
+   ls api-full/endpoints/  # or api-full/routes/
+   cat api-full/endpoints/example.py
+   ```
+
+2. **Follow the pattern** (likely FastAPI or Flask)
+
+3. **Update OpenAPI spec** (may be auto-generated)
+
+4. **Add tests:**
+   ```bash
+   cat tests/test_endpoints.py
+   ```
+
+**Task 2: Work with Supabase**
+
+```bash
+# See current database schema
+cat supabase/migrations/*.sql  # if using migrations
+
+# Test database locally
+docker-compose up supabase  # if in docker-compose
+```
+
+**Task 3: Use Design Tokens**
+
+```bash
+# Check if design tokens are integrated
+grep -r "design.*token" .
+
+# If using from app-v2, import them:
+# (Actual implementation depends on current setup)
+```
+
+### Environment Variables
+
+**To see required environment variables:**
+```bash
+cat .env.example
+
+# Common variables:
+# - SUPABASE_URL
+# - SUPABASE_KEY
+# - DATABASE_URL
+# - API_PORT (8081, 8082, 8083)
+```
+
+### Monorepo Best Practices
+
+**To see current monorepo structure:**
+```bash
+# List all services
+ls -d */
+
+# Check for shared code
+ls shared/ common/ lib/  # (if exists)
+
+# See inter-service dependencies
+grep -r "../api-" pyproject.toml
+```
+
+**Pattern:**
+- Each service should be independently deployable
+- Shared code goes in `shared/` or similar
+- Each service has its own tests
+- Docker Compose for local multi-service development
+
+## Related Skills
+
+- **policyengine-api-skill** - v1 API patterns (for migration reference)
+- **policyengine-core-skill** - Understanding the simulation engine
+- **policyengine-us-skill** - Country model integration
+- **policyengine-design-skill** - Design tokens and branding
+- **policyengine-standards-skill** - Code quality standards
+
+## Resources
+
+**Repository:** https://github.com/PolicyEngine/policyengine-api-v2
+
+**Related:**
+- v1 API: https://github.com/PolicyEngine/policyengine-api
+- App v2 (design tokens): https://github.com/PolicyEngine/policyengine-app-v2
+- Supabase: https://supabase.com/docs
+
+## Development Status
+
+⚠️ **Important:** API v2 is in active development. Always check the repository README for:
+- Current status and roadmap
+- Breaking changes
+- Migration timeline from v1
+- Deployment instructions
+
+**To see current status:**
+```bash
+cat README.md
+git log -10 --oneline
+```