How to Migrate from CLAUDE.md to Agent Skills [Step-by-Step Guide]
Using CLAUDE.md in your project and considering migrating to Agent Skills?
This article explains how to migrate from CLAUDE.md to Agent Skills and when to use each.
CLAUDE.md vs Agent Skills
CLAUDE.md
- Claude Code-specific configuration file
- Placed at project root
- Always loaded into context
- Best for project-specific rules and background info
Agent Skills
- Standard format working across multiple tools
- Loaded based on task (Progressive Disclosure)
- Packages specific workflows
- Easy to reuse and share
Comparison
| Aspect | CLAUDE.md | Agent Skills |
|---|---|---|
| Compatibility | Claude Code only | Multiple tools |
| Loading | Always | Per task |
| Use case | Project settings | Task-specific workflows |
| Sharing | Within project | Across projects/teams |
Should You Migrate?
Migrate When:
- Multi-tool use: Want same workflow in tools beyond Claude Code
- Reuse: Want same instructions across projects
- Team sharing: Want standardized workflows for the team
Keep CLAUDE.md When:
- Project-specific settings: Info only used in this project
- Constant reference needed: Background info needed for every task
- Simplicity: Want single-file management
Step-by-Step Migration
Step 1: Categorize Content
Classify existing CLAUDE.md content into two groups:
Keep in CLAUDE.md:
- Project overview and background
- Tech stack description
- Coding standards to always follow
- Environment-specific settings
Migrate to Skills:
- Code review procedures
- PR creation templates
- Test writing guidelines
- Task-specific workflows
Step 2: Create Skills
Extract migration targets into SKILL.md files.
Before (in CLAUDE.md):
## Code Review
When reviewing PRs, check these aspects:
1. Security
2. Performance
3. Maintainability
4. Test coverage
After (SKILL.md):
---
name: code-review
description: Review PR code for security, performance, and maintainability
---
## Steps
When reviewing PRs, check these aspects:
1. Security: SQL injection, XSS, auth issues
2. Performance: N+1 queries, unnecessary re-renders
3. Maintainability: complexity, naming, comments
4. Test coverage: tests for critical logic
Step 3: Place and Test
mkdir -p .claude/skills/code-review
# Place SKILL.md
Verify in Claude Code:
/code-review
Step 4: Clean Up CLAUDE.md
Remove migrated content from CLAUDE.md and add skill references:
# Project Overview
[Project description...]
## Available Skills
- `/code-review` - Code review
- `/pr-template` - PR creation
- `/test-generator` - Test generation
Migration Tips
Don't Migrate Everything at Once
Gradual migration makes troubleshooting easier.
- First, convert one workflow to a skill
- Use it for a while to verify no issues
- If good, migrate the next workflow
Write Descriptions Carefully
For auto-application, write specific descriptions:
# ❌ Vague
description: Check code
# ⭕ Specific
description: Review TypeScript PRs for security, performance, and type safety
Use Both Together
You don't need to fully migrate. Using CLAUDE.md and Agent Skills together is practical:
- CLAUDE.md: Project background, rules that need constant reference
- Agent Skills: Task-specific workflows
Summary
CLAUDE.md and Agent Skills each have their place.
- Project-specific settings → Keep in CLAUDE.md
- Reusable workflows → Migrate to Agent Skills
Migrate gradually to leverage the benefits of both.
Browse the Skills list for migration inspiration.
Related Articles
- How to Set Up Skills in Claude Code - Post-migration setup
- How to Create Your Own Skills - SKILL.md syntax
- How to Share Skills with Your Team - Team migration
- What Are Agent Skills? - Agent Skills basics