claude-agent-converter

name	claude-agent-converter
description	Convert Claude Code subagents (.claude/agents/*.md) to standard Agent Skills (skills/*/SKILL.md). Use when migrating subagents to portable skill format, extracting reusable workflows from agents, or standardizing agent definitions across AI runtimes.

Claude Agent Converter

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

When to Use

• Migrating existing .claude/agents/*.md subagent files to skills/*/SKILL.md format.
• Extracting reusable workflows from subagent definitions.
• Creating portable skills from Claude Code-specific agents.
• Standardizing agent definitions for use with Claude Code, Codex CLI, Cursor CLI, and other runtimes.

Inputs

• Source agent file path (e.g., .claude/agents/my-agent.md).
• Optional: target skill name (defaults to agent name from frontmatter).
• Optional: mode to extract (if agent supports multiple modes).

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

Format Differences

Claude Code Subagent Format

Location: .claude/agents/<agent-name>.md

---
name: agent-name
description: When Claude should delegate to this subagent
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: fast | default | advanced | inherit
permissionMode: default | acceptEdits | dontAsk | bypassPermissions | plan
skills: skill-1, skill-2
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
---
[System prompt instructions for the subagent...]

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 1
- Output 2

Conversion Workflow

1. Read the source agent from .claude/agents/.

2. Analyze agent structure:

   • Identify if agent has multiple modes (e.g., ask, exec, review, search).
   • Determine if agent should become one skill or multiple skills.
   • Note tool restrictions for skill documentation.

3. Extract metadata:

   • name from YAML frontmatter.
   • description for triggering context.
   • tools and disallowedTools for capability constraints.
   • model preference if specified.
   • skills dependencies to reference.
   • hooks for validation logic to document.

4. Determine skill name(s):

   • Single-mode agent: use agent name directly.
   • Multi-mode agent: create separate skills per mode (e.g., agent-ask, agent-exec).
   • Use kebab-case for multi-word names.

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

6. Transform content to SKILL.md format:

   • Frontmatter: Keep only name and description.
   • Enhance description: Expand to include when to use the skill.
   • Extract "When to Use": From mode selection criteria in agent prompt.
   • Document Inputs: What information the skill needs to operate.
   • Structure Workflow: Convert agent instructions to numbered steps.
   • List Outputs: Expected artifacts or results.
   • Note Tool Usage: Document which tools the workflow uses.
   • Document Constraints: Read-only modes, permission requirements.

7. Handle multi-mode agents:

   • If agent has distinct modes (ask/exec/review/search), create separate skills.
   • Each skill gets the mode-specific workflow and constraints.
   • Shared context (CLI usage, verification) goes in each skill as needed.

Transformation Rules

Subagent Field	Skill Transformation
name	name in frontmatter
description	description expanded with usage triggers
tools	Documented in workflow (which tools are used)
disallowedTools	Documented as constraints (read-only, no modifications)
model	Noted in workflow if relevant (e.g., "use a fast model")
permissionMode	Documented as workflow constraints
skills	Referenced in "Related Skills" or workflow
hooks	Documented or extracted to scripts/
Mode sections	Separate skills or workflow phases
CLI command patterns	Included in workflow steps
Verification checklists	Included in workflow or outputs

Multi-Mode Agent Handling

When an agent has multiple modes (common pattern: ask, exec, review, search):

Option A: Separate Skills (Recommended)

Create one skill per mode:

• agent-ask - Read-only Q&A
• agent-exec - Code generation/modification
• agent-review - Code review
• agent-search - Web research

Benefits:

• Clear, focused skills.
• Appropriate constraints per skill.
• Easier to discover and use.

Option B: Single Skill with Modes

Keep as one skill if modes are tightly coupled:

• Document mode selection in workflow.
• Include all mode workflows.
• Clearly separate mode-specific sections.

Example Conversion

Input: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear  
      
   

Output: skills/code-reviewer/SKILL.md

---
name: code-reviewer
description: Expert code review specialist for quality, security, and maintainability analysis. Use when reviewing code changes, checking for security vulnerabilities, validating before commits, or assessing code quality.
---

# Code Reviewer

Perform thorough code reviews focusing on quality, security, and maintainability.

## When to Use

- Review code changes before committing.
- Check for security vulnerabilities.
- Validate code    
    



          
     

           




         
          
         


         
         
        


           
           
         


           
         
       


      
      



       
      
     
    



         
        



    
      

Multi-Mode Example

Input: Multi-mode agent with ask/exec/review/search

Create four separate skills:

1. skills/agent-ask/SKILL.md - Q&A mode content
2. skills/agent-exec/SKILL.md - Execution mode content
3. skills/agent-review/SKILL.md - Review mode content
4. skills/agent-search/SKILL.md - Search mode content

Each skill includes:

• Mode-specific description and triggers.
• Mode-specific workflow from agent prompt.
• Mode-specific constraints (read-only for ask/review/search).
• CLI command patterns for that mode.

Key Rules

• Preserve all workflow logic and instructions.
• Remove runtime-specific frontmatter fields (tools, model, permissions, hooks).
• Keep only name and description in skill frontmatter.
• Expand descriptions to include usage triggers.
• Use imperative voice in workflow steps.
• Convert tool restrictions to documented constraints.
• Keep skills self-contained and portable.
• Split multi-mode agents into focused skills.
• Don't add extraneous documentation files (README, CHANGELOG, etc.).

Next Steps

After conversion:

• Review generated SKILL.md for completeness.
• Verify workflow steps are clear and actionable.
• Check that constraints are documented accurately.
• Delete unused example files in scripts/, references/, assets/.
• Update AGENTS.md/CLAUDE.md skill inventory if applicable.
• Create symlinks for runtime integration if needed.