# Migrate To Skills > Migrate legacy rule/command files (Cursor .mdc rules, slash-command markdown, old-format skills) to Claude Code SKILL.md format. Use when consolidating cross-platform configs, importing Cursor or Antigravity workflows to Claude Code, or refactoring old rules into the skills/ directory. Use when this capability is needed. - Skill: `tomevault-io/migrate-to-skills-3` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/migrate-to-skills-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/migrate-to-skills-3/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/migrate-to-skills-3 --- # Migrate Legacy Configs to Claude Code Skills Convert rules and commands from Cursor (`.cursor/rules/*.mdc`, `.cursor/commands/*.md`), Antigravity (`.agent/`), or other tools into Claude Code Skills (`~/.claude/skills//SKILL.md`). **CRITICAL:** Preserve the exact body content. Do not modify, reformat, or "improve" it — copy verbatim. The migration is about restructuring metadata, not editing the content. ## Source → Target Mapping | Source | Target | |--------|--------| | `.cursor/rules/*.mdc` (Cursor "Applied intelligently" rules) | `.claude/skills//SKILL.md` | | `~/.cursor/rules/*.mdc` (user-level Cursor rules) | `~/.claude/skills//SKILL.md` | | `.cursor/commands/*.md` (Cursor slash commands) | `.claude/skills//SKILL.md` or `.claude/commands/.md` | | `~/.cursor/commands/*.md` (user-level Cursor commands) | `~/.claude/skills//SKILL.md` or `~/.claude/commands/.md` | | `.agent/rules/*.md` (Antigravity rules) | `.claude/rules/.md` (if always-load) or `.claude/skills//SKILL.md` | | `.agent/workflows/*.md` (Antigravity workflows) | `.claude/commands/.md` | ### Decision: Skill vs. Command vs. Rule | If the source is... | Target it as... | Why | |---------------------|-----------------|-----| | Workflow with steps (slash command) | `commands/.md` | Commands are invoked by `/` | | Specialized domain knowledge / template | `skills//SKILL.md` | Skills load on-demand with `Skill` tool | | Always-applicable principle | `rules/.md` | Rules auto-load every session | When in doubt: **commands for "do this workflow"**, **skills for "use this knowledge"**, **rules for "follow this principle"**. ## Cursor Rule Migration (.mdc → SKILL.md) ### Source format ```markdown --- description: What this rule does globs: **/*.ts alwaysApply: false --- # Title Body content... ``` ### Target format ```markdown --- name: description: "" context: fork model: sonnet allowed-tools: Read, Write, Edit, Glob, Grep --- # Title Body content... ``` ### Changes 1. Add `name` field (kebab-case from filename) 2. Add `context: fork` (Claude Code skills run in isolated context) 3. Add `model:` and `allowed-tools:` (sensible defaults based on the rule's purpose) 4. Remove `globs` and `alwaysApply` (not used in Claude Code skills — file matching is via description triggers) 5. **Preserve body verbatim** — no edits, no reformatting ### Glob Handling If the original rule had `globs: **/*.ts` (only applied to TypeScript files), translate to the description: ```yaml # Original globs: **/*.ts description: "TypeScript coding conventions" # Migrated description: "TypeScript coding conventions. Use when working with .ts or .tsx files." ``` ## Cursor Command Migration (.md → SKILL.md or command) ### Source ```markdown # Commit current work Instructions here... ``` ### Target Option A: command (recommended for slash-invoked workflows) ```markdown # Commit current work Instructions here... ``` Save to `~/.claude/commands/commit.md` — invoked via `/commit`. ### Target Option B: SKILL.md (recommended for knowledge / templates) ```markdown --- name: commit description: "Commit current work with standardized message format. Use when the user types /commit or asks to commit changes." context: fork model: haiku allowed-tools: Bash, Read, Grep --- # Commit current work Instructions here... ``` Save to `~/.claude/skills/commit/SKILL.md` — invoked via `Skill` tool. ### Changes 1. If Option A (command): keep filename, save to `commands/` — no frontmatter needed 2. If Option B (skill): add frontmatter, infer description from first heading + content, save to `skills//SKILL.md` 3. **Preserve body verbatim** ## Antigravity Migration (.agent → .claude) ### `.agent/rules/*.md` → `.claude/rules/*.md` If the rule should always-load: - Save as `.claude/rules/.md` (no frontmatter required, or minimal) - Preserve body verbatim If it's a domain-specific guide (loaded on-demand): - Save as `.claude/skills//SKILL.md` with proper frontmatter ### `.agent/workflows/*.md` → `.claude/commands/*.md` These are workflow scripts (Torvaldsen-style). Save to `.claude/commands/.md` for `/` invocation. ## Migration Workflow ### If you have the Agent tool available DO NOT read all the files yourself. Delegate to parallel subagents. 1. **Identify the categories**: project rules, user rules, project commands, user commands 2. **Dispatch parallel subagents** (one per category) to: I. Find files matching the source pattern II. Check filter criteria (rules: has `description`, no `globs`, no `alwaysApply: true`; commands: always migrate) III. List files to migrate IV. For each: read, write the new file preserving body EXACTLY, log the migration V. Optionally delete the original (only after confirmation) 3. **Wait for all subagents**, then summarize results 4. **Offer undo** — if the user wants to revert, do the reverse ### If working solo (no Agent tool) 1. **Find source files** using Glob: ```bash # Project rules find . -path '*/.cursor/rules/*.mdc' -type f # User rules find ~/.cursor/rules -name '*.mdc' -type f 2>/dev/null # Commands find . -path '*/.cursor/commands/*.md' -type f find ~/.cursor/commands -name '*.md' -type f 2>/dev/null ``` 2. **For each file**: a. Read the source b. Extract description from frontmatter (rules) or first heading (commands) c. Determine target: skill, command, or rule (see decision table above) d. Create target directory (`mkdir -p`) e. Write target file with new frontmatter + verbatim body f. Log the migration 3. **Optionally delete originals** — only after the user verifies the migration 4. **Summarize**: list of source → target pairs ## Filter Criteria (Cursor → Claude Code) ### Migrate Rules If - Has `description` field - Does NOT have `alwaysApply: true` (those are global Cursor rules, equivalent of Claude Code's auto-loaded `rules/`) - Does NOT have specific `globs` (those are file-type-specific; consider keeping in Cursor instead, or translate to skill description) ### Migrate Commands - All commands always migrate (they're plain markdown without frontmatter) ### Skip - `~/.cursor/skills-cursor/*` — these are Cursor's internal built-in skills, managed automatically (already done if you're reading this — those are the skills being ported) - `.cursor/worktrees/*` — temporary worktrees - `.git/` directories ## Naming Conventions - Skill name = filename without extension, converted to lowercase + hyphens - Examples: - `MyRule.mdc` → `my-rule` - `CodeReview.md` → `code-review` - `bootstrap-codebase.md` → `bootstrap-codebase` (already conformant) ## CRITICAL Rules 1. **Preserve body verbatim** — no edits, no fixes, no "improvements". Copy character-for-character. 2. **Use the read/write tools**, not terminal `cat`/`echo` — the tools are safer and clearer. 3. **Verify before deleting** originals — only delete after the user confirms migration works. 4. **Migrate atomically** — one file at a time, with logged success before moving to the next. 5. **Test triggers** — after migration, verify the new skill/command can be invoked. ## Undo Strategy If something goes wrong: 1. Originals are typically untouched until explicit deletion 2. If deleted, check backups: `/Volumes/NvME-Satechi/_claude-framework-backups/` (if you ran the consolidation) 3. To undo a single file: read the new SKILL.md, extract body, reconstruct original frontmatter (Cursor format), write back to original path 4. If unsure: STOP and ask the user — don't compound the error ## Quick Reference ### Cursor → Claude Code Frontmatter Translation | Cursor Field | Claude Code Equivalent | |--------------|------------------------| | `name:` | `name:` (same) | | `description:` | `description:` (same; may expand with WHEN triggers) | | `globs:` | (removed — encode in description if needed) | | `alwaysApply: true` | (moved to `rules/` directory; no equivalent field) | | `disable-model-invocation: true` | (not needed — skills aren't auto-invoked in Claude Code unless description triggers match) | | — | `context: fork` (new — controls context isolation) | | — | `model: haiku\|sonnet\|opus` (new — preferred model) | | — | `allowed-tools: ...` (new — tool allowlist) | ## Related Skills - `[[create-skill]]` — for authoring new skills from scratch - `[[create-rule]]` — for authoring new always-loaded rules - `[[create-hook]]` — for hook scripts - `[[create-subagent]]` — for subagent definitions --- > Source: [emanuelrechsteiner/claude-code-framework](https://github.com/emanuelrechsteiner/claude-code-framework) — distributed by [TomeVault](https://tomevault.io).