claude-command-converter

name	claude-command-converter
description	Convert Claude Code commands (.claude/commands/*.md) to standard Agent Skills (skills/*/SKILL.md). Use when migrating slash commands to portable skill format, creating skills from existing commands, or standardizing command definitions across AI runtimes.

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, Cursor CLI, 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
    prompt: Trigger prompt
    send: true
---
## User Input

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

[Command instructions...]

Standard Agent Skill Format

Location: 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

Claude Command	Agent Skill
$ARGUMENTS	Inputs section describing expected user input
handoffs:	Next Steps section with skill references
/command.name	skill-name (kebab-case)
agent: foo.bar	foo-bar skill reference
description: in frontmatter	description: expanded with triggers
Inline ## User Input	Removed; documented in Inputs

Example Conversion

Input: .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`...

Output: 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

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.