Switch between AI coding agents without losing context. Portable SKILL.md-based workflow for Claude Code, Codex CLI, Gemini CLI, Cursor, and any other SKILL.md-compatible agent.
You are building a real project with an AI coding agent. You hit one of these walls:
- ⏱️ Usage limit / quota exhausted mid-task — you want to continue with another AI
- 🔁 Different AI for different strengths — Claude Code for architecture, Codex for quick scripts, Gemini CLI for Google ecosystem
- 📅 Break in work — you come back after a few days and the AI has forgotten everything
- 👥 Hand off to teammate who uses a different AI tool
Each time, you re-explain the whole project. Every switch leaks context. Progress slows.
ai-switch is a tiny, portable workflow that uses two artifacts every AI agent already understands:
PROGRESS.md— a structured file at your repo root describing current project stategit— the ground truth of what is committed
With two commands:
/ai-switch-stop # Before closing: save progress + commit
/ai-switch-start # When opening: read progress + report stateAny AI agent that supports the SKILL.md standard can read the same files and continue the work seamlessly. No vendor lock-in, no custom server, no API keys.
Agent A (Claude Code) Agent B (Codex CLI)
───────────────────── ─────────────────────
working...
↓
/ai-switch-stop
├─► updates PROGRESS.md
├─► git add -A && git commit
└─► git push (optional)
/ai-switch-start
├─► reads PROGRESS.md
├─► git log / git status
└─► reports state + waits
↓
working...
Pick the section for your AI tool. All methods install 3 skills:
ai-switch— umbrella / routingai-switch-stop— save & commit commandai-switch-start— resume & report command
Global install (all projects):
# Create skills directory if it doesn't exist
mkdir -p ~/.claude/skills
# Clone into Claude's skills folder
git clone https://github.com/quyendang/ai-switch.git /tmp/ai-switch
cp -r /tmp/ai-switch/skills/* ~/.claude/skills/
rm -rf /tmp/ai-switch
# Restart Claude Code to load the new skillsProject-only install:
# From your project root
mkdir -p .claude/skills
git clone https://github.com/quyendang/ai-switch.git /tmp/ai-switch
cp -r /tmp/ai-switch/skills/* .claude/skills/
rm -rf /tmp/ai-switch
# Commit the skills so your team gets them
git add .claude/skills
git commit -m "chore: add ai-switch skills"Verify:
In Claude Code, type / and confirm you see /ai-switch-stop and /ai-switch-start in the autocomplete list.
# Create skills directory
mkdir -p ~/.codex/skills
# Clone and copy
git clone https://github.com/quyendang/ai-switch.git /tmp/ai-switch
cp -r /tmp/ai-switch/skills/* ~/.codex/skills/
rm -rf /tmp/ai-switch
# Restart Codex CLIVerify by typing / in Codex CLI — you should see the two commands available.
Gemini CLI has a built-in skill installer:
# Install from GitHub (user scope — available in all projects)
gemini skills install https://github.com/quyendang/ai-switch.git
# Or install to workspace scope (current project only)
gemini skills install https://github.com/quyendang/ai-switch.git --scope workspace
# Reload skills
gemini skills reload
# Verify
gemini skills listAlternatively, clone and link:
git clone https://github.com/quyendang/ai-switch.git ~/code/ai-switch
gemini skills link ~/code/ai-switch/skills
gemini skills reloadCursor supports SKILL.md files via the .cursor/skills/ or .cursor/rules/ folder (depending on version). Copy the skill files into your project:
# Project install
mkdir -p .cursor/skills
git clone https://github.com/quyendang/ai-switch.git /tmp/ai-switch
cp -r /tmp/ai-switch/skills/* .cursor/skills/
rm -rf /tmp/ai-switchThen in Cursor, open the Composer and the skills will be discovered automatically. Invoke by saying "use ai-switch-stop" or pasting the workflow manually if slash commands are not yet supported in your Cursor version.
Most modern agents follow the same pattern: a directory like ~/.{agent}/skills/ or .{agent}/skills/ in your project. Copy the skills/ folder contents there.
# Generic universal install
git clone https://github.com/quyendang/ai-switch.git
cp -r ai-switch/skills/* ~/.YOUR_AGENT/skills/Check your agent's documentation for the exact path.
If you use the vercel-labs/skills universal installer, you can install once and share across all agents:
npx @vercel-labs/skills add https://github.com/quyendang/ai-switch.git --agent claude --agent codex --agent geminiThe skills are just folders with SKILL.md files. Copy them anywhere your AI reads instructions:
- Download or clone this repo
- Copy the three folders from
skills/:ai-switch/ai-switch-stop/ai-switch-start/
- Paste into your AI agent's skills / commands / rules directory
- Restart the agent
If your agent does not support skills at all, you can still use the workflow manually — see Manual usage below.
Once installed, the workflow is:
1. Initialize (first time only):
Just start working on your project normally. On your first /ai-switch-stop, the skill will create PROGRESS.md for you.
2. End of session:
You: /ai-switch-stop
AI: [updates PROGRESS.md, commits, pushes]
✅ Progress saved. Committed: a3f29c1.
Next agent should: continue implementing login form validation.
3. Start of next session (possibly in a different AI):
You: /ai-switch-start
AI: [reads PROGRESS.md, checks git]
📍 Resume Report
Last checkpoint: 2026-04-20 14:32 by Claude Code
Status: 🚧 In progress
Current task: Implementing login form validation
...
🎯 Suggested next action: Add password strength indicator
Before I continue, please confirm this state is accurate.
You: Yes, go ahead.
AI: [works normally]
That's it.
See skills/ai-switch/references/progress-template.md for the full template. Short version:
# Project Progress
**Last updated:** 2026-04-20 14:32
**Last agent:** Claude Code
**Status:** 🚧 In progress
## Current task
Implementing login form validation
## Todo list
- [x] Set up form component
- [x] Add email validation
- [~] Add password strength indicator
- [ ] Add rate limiting on submit
## Files changed this session
- `src/components/LoginForm.tsx` — added email regex validation
- `src/hooks/useAuth.ts` — created
## Decisions & notes
- 2026-04-20: Chose zod over yup for validation (smaller bundle)
## Next up
1. Complete password strength indicator (see react-zxcvbn)
2. Add submit rate limiting (max 5 attempts / minute)
## Changelog
| Date | Agent | Commit | Summary |
|---|---|---|---|
| 2026-04-20 | Claude Code | a3f29c1 | feat: add email validation to login form |If your AI agent does not support skills, you can still use this workflow by copy-pasting prompts.
Save progress prompt:
See templates/prompt-stop.md. Paste into any AI chat when ending a session.
Resume prompt:
See templates/prompt-start.md. Paste at the start of a new session.
Q: Do I need to commit after every small change?
A: /ai-switch-stop commits at the end of a session, not after every edit. For normal work within a session, commit as you normally would. ai-switch is specifically for session boundaries.
Q: What if the AI forgets to update PROGRESS.md?
A: Run /ai-switch-stop explicitly before closing. The skill is triggered by the command, so the AI will always update the file when told.
Q: What if the AI gets PROGRESS.md wrong?
A: It is a plain markdown file. Open it in any editor and fix it. The next /ai-switch-start will read your corrections.
Q: Can I use this for non-code projects? A: Yes. It works for any project tracked in git — writing, research notes, config files, infrastructure, etc.
Q: What if I use two AI agents at the same time?
A: Both will read and write to the same PROGRESS.md and git repo. Avoid this — race conditions are annoying. Use one agent at a time and switch with /ai-switch-stop + /ai-switch-start.
Q: Can AI agents bypass quality hooks (pre-commit, etc.)? A: The skill respects your git hooks. If a hook fails, the commit fails and the AI will report the error to you.
Q: What about monorepos?
A: Works fine — place PROGRESS.md at the root of the project you are focused on (the git root). For very large monorepos, you can have multiple PROGRESS.md files in different sub-projects, one per workstream.
Q: Does this replace docs/README/CHANGELOG? A: No. PROGRESS.md tracks ephemeral session state. Your README, architecture docs, and changelog remain as normal project artifacts.
Tested with:
- ✅ Claude Code
- ✅ Codex CLI (OpenAI)
- ✅ Gemini CLI (Google)
- ✅ Cursor (Composer)
- ✅ Windsurf
- ✅ Antigravity IDE
Should work with any agent supporting the SKILL.md standard. If you test with another agent and it works (or doesn't), please open an issue or PR.
- Portability over features. We use only git + markdown + POSIX shell. No custom server, no API keys, no proprietary file format.
- Conservative by default.
/ai-switch-startnever modifies anything without your approval./ai-switch-stopnever force-pushes or rewrites history. - Human-readable. PROGRESS.md is designed for humans first, agents second. You can edit it freely.
- Durable. The workflow survives any AI tool going away, changing pricing, or shutting down. Git + markdown outlive all of them.
PRs welcome. In particular:
- Testing on additional agents
- Translating READMEs to other languages
- Improving the PROGRESS.md template for specific project types
- Edge case handling
Open an issue to discuss bigger changes before submitting a PR.
MIT. See LICENSE.
Inspired by the pattern of treating PROGRESS.md as a shared memory artifact between AI coding sessions, and built on top of the open SKILL.md Agent Skills standard pioneered by Anthropic and adopted across the ecosystem.
Made by @quyendang — because switching AI agents mid-project shouldn't feel like starting over.