Migrate To Skills

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

Decision: Skill vs. Command vs. Rule

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

---
description: What this rule does
globs: **/*.ts
alwaysApply: false
---
# Title
Body content...

Target format

---
name: <kebab-name>
description: "<original description, expanded with WHEN trigger>"
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:

# 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

# Commit current work
Instructions here...

Target Option A: command (recommended for slash-invoked workflows)

# Commit current work
Instructions here...

Save to ~/.claude/commands/commit.md — invoked via /commit.

Target Option B: SKILL.md (recommended for knowledge / templates)

---
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/<name>/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/<name>.md (no frontmatter required, or minimal)
• Preserve body verbatim

If it's a domain-specific guide (loaded on-demand):

• Save as .claude/skills/<name>/SKILL.md with proper frontmatter

.agent/workflows/*.md → .claude/commands/*.md

These are workflow scripts (Torvaldsen-style). Save to .claude/commands/<name>.md for /<name> 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:

   # 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

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 — distributed by TomeVault.