dceoy/ai-coding-agent-skills/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: sonnet | opus | haiku | 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/.

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

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

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

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

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

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

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

1. Extract helper scripts (optional):

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

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

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