Claude Agent Converter

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.

8. Remove runtime-specific content:

   • Remove tools, disallowedTools, model, permissionMode from frontmatter.
   • Remove skills and hooks from frontmatter.
   • Convert tool restrictions to prose documentation.
   • Replace runtime-specific variables with documented inputs.

9. Extract helper scripts (optional):

   • If agent uses hook scripts, consider including in scripts/.
   • If agent references validation logic, document or include it.

10. Validate skill structure:

    • Frontmatter has only name and description.
    • Body has clear sections (When to Use, Inputs, Workflow, Outputs).
    • No TODO placeholders remain.
    • No runtime-specific fields in frontmatter.

11. Report conversion result:

    • Source agent path.
    • Generated skill path(s).
    • Key transformations applied.
    • Multi-mode handling decisions.
    • Manual review recommendations.

Transformation Rules

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 and readable
- No exposed secrets or API keys
- Proper error handling
...

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 quality and best practices.
- Assess maintainability of changes.

## Inputs

- Scope of review (uncommitted changes, specific commit, PR, or files).
- Focus area (comprehensive, security-focused, performance-focused).

If scope is unclear, default to reviewing uncommitted changes with `git diff`.

## Workflow

1. **Determine scope**:
   - Run `git diff` for uncommitted changes.
   - Run `git diff HEAD~1` for last commit.
   - Run `git diff main...branch` for PR.

2. **Gather context**:
   - Check `git status` for changed files.
   - Read modified files to understand changes.
   - Identify related code and patterns.

3. **Review for issues**:
   - **Critical**: Security vulnerabilities, runtime errors, data loss risks.
   - **Important**: Logic bugs, performance problems, error handling gaps.
   - **Suggestions**: Code quality, refactoring opportunities, documentation.

4. **Document findings**:
   - Prioritize by severity (Critical → Important → Suggestions).
   - Include file path and line numbers.
   - Provide specific fix examples.

5. **Include positive observations**:
   - Note well-implemented patterns.
   - Acknowledge good practices.

## Outputs

- Review summary with issue counts by severity.
- Detailed issue list with file:line references.
- Fix suggestions with code examples.
- Positive observations for reinforcement.

## Constraints

- **Read-only**: Do not modify code, only analyze and suggest.
- **Tools used**: Read, Grep, Glob, Bash (for git commands).

## Related Skills

- `code-exec` for implementing fixes.
- `code-ask` for understanding code before review.

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.