DRAFT: Add V0 to V1 API migration skill

[jpshackelford]

Summary

This PR adds a new skill to help developers migrate from the deprecated OpenHands V0 API (/api/conversations) to the new V1 API (/api/v1/*).

V0 API deprecation deadline: April 1, 2026

Features

🔍 Detection

• Regex patterns for finding V0 API calls in codebases
• grep commands for Python, TypeScript, JavaScript, and shell scripts
• Field name detection (initial_user_msg, etc.)

📋 Migration Workflow

• Step-by-step migration guidance in SKILL.md
• Code transformation examples (V0 → V1)
• Complexity categorization (Simple/Moderate/Complex)
• Endpoint mapping quick reference

📁 Test Fixtures

• V0 request/response examples
• V1 request/response examples
• mapping.json documenting breaking changes between versions

📖 Embedded OpenAPI Specs

• openapi/app-server.json - Full App Server spec (V0 + V1 endpoints)
• openapi/agent-server.json - Agent Server spec (per-sandbox API)
• Specs include metadata with retrieval date and refresh instructions

Trigger Keywords

• migrate v0 to v1
• v0 api migration
• openhands api migration
• find v0 api calls
• v0 deprecation

Directory Structure

skills/v0-v1-migration/
├── SKILL.md                    # Main skill with migration workflow
├── README.md                   # Usage documentation
├── openapi/
│   ├── app-server.json         # App Server OpenAPI (retrieved 2026-03-02)
│   └── agent-server.json       # Agent Server OpenAPI (generated 2026-03-02)
├── detection/
│   └── patterns.json           # V0 detection regex patterns
└── fixtures/
    ├── mapping.json            # V0→V1 transformation mapping
    ├── v0/                     # V0 request/response examples
    └── v1/                     # V1 request/response examples

Related

• Docs PR with migration guide: Add Narrative-First V0 to V1 Migration Guide (Alternative to #362) docs#363
• V0 deprecation tracking: V0 to V1 Migration Guide OpenHands#12578

TODO (before removing draft status)

• Review SKILL.md content for accuracy
• Add more fixtures (events, file operations, etc.)
• Add language-specific pattern docs (Python, TypeScript)
• Consider adding a detection script utility
• Test skill activation with trigger keywords

[enyst]

I think maybe these can be just links to the existing .json OpenAPI files?