The Great Claude Skills Migration: A Love Story About Moving Your Shit Between Two Systems That Should Probably Talk To Each Other But Don't
A definitive guide to understanding, moving, and managing Claude Skills across Claude Code and Claude.ai Projects, written by someone who's done this enough times to have strong opinions about it.
- The "Wait, There Are Two Skill Systems?" Moment
- Where the Hell Are My Claude Code Skills, Anyway?
- Project Skills vs. Universal Skills: An Existential Crisis
- The Great Migration: Moving Skills from Claude Code to Claude.ai
- The Reverse Journey: Claude.ai to Claude Code
- Pro Tips for Living Your Best Multi-Environment Life
- The Skill Creation Workflow That Actually Works
- Common Fuckups and How to Avoid Them
- The Future: Will These Systems Ever Talk?
So you've been living your best life with Claude Code, cranking out skills like you're Gordon Ramsay in a MasterChef kitchen, building automation that makes your friends jealous and your Docker containers purr. Then one day, you fire up Claude.ai in your browser,maybe you're on a different machine, maybe you're showing off to a colleague, maybe you just wanted to see if the grass is greener in the cloud,and you think to yourself: "I'll just use my awesome homelab monitoring skill I built last week."
Except... it's not there.
You search. You refresh. You check your files. You question your sanity. You briefly consider that maybe you imagined building that skill during a particularly vivid fever dream.
But no. The skill exists. It's just that Claude Code skills and Claude.ai Project skills are two completely different universes that, as of this writing, communicate about as well as your divorced parents at Thanksgiving dinner.
This isn't a bug. This isn't an oversight. This is the reality of working with an ecosystem that's evolving faster than Marvel's multiverse can keep up with retcons. And like any good multiverse situation, you need a guide to understand which universe you're in and how to port your powers between them.
Welcome. I'm your guide. Let's do this.
First things first. If you're using Claude Code and you've been building or installing skills, they live somewhere on your machine. The question is: where?
By default, Claude Code stores skills in your home directory:
~/.claude/skills/Or, if you want to get fancy with the full path:
/Users/YOUR_USERNAME/.claude/skills/ # macOS
/home/YOUR_USERNAME/.claude/skills/ # LinuxLet's see what's in there:
ls -la ~/.claude/skills/You should see a structure that looks something like this:
.claude/skills/
├── user/ # Your custom skills
│ ├── my-awesome-skill/
│ │ ├── SKILL.md
│ │ └── resources/
│ └── homelab-monitor/
│ └── SKILL.md
├── marketplace/ # Skills from plugin marketplaces
│ ├── anthropic-agent-skills/
│ │ ├── document-skills/
│ │ └── example-skills/
│ └── superpowers-marketplace/
└── cache/ # Claude's internal cache (ignore this)
WSL (Windows Subsystem for Linux) users (and I say this with love), your skills are probably here:
\\wsl$\Ubuntu\home\YOUR_USERNAME\.claude\skills\Claude Code respects the CLAUDE_HOME environment variable. If someone (possibly drunk-you from 2am last Tuesday) set this variable, your skills might be wherever that points.
Check it:
echo $CLAUDE_HOME # *nix/macOSIf this returns something, your skills are probably in:
$CLAUDE_HOME/skills/If you've been using Claude Code's plugin marketplace system (and you should, it's pretty slick), those skills live in the marketplace/ subdirectory I mentioned above. These are namespaced by the marketplace they came from.
For example, if you ran:
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skillsYour skills are in:
~/.claude/skills/marketplace/anthropic-agent-skills/document-skills/Here's a one-liner that'll show you all your skill directories:
find ~/.claude/skills -name "SKILL.md" -type f | sed 's|/SKILL.md||g'This searches for all SKILL.md files (the heart of every skill) and shows you their parent directories. You're welcome.
Alright, here's where things get philosophical. And by philosophical, I mean "annoying in ways that will make you want to scream into a pillow."
When you install a skill in Claude Code, it's available to all your projects in that Claude Code instance. You install it once, use it everywhere. It's like that one spice blend you bought at Costco,you didn't need 5 pounds of it, but now you're going to use it in everything.
This happens because Claude Code runs locally on your machine, and it loads skills from your ~/.claude/skills/ directory regardless of which project you're working on.
Now, Claude.ai Projects take a different approach. Skills you upload to a Project are scoped to that specific Project. They don't bleed across. Each Project is its own universe.
This is actually pretty smart from a privacy and organization standpoint:
- Your "work-project" can have your company's brand guidelines skill without polluting your "personal-blog-project"
- Your "homelab-automation" project can have server management skills without confusing Claude when you're in your "creative-writing" project
- You can have different versions of the same skill in different projects for testing
But it also means: If you want to use a skill in multiple Projects, you need to upload it multiple times.
I know. I can hear you groaning from here.
Here's what this means in practice:
Scenario 1: You build a skill in Claude Code
- You can use it in any local project immediately
- To use it in Claude.ai, you must upload it to EACH Project where you want it
- Changes you make locally don't sync to the cloud
Scenario 2: You build/customize a skill in a Claude.ai Project
- You can only use it in that specific Project
- To use it in Claude Code, you must download and install it locally
- To use it in another Project, you must re-upload it there
Scenario 3: You improve a skill over time
- You need to manually push updates to wherever you want them
- There's no version control built in (yet)
- You'll forget which version is where and spend 20 minutes debugging why "the newest features" aren't working
This is not ideal. But it's workable. And I'm going to show you how to make it work.
Alright, let's say you've built the world's greatest homelab monitoring skill in Claude Code, and now you want to use it in your Claude.ai "Infrastructure" Project. Here's how.
Navigate to your skill directory:
cd ~/.claude/skills/user/my-awesome-skill/Or wherever your skill lives. The key file you need is SKILL.md. This is the brain of the operation.
List what you've got:
ls -laYou might see:
SKILL.md # Required: The skill instructions
resources/ # Optional: Supporting files
└── config.json
└── template.txt
scripts/ # Optional: Helper scripts
└── process.py
README.md # Optional: Human documentation
A Claude skill is really just:
- SKILL.md - The required file with YAML frontmatter and instructions
- Supporting files - Optional stuff that makes the skill better
The SKILL.md has this structure:
---
name: my-awesome-skill
description: Does cool stuff with your homelab
version: 1.0.0
author: you@example.com
---
# My Awesome Skill
Instructions that Claude will follow...
## Usage Examples
Show Claude how to use this...
## Pro Tips
Your wisdom here...Important: Claude.ai Projects can handle subdirectories and multiple files, but the SKILL.md is the entry point.
If your skill has multiple files, you need to zip them up:
# Make sure you're in the skill directory
cd ~/.claude/skills/user/my-awesome-skill/
# Create a zip archive with all files
zip -r my-awesome-skill.zip .
# Verify it worked
unzip -l my-awesome-skill.zipPro tip: Make sure the zip contains the files directly, not wrapped in another directory. When unzipped, it should extract SKILL.md and other files at the top level, not my-awesome-skill/SKILL.md.
Test your zip:
# Create a test directory
mkdir /tmp/skill-test
cd /tmp/skill-test
# Extract your zip
unzip ~/path/to/my-awesome-skill.zip
# Check the structure
ls -la
# Should show SKILL.md, not a subdirectoryNow, head to Claude.ai:
-
Open or create your Project
- Go to https://claude.ai
- Click on "Projects" in the sidebar
- Open an existing Project or create a new one
-
Access Project Knowledge
- Click on the Project name at the top
- Click "Project knowledge" in the dropdown
-
Upload Your Skill
- Click "Add skill" (or "+" if it's your first skill)
- Select "Upload skill files"
- Choose your
.zipfile - OR drag and drop individual files if your skill is just
SKILL.md
-
Wait for Processing
- Claude will extract and validate your skill
- This usually takes 5-10 seconds
- You'll see your skill appear in the "Skills" section
-
Verify It Loaded
- Start a new chat in the Project
- Ask Claude: "What skills do you have available?"
- Your skill should appear in the list
Don't just assume it works. Actually test it:
You: "Use my-awesome-skill to monitor my Proxmox server"
Claude: [Should acknowledge the skill and use it]
If Claude doesn't recognize it, check:
- Is the YAML frontmatter properly formatted?
- Is the skill name in the frontmatter exactly what you're referencing?
- Did any special characters get mangled in the upload?
If your skill is just a SKILL.md file with no other resources, you can skip the zip step:
- Copy the contents of
SKILL.md - In Claude.ai Project settings → Skills
- Click "Create new skill"
- Paste the content
- Save
Done. No zip required.
Now let's go the other direction. Maybe you built or customized a skill in Claude.ai, and you want it locally.
Currently (and this might change), there's no direct "download" button for skills in Claude.ai Projects. So you need to do this manually:
- Go to your Project
- Click Project Knowledge → Skills
- Find your skill
- Copy the contents
If your skill has multiple files:
- You'll need to view and copy each file individually
- Claude.ai shows you the file structure
Create the directory structure:
# Navigate to your user skills directory
cd ~/.claude/skills/user/
# Create a directory for your skill
mkdir my-claude-ai-skill
cd my-claude-ai-skill
# Create the SKILL.md file
touch SKILL.mdNow open SKILL.md in your editor and paste the content:
# Using vim (if you're hardcore)
vim SKILL.md
# Using nano (if you're sensible)
nano SKILL.md
# Using VSCode (if you're civilized)
code SKILL.mdPaste the content you copied from Claude.ai and save.
If your skill had additional files:
# Create a resources directory
mkdir resources
# Add your files
echo '{"config": "value"}' > resources/config.jsonRepeat for each file in your skill.
Open Claude Code and start a new chat:
# If Claude Code is already running, it should auto-detect the new skill
# If not, restart Claude CodeThen test:
You: "What skills do you have?"
Your skill should appear in the list.
You: "Use my-claude-ai-skill to do the thing"
Verify it works as expected.
Here's a better approach: Use Git to manage your skills.
In Claude.ai:
- Work on your skill
- Copy the final version
Locally:
# Create a Git repo for your skills
cd ~/.claude/skills/user/
git init
git add .
git commit -m "Initial skills"
# Add your new skill
mkdir new-skill
cd new-skill
# Paste from Claude.ai
vim SKILL.md
# Commit it
git add .
git commit -m "Add new-skill from Claude.ai"
# Push to GitHub (optional but smart)
git remote add origin https://github.com/yourusername/my-claude-skills.git
git push -u origin mainNow your skills are version-controlled, backed up, and you can sync them across machines.
Pick ONE place to be your "primary" skill development environment:
Option A: Claude Code as Primary
- Develop and test skills locally
- Push to GitHub
- Import to Claude.ai Projects as needed
- Pros: Full control, version control, can use local editor
- Cons: Manual sync to cloud
Option B: Claude.ai as Primary
- Develop skills in Projects
- Export to local when stable
- Pros: Test in production immediately
- Cons: Less control, manual file management
My recommendation: Use Claude Code as primary, Claude.ai Projects for deployment. It's like developing on localhost and deploying to production.
Name your skills consistently:
project-type-function-version
Examples:
homelab-monitor-proxmox-v1
work-report-weekly-status-v2
personal-blog-seo-optimizer-v1
This makes it obvious:
- What the skill does
- Which Project/context it belongs to
- Which version you're looking at
Create a simple script to sync skills:
#!/bin/bash
# save as ~/bin/sync-claude-skills.sh
CLAUDE_SKILLS="$HOME/.claude/skills/user"
PROJECTS_EXPORT="$HOME/Documents/claude-projects-skills"
echo "Syncing Claude skills..."
# Create export directory if it doesn't exist
mkdir -p "$PROJECTS_EXPORT"
# For each skill, create a zip
for skill_dir in "$CLAUDE_SKILLS"/*; do
if [ -d "$skill_dir" ]; then
skill_name=$(basename "$skill_dir")
echo "Processing: $skill_name"
cd "$skill_dir"
zip -r "$PROJECTS_EXPORT/${skill_name}.zip" .
echo " ✓ Created ${skill_name}.zip"
fi
done
echo "Done! Zips are in: $PROJECTS_EXPORT"
echo "Upload these to your Claude.ai Projects"Make it executable:
chmod +x ~/bin/sync-claude-skills.shRun it whenever you want to sync:
~/bin/sync-claude-skills.shIn EVERY skill, include a README.md that documents:
# My Awesome Skill
## What It Does
Clear description of the skill's purpose
## Where It's Used
- Claude Code: ✓
- Claude.ai Project "Homelab": ✓
- Claude.ai Project "Work": ✗
## Version History
- v1.0.0 (2025-11-06): Initial version
- v1.1.0 (2025-11-15): Added Proxmox support
## Installation
### Claude Code
\`\`\`bash
cd ~/.claude/skills/user/
git clone https://github.com/you/my-awesome-skill.git
\`\`\`
### Claude.ai Projects
1. Download `my-awesome-skill.zip`
2. Upload to Project → Skills
## Testing
How to verify it works
## Known Issues
What doesn't work yetFuture you will thank past you.
Create a template for new skills:
mkdir ~/.claude/skills/user/_template
cd ~/.claude/skills/user/_templateCreate SKILL.md:
---
name: SKILL_NAME_HERE
description: DESCRIPTION_HERE
version: 0.1.0
author: YOUR_NAME
created: 2025-11-06
updated: 2025-11-06
---
# SKILL_NAME_HERE
## Purpose
What this skill does and why it exists
## Usage
### Examples
\`\`\`
Example usage here
\`\`\`
## Instructions for Claude
When this skill is activated:
1. First, do this...
2. Then, do that...
3. Finally, do the other thing...
## Guidelines
- Important rule 1
- Important rule 2
## Common Patterns
Show Claude common use cases
## Edge Cases
Document known limitationsNow when you create a new skill:
cd ~/.claude/skills/user/
cp -r _template new-skill-name
cd new-skill-name
# Edit SKILL.md with your actual contentHere's my battle-tested workflow for creating skills that work everywhere:
-
Start in a Claude.ai chat (not in a Project yet)
- Describe what you want the skill to do
- Work with Claude to refine the idea
- Test the instructions conversationally
-
Use the skill-creator skill (it's built into Claude.ai)
You: "Help me create a skill for monitoring my Proxmox homelab" Claude: [Uses skill-creator to scaffold a skill] -
Iterate on the instructions
- Test different phrasings
- See what works, what doesn't
- Refine until it's solid
-
Copy the refined instructions into a local file
cd ~/.claude/skills/user/ mkdir homelab-proxmox-monitor cd homelab-proxmox-monitor vim SKILL.md
-
Add proper YAML frontmatter
--- name: homelab-proxmox-monitor description: Monitor and analyze Proxmox VE servers version: 1.0.0 author: you@example.com ---
-
Structure the instructions clearly
- Use headers
- Include examples
- Document edge cases
-
Test in Claude Code
# Start Claude Code claude-code # In the chat You: "Use homelab-proxmox-monitor to check my server"
-
Iterate based on real usage
- Watch how Claude interprets the instructions
- Note where it gets confused
- Update the SKILL.md accordingly
-
Version control it
git add . git commit -m "Add homelab-proxmox-monitor v1.0.0" git push
-
Create a zip for deployment
zip -r homelab-proxmox-monitor.zip . -
Upload to relevant Projects
- Go to each Project that needs it
- Upload the skill
- Test it in that Project's context
-
Document where it's deployed
- Update the README
- Track which Projects have which version
- When you make improvements
- Update locally first
- Bump the version number
- Test in Claude Code
- Create new zip
- Re-upload to Projects
- Document changes
This workflow sounds like a lot, but once you've done it a few times, it becomes second nature. And you'll have skills that work consistently everywhere.
What happens: You improve a skill locally, upload it to a Project, but Claude still behaves like the old version.
Why: Claude.ai caches skills based on their name and version. If you don't bump the version, it might not reload.
Fix:
---
name: my-skill
version: 1.0.1 # Bump this!
---Prevention: Use semantic versioning and always bump when you deploy.
What happens: You have homelab-monitor, homelab_monitor, and HomelabMonitor scattered across Projects and local, and you can't remember which is which.
Why: You were in a hurry and didn't think about it.
Fix: Pick ONE naming convention and stick to it. I recommend kebab-case (homelab-monitor).
Prevention: Use the template with proper naming from the start.
What happens: Your skill references resources/config.json but you only uploaded SKILL.md.
Why: You copied just the markdown file and forgot about dependencies.
Fix: Always zip the entire skill directory, not just SKILL.md.
Prevention: Use the sync script. It handles everything.
What happens: Skill works great in Claude Code, breaks in Claude.ai Projects (or vice versa).
Why: Different environments have different tool availability or context limitations.
Fix: Test in both environments before considering a skill "done."
Prevention: Make testing part of your workflow (Phase 3 above).
What happens: You fix a bug in version 1.2.0, but accidentally upload 1.1.0 to your Project, and now the bug is back.
Why: You grabbed the wrong zip file.
Fix:
# Always name your zips with versions
my-skill-v1.2.0.zip
my-skill-v1.1.0.zipPrevention: Automate with the sync script, or at minimum, include version in filename.
What happens: You update a skill locally and expect it to magically appear in your Projects.
Why: Because that would be logical, but it doesn't work that way (yet).
Fix: Accept that manual sync is required.
Prevention: Set a reminder to sync weekly, or build a sync workflow.
What happens: Skill A references Skill B, which references Skill C, which references Skill A. Claude gets confused.
Why: You built skills incrementally without thinking about dependencies.
Fix: Refactor to remove circular references. Skills should be self-contained or have clear hierarchies.
Prevention: Design skills to be independent, or document dependencies clearly.
What happens: You edit a skill, save it, and when Claude uses it, the results are completely wrong.
Why: You had a typo, broke the YAML frontmatter, or your instructions contradicted themselves.
Fix:
# Validate your YAML
python3 -c "import yaml; yaml.safe_load(open('SKILL.md').read().split('---')[1])"Prevention: Use a proper editor with YAML validation (VSCode with YAML extension).
Let's address the elephant in the room: This is kind of a pain in the ass.
The good news is that Anthropic is actively developing the skills ecosystem, and based on patterns in the industry, here's what might (should) happen:
1. Unified Skill Storage
- A central repo (like npm, pip, or brew) for Claude skills
- Install once, available everywhere
- Automatic syncing across environments
2. Built-in Version Control
- Git integration directly in Claude.ai
- Push/pull skills from GitHub
- Conflict resolution UI
3. Skill Marketplaces
- Official skill store
- Community skills with ratings/reviews
- One-click install to any environment
4. Cross-Platform Skill Manager
- CLI tool:
claude-skills sync - Handles all the zip/upload/download automatically
- Respects Project boundaries while enabling reuse
As a community, we should advocate for:
- Skill export/import API - Let us programmatically move skills
- Skill versioning system - Track changes, rollback, compare
- Dependency management - Skills that depend on other skills
- Testing framework - Automated skill validation
Until then, we work with what we have. And honestly? The manual workflow isn't terrible once you've set up your systems. It's like the early days of Docker before docker-compose. Annoying, but functional.
The skills themselves are powerful enough that the overhead is worth it.
Look, if you've made it this far, you're probably thinking one of two things:
- "This is way more complicated than it should be"
- "This is actually pretty straightforward once you understand it"
Both are true.
The complexity exists because we're in the early days of a new paradigm. Remember when everyone was confused about virtual environments in Python? Or when Docker was new and everyone was like "wait, containers aren't VMs?" This is that moment for AI skills.
The key insight is this: Skills are just specialized prompts with structure. Everything else,the file locations, the sync process, the Projects vs. Code distinction,is just plumbing. Important plumbing, sure, but plumbing nonetheless.
Once you internalize that, the workflow becomes:
- Write good instructions for Claude
- Put them in a structured format
- Make them available where you need them
That's it. The rest is just execution details.
You know what this reminds me of? It's like when Jon Stewart would talk about how the media covered politics. Everyone focuses on the horse race,who's up, who's down, what the polls say,and completely misses the actual policy that matters.
With Claude Skills, everyone focuses on the mechanics: "Where are my files?" "How do I zip things?" "Which version is in which Project?"
But the real value is in what you build. The skill that automates your weekly reports. The skill that monitors your homelab and alerts you to issues. The skill that helps you refactor code. Those are the things that matter.
The portability stuff? That's just so you can use your valuable skills wherever you need them. Don't let the process distract you from the purpose.
Here's the thing: The skills system is incredibly powerful. The ability to teach Claude new capabilities, to specialize it for your exact use case, to build automation that thinks,that's transformative.
The fact that moving those skills between environments takes a few extra steps? That's a tax we pay for being early adopters. And early adopters always pay that tax.
But early adopters also get the benefits first. While everyone else is still using Claude as a fancy chatbot, you're building systems that amplify your capabilities in ways most people don't even understand yet.
So yeah, set up your sync scripts. Create your templates. Build your workflows. Document your skills. Version control everything.
And then use those skills to build things that matter.
Because you'll come back to this article when you need to actually do the thing and you'll want the condensed version:
ls -la ~/.claude/skills/user/cd ~/.claude/skills/user/
mkdir my-new-skill
cd my-new-skill
vim SKILL.md # Add frontmatter + instructionscd ~/.claude/skills/user/my-skill/
zip -r my-skill.zip .- Open Project → Settings → Skills
- Upload the
.zipfile - Test: "What skills do you have?"
#!/bin/bash
SKILLS_DIR="$HOME/.claude/skills/user"
EXPORT_DIR="$HOME/Documents/claude-project-skills"
mkdir -p "$EXPORT_DIR"
for skill in "$SKILLS_DIR"/*; do
name=$(basename "$skill")
cd "$skill"
zip -r "$EXPORT_DIR/${name}.zip" .
done
echo "Zips created in: $EXPORT_DIR"---
name: skill-name
description: What it does
version: 1.0.0
author: your@email.com
---
# Skill Name
## Instructions
What Claude should do when using this skill
## Examples
Show Claude how to use it
## Guidelines
Important rules and edge casesThe Claude Skills ecosystem is evolving rapidly. By the time you read this, some of the pain points I've described might be solved. New tools might exist. Better workflows might emerge.
But the fundamentals will remain:
- Skills are structured instructions
- You need to manage them across environments
- Good organization and documentation save future-you time
- Testing in both environments is essential
- Version control is your friend
Build your systems. Document your work. Share your skills. And when you find a better way to do something, write about it.
That's how we level up the entire ecosystem.
Now go build something cool.
- Anthropic Skills Repo: https://github.com/anthropics/skills
- Awesome Claude Skills: https://github.com/travisvn/awesome-claude-skills
- Claude Code Documentation: https://docs.claude.com/claude-code
- Skills API Docs: https://docs.claude.com/api/skills
- skill-creator skill: Built into Claude.ai (just ask Claude to use it)
Written by a human who has moved too many skills between too many systems and wanted to save you the same pain. If this helped you, consider sharing it with someone who's about to go through the same journey.
If you found this valuable and want to support more guides like this, [buy me a coffee / subscribe / whatever monetization thing you're doing].
- 2025-11-06: Initial publication
- [Future Date]: Will update when Anthropic inevitably improves this workflow
License: Do whatever you want with this. If it helps you, great. If you improve it, share the improvements. That's how knowledge works.