How to Migrate Your Claude Code Setup to OpenClaw Skills

If you have been using Claude Code for a while, you probably have a collection of CLAUDE.md files, custom prompts, and workflow conventions scattered across your projects. They work — but they are hard to share, difficult to version, and impossible to discover. OpenClaw skills solve all three problems by giving your agent configuration a standard format, a distribution mechanism, and a community.

This guide walks you through converting your existing Claude Code setup into reusable OpenClaw skills, step by step.

Why Migrate?

Before we get into the how, here is why the migration is worth the effort.

Portability. A CLAUDE.md file lives in one project. An OpenClaw skill can be installed in any project with a single command. If you have ten repositories that all need the same coding conventions, you are currently maintaining ten copies of the same instructions.

Discoverability. Your CLAUDE.md is invisible to other developers. An OpenClaw skill published to the Bazaar can be found, evaluated, and installed by anyone. That teammate who could benefit from your testing conventions? They cannot find your CLAUDE.md — but they can find your skill.

Versioning. Skills have versions. When you improve your instructions, every project using the skill gets the update. With CLAUDE.md files, you have to manually copy changes across repositories.

Composition. Skills are designed to work together. You can install multiple skills and they compose without conflicts. Merging multiple CLAUDE.md files is manual and error-prone.

Step 1: Audit Your Current Setup

Start by collecting everything your agent currently relies on. In most Claude Code setups, this is spread across several locations.

Project-level CLAUDE.md

This is the most common location. Open your CLAUDE.md and categorize each section:

# Example CLAUDE.md sections
## Project Overview          --> Context (not a skill)
## Code Style Rules          --> Candidate for a skill
## Testing Conventions       --> Candidate for a skill
## Git Commit Format         --> Candidate for a skill
## Architecture Decisions    --> Context (project-specific)
## Deployment Process        --> Candidate for a skill

The key distinction: project-specific context (what this particular app does, its architecture) stays in CLAUDE.md. Reusable conventions (how to write tests, code style, deployment patterns) become skills.

Manual Prompts You Repeat

Think about the prompts you type frequently. Things like:

• "Always use TypeScript strict mode and never use any"
• "Write tests using pytest with fixtures, not unittest"
• "Use conventional commits: feat, fix, chore, docs"

These repeated prompts are the strongest candidates for skills because you are already maintaining them in your head.

Slash Commands and Custom Instructions

If you have set up custom slash commands or system instructions, document them. These map directly to skill capabilities.

Step 2: Define Skill Boundaries

The most common migration mistake is creating one giant skill that does everything. Instead, split your instructions into focused skills, each covering one concern.

Too broad:

skill: "my-fullstack-conventions"
Contains: code style + testing + git + deployment + security + everything

Better:

skill: "typescript-strict-conventions"   --> Code style
skill: "pytest-fixtures-pattern"         --> Testing
skill: "conventional-commits-enforcer"   --> Git workflow
skill: "docker-deploy-railway"           --> Deployment

A good rule of thumb: each skill should be useful to someone who does not share your exact stack. A TypeScript style skill is useful to any TypeScript developer. A skill that combines TypeScript style with Django deployment conventions is useful to almost nobody.

Step 3: Convert Instructions to Skill Format

An OpenClaw skill is a structured markdown file with metadata. Here is the basic format:

---
name: typescript-strict-conventions
version: 1.0.0
description: Enforces strict TypeScript conventions with no-any rules and explicit return types
tags: [typescript, code-style, strict]
---

# TypeScript Strict Conventions

## Rules

