claude-command-converter

Claude Command Converter

Convert Claude Code commands to standard Agent Skills format for portability across AI coding assistants.

When to Use

• Migrating existing .claude/commands/*.md files to skills/*/SKILL.md format.
• Creating portable skills from Claude Code-specific commands.
• Standardizing command definitions for use with Claude Code, Codex CLI, GitHub Copilot, and other runtimes.

Inputs

• Source command file path (e.g., .claude/commands/my-command.md).
• Optional: target skill name (defaults to command filename without extension).

If input is missing, ask for the source command file path.

Format Differences

Claude Code Command Format

Location: .claude/commands/<command-name>.md

---
description: Short description of the command
handoffs:
  - label: Next Action
    agent: other.command

Standard Agent Skill Format

Location: skills/<skill-name>/SKILL.md

Conversion Workflow

1. Read the source command from .claude/commands/.

2. Extract metadata:

   • description from YAML frontmatter.
   • handoffs for related skills/next steps.
   • $ARGUMENTS handling for inputs.

3. Determine skill name:

   • Convert command.name.md → command-name (replace dots with hyphens).
   • Use kebab-case for multi-word names.

4. Create skill directory: skills/<skill-name>/

5. Transform content to SKILL.md format:

   • Frontmatter: Keep name and description only.
   • Enhance description: Expand to include when to use the skill.
   • Convert $ARGUMENTS: Document as Inputs section.
   • Structure workflow: Extract steps into numbered Workflow section.
   • Add "When to Use": Derive from command context and description.
   • Add "Outputs": List generated files/artifacts.
   • Convert handoffs: Add "Next Steps" section referencing related skills.

6. Remove runtime-specific content:

   • Remove ## User Input section with $ARGUMENTS block.
   • Remove handoffs from frontmatter (move to prose).
   • Remove /command.name references (use skill names instead).

7. Validate skill structure:

   • Frontmatter has name and description only.
   • Body has clear sections (When to Use, Inputs, Workflow, Outputs).
   • No TODO placeholders remain.
   • No runtime-specific variables like $ARGUMENTS.

8. Report conversion result:

   • Source command path.
   • Generated skill path.
   • Key transformations applied.
   • Manual review recommendations.

Transformation Rules

Example Conversion

Input: .claude/commands/speckit.specify.md

Output: skills/speckit-specify/SKILL.md

Key Rules

• Preserve all workflow logic and instructions.
• Remove runtime-specific constructs ($ARGUMENTS, handoffs, /slash-commands).
• Expand terse descriptions to include usage triggers.
• Use imperative voice in workflow steps.
• Keep skills self-contained and portable.
• Don't add extraneous documentation files (README, CHANGELOG, etc.).

Next Steps

After conversion:

• Review generated SKILL.md for completeness.
• Delete unused example files in scripts/, references/, assets/.
• Update AGENTS.md/CLAUDE.md skill inventory if applicable.
• Create symlinks for runtime integration if needed.