The ofauth-v2-to-v3-migration skill teaches a coding agent, such as Claude Code, Codex, or Cursor, how to move your codebase from V2 to V3. It follows the migration guide and the V3 reference.
The skill changes your code only. You still run the organization migration in the OFAuth dashboard.
What the agent does
- Finds V2 usage. It searches for API keys (
sk_live_..., sk_test_..., sk_sandbox_...), api.ofauth.com/v2 calls and the raw access proxy, x-connection-id, Link embed and /v2/link/init, /v2/account*, /v2/vault-plus, V2 SDKs, and webhook receivers that read svix-* headers.
- Plans the changes. It maps each use to a V3 operation and scope, and lists V2 routes that have no V3 operation yet and features V3 removes. It shows you the plan before large edits.
- Rewrites the integration. OAuth with PKCE at
https://auth.ofauth.com/link/authorize, the token endpoint with client_secret_basic, refresh tokens stored for each linked_account_id, /v3/access/* with x-linked-account-id, /v3/vault-plus/*, /v3/linked-accounts, Standard Webhooks headers, lifecycle events, and V3 error recovery.
- Builds the account bundle import. A script that imports the one-time account bundle after cutover. It stores each new refresh token and can safely run again.
- Verifies. It runs your tests, checks that no V2 calls remain, and walks you through the Test rehearsal, the Live token request, and the cutover-day steps.
Install the skill
The skill is a folder of plain Markdown files: SKILL.md and a references/ folder. It is published at https://ofauth.com/skills/ofauth-v2-to-v3-migration/, and files.txt in that folder lists every file. Run the install command from your repository root.
Claude Code
Codex and others
Cursor
Claude Code loads skills from .claude/skills/. To use the skill in every project, set dir=~/.claude/skills/ofauth-v2-to-v3-migration instead. Codex and other agents that support Agent Skills load skills from .agents/skills/. If your agent does not load skills, add this line to your AGENTS.md: Download the files with the Codex and others command, then add a rule at .cursor/rules/ofauth-v2-to-v3-migration.mdc: Start the migration
Open your agent in the repository and paste:
Plan for the steps only you can do:
- Run the organization migration in the dashboard, review the Live callbacks, and save the Live client secret.
- Fill in the client IDs, client secrets, and webhook secret in your configuration.
- Run the Test rehearsal and the Live token request.
- After cutover, download the account bundle and run the import.
Safety
The account bundle holds one refresh token for each migrated account. Treat it like your client secret: never commit it, paste it into an agent chat, or share it. Run the import yourself, then delete the file. If you lose it, an owner can regenerate it, which revokes every token from the previous bundle.
- Review every diff before you merge. Pay most attention to token storage, the OAuth callback, and webhook verification.
- Keep secrets in your secret manager or environment, not in code, fixtures, or prompts.
- Run the full test suite and rehearse in Test before you schedule cutover.
- If your app uses a V2 route with no V3 operation, or a raw proxy path, contact support@ofauth.com with the path before you schedule cutover.
