Agent Skills: Convert to Skills

Convert to Skills

Convert legacy agent resources to the unified Agent Skills format.

Workflow

Execute these phases in order. Always get user approval before making changes.

Phase 1: Discovery

Search for legacy resources. Run these searches immediately:

# Subagents
find . -path "*/.claude/agents/*.md" -o -path "*/.cursor/agents/*.md" -o -path "*/.codex/agents/*.md" 2>/dev/null

# Commands  
find . -path "*/.claude/commands/*.md" -o -path "*/.cursor/commands/*.md" -o -path "*/.codex/commands/*.md" 2>/dev/null

# Rules
find . -path "*/.claude/rules/*.md" -o -path "*/.cursor/rules/*.mdc" -o -path "*/.cursor/rules/*.md" 2>/dev/null

# Custom Prompts (Codex)
find . -path "*/.codex/prompts/*.md" 2>/dev/null

# AGENTS.md files
find . -name "AGENTS.md" 2>/dev/null

If $1 specifies a path, only scan that location.

Phase 2: Classification

Read each discovered file and classify it. Present findings as:

## Discovery Results

### Subagents (X found)
| File | Name | Recommended Action |
|------|------|-------------------|
| .claude/agents/reviewer.md | reviewer | Convert to skill |

### Commands (X found)
| File | Name | Recommended Action |
|------|------|-------------------|
| .claude/commands/test.md | test | Convert to skill |

### Rules (X found)
| File | Name | Type | Recommended Action |
|------|------|------|-------------------|
| .cursor/rules/style.mdc | style | always-apply | Import to CLAUDE.md |
| .cursor/rules/react.mdc | react | glob-scoped | Keep as rule |
| .claude/rules/security.md | security | knowledge | Convert to skill |

### Already Skills (No Action)
- .claude/skills/existing/ ✓

### Needs Manual Review
- [file]: [reason]

Rule classification logic:

• alwaysApply: true → Import to CLAUDE.md via @import
• Has globs pattern → Keep as rule (skills don't support glob activation)
• General knowledge → Convert to skill

Phase 3: Approval

Ask user:

"Found X resources to convert. Proceed with conversion? [Y/n/customize]"

If "customize": Let user select specific items or modify actions.

Phase 4: Conversion

For each approved conversion, apply the appropriate mapping:

Subagent → Skill:

• Add context: fork (required for subagent behavior)
• Simplify model names (see field-mappings.md)
• Keep allowed-tools
• Enhance description with trigger keywords

Command → Skill:

• Add disable-model-invocation: true
• Keep argument-hint
• Document $ARGUMENTS, $1, $2 usage

Rule → Skill (knowledge type only):

• Write description with auto-trigger keywords
• No disable-model-invocation (allow auto-activation)

Rule → CLAUDE.md (always-apply):

• Add @import path/to/rule.md to CLAUDE.md

Create skill structure:

.claude/skills/{name}/
├── SKILL.md
├── scripts/      # If original has executables
├── references/   # If original has docs
└── assets/       # If original has templates

Phase 5: Verification

After conversion, run:

# List created skills
ls -la .claude/skills/

# Verify frontmatter
for skill in .claude/skills/*/SKILL.md; do
  echo "=== $skill ===" && head -20 "$skill"
done

Present summary:

## Conversion Complete

### Created Skills
| Skill | Location | Source |
|-------|----------|--------|
| reviewer | .claude/skills/reviewer/ | .claude/agents/reviewer.md |

### Updated Files
- CLAUDE.md: Added 2 @import statements

### Verification
- [x] All skills have valid frontmatter
- [x] Names match directory names
- [x] No duplicate skills

Phase 6: Cleanup (Optional)

Ask user:

"Delete original files? [y/N/archive]"

• y: Delete originals
• N: Keep originals (default)
• archive: Move to .claude/archive/

Quick Reference

Key Conversion Rules

| Source Type | Target | Key Addition | |-------------|--------|--------------| | Subagent | Skill | context: fork | | Command | Skill | disable-model-invocation: true | | Rule (knowledge) | Skill | Trigger keywords in description | | Rule (always-apply) | CLAUDE.md | @import statement | | Rule (glob-scoped) | Keep as rule | No conversion needed |

Model Mapping

| Legacy | Skills | |--------|--------| | claude-opus-4-* | opus | | claude-sonnet-4-* | sonnet | | claude-3-5-haiku-* | haiku | | inherit / omitted | (omit) |

Tool Mapping

| Variations | Standard | |------------|----------| | read, ReadFile, file_read | Read | | write, WriteFile | Write | | bash, Terminal, Shell | Bash | | grep, Search | Grep | | glob, Find, list_files | Glob |

Reference Files

For detailed specifications, read these on-demand:

• references/spec-reference.md - Full Agent Skills specification
• references/field-mappings.md - Complete field conversion tables
• references/examples.md - Before/after conversion examples

Troubleshooting

| Issue | Solution | |-------|----------| | Skill not discovered | Check: name matches directory, valid YAML frontmatter | | Triggers too often | Add disable-model-invocation: true | | Doesn't auto-trigger | Remove disable-model-invocation, add keywords to description | | Subagent behavior changed | Ensure context: fork is present | | Hooks not working | Requires Claude Code 2.1+ |