Skip to content

Instantly share code, notes, and snippets.

@jackspace
Last active November 7, 2025 21:49
Show Gist options
  • Select an option

  • Save jackspace/548c97c27b80d81d3083b7fefdf3af77 to your computer and use it in GitHub Desktop.

Select an option

Save jackspace/548c97c27b80d81d3083b7fefdf3af77 to your computer and use it in GitHub Desktop.

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

Or: How I Learned to Stop Worrying and Love the Skill Portability Dance

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.


Table of Contents (Because This Is Long and You Might Want to Skip to the Good Parts)

  1. The "Wait, There Are Two Skill Systems?" Moment
  2. Where the Hell Are My Claude Code Skills, Anyway?
  3. Project Skills vs. Universal Skills: An Existential Crisis
  4. The Great Migration: Moving Skills from Claude Code to Claude.ai
  5. The Reverse Journey: Claude.ai to Claude Code
  6. Pro Tips for Living Your Best Multi-Environment Life
  7. The Skill Creation Workflow That Actually Works
  8. Common Fuckups and How to Avoid Them
  9. The Future: Will These Systems Ever Talk?

The "Wait, There Are Two Skill Systems?" Moment {#the-revelation}

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.


Where the Hell Are My Claude Code Skills, Anyway? {#finding-your-skills}

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?

The Default Location (macOS/Linux)

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/   # Linux

Let'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)

The WSL Location (If You're Into That)

WSL (Windows Subsystem for Linux) users (and I say this with love), your skills are probably here:

\\wsl$\Ubuntu\home\YOUR_USERNAME\.claude\skills\

But Wait, What If It's Somewhere Else?

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/macOS

If this returns something, your skills are probably in:

$CLAUDE_HOME/skills/

The "I Installed from a Marketplace" Special Case

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-skills

Your skills are in:

~/.claude/skills/marketplace/anthropic-agent-skills/document-skills/

Quick Command to Find Everything

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.


Project Skills vs. Universal Skills: An Existential Crisis {#project-vs-universal}

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."

In Claude Code: Universal(ish) Skills

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.

In Claude.ai Projects: Project-Scoped Skills

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.

The Implications

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.


The Great Migration: Moving Skills from Claude Code to Claude.ai {#the-migration}

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.

Step 1: Find Your Skill Files

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 -la

You 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

Step 2: Understand What You're Moving

A Claude skill is really just:

  1. SKILL.md - The required file with YAML frontmatter and instructions
  2. 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.

Step 3: Prepare Your Skill for Upload

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.zip

Pro 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 subdirectory

Step 4: Upload to Claude.ai Project

Now, head to Claude.ai:

  1. 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
  2. Access Project Knowledge

    • Click on the Project name at the top
    • Click "Project knowledge" in the dropdown
  3. Upload Your Skill

    • Click "Add skill" (or "+" if it's your first skill)
    • Select "Upload skill files"
    • Choose your .zip file
    • OR drag and drop individual files if your skill is just SKILL.md
  4. 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
  5. 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

Step 5: Test Your Skill

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?

The "Single SKILL.md" Shortcut

If your skill is just a SKILL.md file with no other resources, you can skip the zip step:

  1. Copy the contents of SKILL.md
  2. In Claude.ai Project settings → Skills
  3. Click "Create new skill"
  4. Paste the content
  5. Save

Done. No zip required.


The Reverse Journey: Claude.ai to Claude Code {#reverse-migration}

Now let's go the other direction. Maybe you built or customized a skill in Claude.ai, and you want it locally.

Step 1: Download the Skill from Claude.ai

Currently (and this might change), there's no direct "download" button for skills in Claude.ai Projects. So you need to do this manually:

  1. Go to your Project
  2. Click Project Knowledge → Skills
  3. Find your skill
  4. 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

Step 2: Recreate Locally

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.md

Now 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.md

Paste the content you copied from Claude.ai and save.

Step 3: Add Supporting Files (If Any)

If your skill had additional files:

# Create a resources directory
mkdir resources

# Add your files
echo '{"config": "value"}' > resources/config.json

Repeat for each file in your skill.

Step 4: Test in Claude Code

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 Code

Then 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.

The Git Workflow (Recommended)

Here's a better approach: Use Git to manage your skills.

In Claude.ai:

  1. Work on your skill
  2. 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 main

Now your skills are version-controlled, backed up, and you can sync them across machines.


Pro Tips for Living Your Best Multi-Environment Life {#pro-tips}

1. The Single Source of Truth Strategy

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.

2. The Naming Convention That Saves Your Ass

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

3. The Sync Script

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.sh

Run it whenever you want to sync:

~/bin/sync-claude-skills.sh

4. The README Strategy

In 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 yet

Future you will thank past you.

5. The Skill Template

Create a template for new skills:

mkdir ~/.claude/skills/user/_template
cd ~/.claude/skills/user/_template

Create 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 limitations

Now 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 content

The Skill Creation Workflow That Actually Works {#workflow}

Here's my battle-tested workflow for creating skills that work everywhere:

Phase 1: Ideation & Testing (Claude.ai)

  1. 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
  2. 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]
    
  3. Iterate on the instructions

    • Test different phrasings
    • See what works, what doesn't
    • Refine until it's solid

Phase 2: Formalization (Text Editor)

  1. Copy the refined instructions into a local file

    cd ~/.claude/skills/user/
    mkdir homelab-proxmox-monitor
    cd homelab-proxmox-monitor
    vim SKILL.md
  2. Add proper YAML frontmatter

    ---
    name: homelab-proxmox-monitor
    description: Monitor and analyze Proxmox VE servers
    version: 1.0.0
    author: you@example.com
    ---
  3. Structure the instructions clearly

    • Use headers
    • Include examples
    • Document edge cases

Phase 3: Testing (Claude Code)

  1. Test in Claude Code

    # Start Claude Code
    claude-code
    
    # In the chat
    You: "Use homelab-proxmox-monitor to check my server"
  2. Iterate based on real usage

    • Watch how Claude interprets the instructions
    • Note where it gets confused
    • Update the SKILL.md accordingly
  3. Version control it

    git add .
    git commit -m "Add homelab-proxmox-monitor v1.0.0"
    git push

Phase 4: Deployment (Claude.ai Projects)

  1. Create a zip for deployment

    zip -r homelab-proxmox-monitor.zip .
  2. Upload to relevant Projects

    • Go to each Project that needs it
    • Upload the skill
    • Test it in that Project's context
  3. Document where it's deployed

    • Update the README
    • Track which Projects have which version

Phase 5: Maintenance

  1. 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.


Common Fuckups and How to Avoid Them {#common-fuckups}

Fuckup #1: Forgetting to Update the Version Number

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.

Fuckup #2: Inconsistent Naming

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.

Fuckup #3: Forgetting Supporting Files

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.

Fuckup #4: Not Testing in the Target Environment

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).

Fuckup #5: Overwriting the Wrong Version

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.zip

Prevention: Automate with the sync script, or at minimum, include version in filename.

Fuckup #6: Assuming Skills Auto-Sync

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.

Fuckup #7: Circular Dependencies

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.

Fuckup #8: Not Reading the Skill After Editing

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).


The Future: Will These Systems Ever Talk? {#the-future}

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:

What We Might See in 2025-2026

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

What We Need to Push For

As a community, we should advocate for:

  1. Skill export/import API - Let us programmatically move skills
  2. Skill versioning system - Track changes, rollback, compare
  3. Dependency management - Skills that depend on other skills
  4. Testing framework - Automated skill validation

In the Meantime

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.


The Real Talk Section

Look, if you've made it this far, you're probably thinking one of two things:

  1. "This is way more complicated than it should be"
  2. "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:

  1. Write good instructions for Claude
  2. Put them in a structured format
  3. 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.

The Synthesis

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.


The Quick Reference Guide

Because you'll come back to this article when you need to actually do the thing and you'll want the condensed version:

Finding Your Claude Code Skills

ls -la ~/.claude/skills/user/

Creating a Skill Locally

cd ~/.claude/skills/user/
mkdir my-new-skill
cd my-new-skill
vim SKILL.md  # Add frontmatter + instructions

Zipping a Skill for Upload

cd ~/.claude/skills/user/my-skill/
zip -r my-skill.zip .

Uploading to Claude.ai Project

  1. Open Project → Settings → Skills
  2. Upload the .zip file
  3. Test: "What skills do you have?"

Sync Script

#!/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"

Skill Template (SKILL.md)

---
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 cases

Final Thoughts

The 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.


Resources & Links


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].


Changelog

  • 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment