How to Migrate from Custom GPTs to Agent Shelf

Why migrate from Custom GPTs?

Custom GPTs are useful, but they lock your agent definitions inside a single platform. If you've built a Custom GPT that your team relies on, you've probably run into these limitations:

• Platform lock-in. Your GPT only works inside ChatGPT. Teammates who prefer Cursor, Claude Code, or Windsurf can't use it.
• No version control. There's no built-in way to track changes, roll back, or manage versions of your GPT instructions.
• Paywall. Everyone who uses your GPT needs a ChatGPT Plus subscription ($20/month minimum).
• No IDE integration. Custom GPTs run in a browser tab, disconnected from your codebase, terminal, and file system.

Agent Shelf definitions are plain Markdown files. They work across 40+ AI coding tools, support semantic versioning, and live in your project alongside your code.

Step 1: Export your GPT instructions

OpenAI doesn't offer an export button, but getting your instructions out is straightforward.

1. Open ChatGPT and go to Explore GPTs > My GPTs
2. Click the GPT you want to migrate, then click Edit
3. Copy the entire contents of the Instructions field
4. Note any Conversation Starters you've defined (these can become example prompts in your agent)
5. Note which Capabilities are enabled (Web Browsing, DALL-E, Code Interpreter)

Save the instructions text to a file. You'll restructure it in the next step.

Step 2: Convert to Agent Shelf format

Agent Shelf agents use YAML frontmatter followed by a Markdown body. Here's the structure:

Before: Custom GPT config

Name: Code Review Expert
Description: Reviews pull requests with a focus on security and performance

Instructions:
You are a senior code reviewer. When given code, you should:
1. Check for security vulnerabilities
2. Identify performance issues
3. Suggest improvements
4. Rate severity as high/medium/low

Always be constructive. Never just say "looks good" without detailed analysis.
Capabilities: Web Browsing, Code Interpreter

After: Agent Shelf Markdown

---
id: code-review-expert
name: Code Review Expert
description: Reviews pull requests with a focus on security and performance
version: 1.0.0
category: coding
tags:
  - code-review
  - security
  - performance
license: MIT
---

## Persona

You are a senior code reviewer with deep expertise in application security and performance optimization.

## Workflow

When reviewing code, follow this process:

1. **Understand context** — Read the full diff and understand the purpose of the change
2. **Security audit** — Check for injection vulnerabilities, auth issues, data exposure, and insecure defaults
3. **Performance review** — Identify N+1 queries, unnecessary re-renders, memory leaks, and algorithmic inefficiency
4. **Improvement suggestions** — Propose concrete alternatives with code examples
5. **Severity rating** — Rate each finding as high, medium, or low severity

## Rules

- Be constructive. Every criticism must include a suggested fix.
- Never respond with just "looks good" without detailed analysis.
- When reading files, check the surrounding context, not just the changed lines.
- Flag security issues before style issues.

Notice what changed: the instructions became structured Markdown sections with clear headings. The frontmatter captures metadata that ChatGPT stored in form fields.

Step 3: Adapt instructions for coding tools

Custom GPTs run in a browser with access to web browsing, image generation, and a sandboxed Python environment. AI coding tools operate differently. They have access to your file system, terminal, and project context.

Remove references to capabilities that don't transfer:

• ~~"Search the web for..."~~ — Most coding tools don't browse the web (though some have MCP servers for this)
• ~~"Generate an image showing..."~~ — DALL-E isn't available in coding environments
• ~~"Use the browser to verify..."~~ — Replace with terminal commands or file reads

Add coding-tool-specific instructions:

• "Read the project's README and package.json to understand the tech stack before responding"
• "Check existing code patterns in the codebase before suggesting new approaches"
• "Run tests after making changes to verify nothing is broken"
• "Use the terminal to verify your suggestions compile/run correctly"

Restructure for file-system context. GPTs work with pasted snippets. Coding tools work with full repositories. Update your instructions to reference files, directories, and project structure rather than expecting copy-pasted code.

Step 4: Publish to Agent Shelf

Once your Markdown file is ready, you have two options:

Option A: Upload via the web UI. Go to Agent Shelf Upload and submit your Markdown file directly.

Option B: Publish from your coding tool. If you have the Agent Shelf skill installed, just ask your AI assistant to publish the agent. It handles authentication and upload automatically.

Either way, your agent gets a unique ID, version tracking, and a shareable page. Teammates can install it with a single command, no ChatGPT subscription required.

What doesn't transfer

Be upfront about what you'll lose in the migration:

| Feature | Custom GPTs | Agent Shelf | |---------|-------------|-------------| | Web browsing | Built-in | Requires MCP server | | Image generation | DALL-E built-in | Not available | | Code Interpreter | Sandboxed Python | Full terminal access (more powerful) | | Actions (API calls) | Built-in | Use MCP servers instead | | Knowledge files | Upload files to GPT | Reference project files directly | | Conversation memory | Per-user memory | Handled by the AI tool |

The trade-off is clear: you lose some browser-based features but gain full IDE integration, file system access, version control, and cross-tool portability.

Tips for a clean migration

• Start with your most-used GPT. Migrate one agent, test it thoroughly, then do the rest.
• Add a changelog. When you publish version 1.0.0, note that it's a migration from your Custom GPT.
• Test across tools. Try your agent in at least two different AI tools to make sure the instructions are tool-agnostic.
• Read our guide on writing effective agent definitions for tips on structuring instructions that work well across different AI tools.

Migration takes about 15 minutes per GPT. The result is an agent that works everywhere, versions cleanly, and doesn't require a subscription to use.