- Never use \`any\`. Use \`unknown\` and narrow with type guards.
- All functions must have explicit return types.
- Prefer \`interface\` over \`type\` for object shapes.
- Use \`readonly\` for properties that should not be reassigned.
- Prefer \`const\` assertions for literal types.

## Examples

### Instead of this:
\`\`\`typescript
function getData(input: any): any {
  return input.value;
}
\`\`\`

### Write this:
\`\`\`typescript
function getData(input: unknown): string {
  if (typeof input === 'object' && input !== null && 'value' in input) {
    return String((input as { value: unknown }).value);
  }
  throw new TypeError('Expected object with value property');
}
\`\`\`

Notice the structure: metadata at the top in frontmatter, clear rules in the body, and concrete examples that show the before and after. The examples are critical — they give the agent pattern-matching material, not just abstract rules.

Step 4: Translate Common CLAUDE.md Patterns

Here are the most common CLAUDE.md patterns and how to express them as skills.

Code Style Rules

In CLAUDE.md:

## Code Style
- Use 2-space indentation
- Prefer arrow functions
- Always destructure props
- No default exports except for pages

As a skill: Wrap these in a skill with the code-style tag. Add examples for each rule — especially the non-obvious ones like "no default exports except for pages." Show a component with a named export and a page with a default export so the agent understands the exception.

Testing Requirements

In CLAUDE.md:

## Testing
- Use React Testing Library, not Enzyme
- Test behavior, not implementation
- Mock API calls with MSW
- Every component needs at least one test

As a skill: This is a strong skill candidate. Add a full test example that demonstrates the MSW setup, the testing-library queries, and the behavioral testing approach. Include a conftest or setup file example so the agent knows the project's test infrastructure.

Git Conventions

In CLAUDE.md:

## Commits
- Use conventional commits
- Scope is required: feat(auth): add login flow
- No WIP commits on main

As a skill: Create a commit-conventions skill with examples of good and bad commit messages. Include the full list of allowed scopes if your project has them. This skill is highly reusable across projects.

Step 5: Test Your Skills Locally

Before publishing, install your skills locally and verify they work.

openclaw skill install ./path/to/your-skill.md --local

Test with prompts that previously required your CLAUDE.md instructions. Ask your agent to:

1. Write a component and check if it follows your style rules
2. Generate tests and verify they use the right patterns
3. Create a commit message and confirm it matches your conventions

If the agent misses something, go back and add more explicit instructions or examples to the skill. The most common issue is rules that are clear to humans but ambiguous to agents — adding a concrete example almost always fixes this.

Step 6: Slim Down Your CLAUDE.md

After migrating reusable conventions to skills, your CLAUDE.md should only contain project-specific context:

# CLAUDE.md

## Project Overview
This is the Acme billing service. It handles subscription management,
invoice generation, and payment processing via Stripe.

## Architecture
- API layer: FastAPI with async handlers
- Database: PostgreSQL via SQLAlchemy 2.0
- Queue: Redis with Celery for async jobs
- Auth: JWT tokens validated by API gateway

## Key Domain Concepts
- A "subscription" belongs to an "organization", not a "user"
- Invoices are immutable once finalized
- All monetary values are stored as integers (cents)

## Local Development
- Run \`make dev\` to start all services
- Seed data: \`make seed\`
- Tests: \`make test\`

This is cleaner, easier to maintain, and does not duplicate instructions that now live in skills.

Step 7: Publish to the Bazaar (Optional)

If your skills are useful beyond your own projects, publish them to the Bazaar so other developers can benefit.

openclaw skill publish ./path/to/your-skill.md

The publishing process validates your skill format, checks for required metadata, and creates a listing in the skills directory. You can update your skill at any time, and projects using it will get the new version on their next sync.

For the full publishing guide, see how to publish your OpenClaw skill on the Bazaar.

Common Migration Mistakes

Putting project context in skills. Your skill should not reference specific files, endpoints, or domain concepts from one project. Keep project-specific context in CLAUDE.md and general conventions in skills.

Making skills too large. If your skill is over 500 lines, it probably covers too many concerns. Split it. Agents process focused instructions better than comprehensive ones.

Skipping examples. Rules without examples are suggestions. Rules with examples are patterns. Always include before-and-after code samples.

Not testing before publishing. A skill that sounds right but produces wrong output is worse than no skill at all. Always test locally first.

The End State

After migration, your agent setup looks like this:

• CLAUDE.md — Lean project context: what the app does, its architecture, and local dev commands.
• Installed skills — Reusable conventions for code style, testing, Git, deployment, and anything else that applies across projects.
• No repeated prompts — Everything you used to type manually is now encoded in a skill that activates automatically.

This is a cleaner, more maintainable setup that scales across teams and projects. And if you have built skills that others might find useful, the Bazaar is waiting.

Browse the Skills Directory

Find the right skill for your workflow. The OpenClaw Bazaar skills directory has over 2,300 community-rated skills — searchable, sortable, and free to install.

Browse Skills →

Try a Pre-Built Persona

Don't want to configure everything from scratch? OpenClaw personas come pre-loaded with skills, memory templates, and workflows designed for specific roles. Compare personas →