Claude Command Converter

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).

Format Differences

Claude Code Command Format

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

---
description: Short description of the command
handoffs:
  - label: Next Action
    agent: other.command
    prompt: Trigger prompt
    send: true
---
## User Input

\`\`\`text
$ARGUMENTS
\`\`\`

[Command instructions...]

Standard Agent Skill Format

skills/<skill-name>/SKILL.md

---
name: skill-name
description: Complete description including what the skill does and when to use it.
---

# Skill Title

## When to Use

- Scenario 1
- Scenario 2

## Inputs

- Required input 1
- Optional input 2

## Workflow

1. Step 1
2. Step 2
...

## Outputs

- Output file 1
- Output file 2

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

$ARGUMENTS

handoffs:

/command.name

skill-name

agent: foo.bar

foo-bar

description:

description:

## User Input

Example Conversion

.claude/commands/speckit.specify.md

---
description: Create feature specification from natural language.
handoffs:
  - label: Build Technical Plan
    agent: speckit.plan
---
## User Input

\`\`\`text
$ARGUMENTS
\`\`\`

The text the user typed after `/speckit.specify`...

skills/speckit-specify/SKILL.md

---
name: speckit-specify
description: Create or update a feature specification from a natural language feature description.
---

# Spec Kit Specify Skill

## When to Use

- The user wants a new or updated feature spec from a natural language description.

## Inputs

- Feature description from the user.
- Repo context with `.specify/` scripts and templates.

If the description is missing or unclear, ask a targeted question before continuing.

## Workflow

...

## Outputs

- `specs/<feature>/spec.md`
- `specs/<feature>/checklists/requirements.md`

## Next Steps

After generating spec.md:

- **Plan** technical implementation with speckit-plan.
- **Clarify** specification requirements with speckit-clarify.

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

• 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.