Converting Claude Code Sub-Agents to Skills

Converting Claude Code Sub-Agents to Skills

This document provides detailed guidance on converting existing Claude Code sub-agent configurations to the Skills format.

Essential Reading

Before starting any conversion, review these official documentation sources:

undefined

Use WebFetch to access these URLs for the latest information.

Understanding the Differences

Sub-Agent Configuration

Sub-agents are defined in files (in `~/.claude/agents/` or `.claude/agents/`) with YAML frontmatter:

---
name: agent-name
description: What this agent does (for Task tool invocation)
tools: [optional tool restrictions]
model: sonnet|opus|haiku
---

Agent instructions and expertise...

**Key characteristics:**

undefined

**Example from Documentation - Code Reviewer:**

---
name: code-reviewer
description: Reviews code quality, checks security and best practices, provides prioritized feedback
model: sonnet
---

You are an expert code reviewer focusing on:
- Code quality and maintainability
- Security vulnerabilities
- Performance issues
- Best practices adherence

Review the code and provide clear, actionable feedback.

Skill Configuration

Skills are directories with a `SKILL.md` file:

---
name: skill-name
description: When to use this skill (triggers automatic invocation by Claude)
---

Skill instructions and expertise...

**Key characteristics:**

undefined

Key Transformation Steps

1. Description Transformation (MOST CRITICAL)

Sub-agent descriptions explain WHAT the agent does. Skill descriptions must explain WHEN to invoke.

**Transformation Formula:**

Sub-Agent: "Reviews code quality and provides feedback"
Skill: "Use this skill when reviewing code for quality issues, security vulnerabilities, performance problems, or best practices violations. This includes analyzing pull requests, auditing existing code, or validating new implementations."

**Guidelines:**

undefined

2. Name Transformation

**Sub-Agent Names** (t