Subagentes y Skills de Claude Code: guía en español [2026]
Un subagente de Claude Code es un asistente de IA especializado que el agente principal invoca para ejecutar una tarea concreta en su propia ventana de contexto: recibe el encargo, trabaja de forma independiente con las herramientas que le permitiste, y devuelve solo el resultado, sin contaminar la conversación principal. Una skill es un archivo SKILL.md con instrucciones que amplía lo que Claude sabe hacer: la creás una vez y Claude la carga automáticamente cuando es relevante, o la invocás directo con /nombre-de-la-skill.
Son las dos piezas centrales para pasar de "usar Claude Code" a "operar un sistema con Claude Code", y casi todo el contenido que las explica bien está en inglés. Esta guía las cubre en español. No escribimos desde la teoría: en Duotach operamos un sistema interno con 53 skills, de las cuales 9 son validadores y 5 son orquestadores (acá está el caso documentado). Todo lo técnico está verificado contra la documentación oficial de Claude Code en español.
Qué es un subagente en Claude Code
Un subagente es una instancia separada de Claude que el agente principal invoca para delegar un tipo específico de tarea. Según la documentación oficial, cada subagente se ejecuta en su propia ventana de contexto, con un mensaje de sistema propio, acceso a herramientas específicas y permisos independientes. Cuando Claude encuentra una tarea que coincide con la description de un subagente, delega en él; el subagente trabaja solo y devuelve el resultado resumido.
El beneficio principal es la preservación de contexto. Si una tarea secundaria va a inundar tu conversación con resultados de búsqueda, logs o contenido de archivos que no vas a volver a mirar, ese trabajo va a un subagente: el ruido queda en su ventana, y a tu conversación principal vuelve solo la conclusión.
Preservar contexto
Exploración e investigación fuera de la conversación principal.
Aplicar restricciones
Limitar qué herramientas puede usar (por ejemplo, un revisor de código de solo lectura).
Reutilizar configuraciones
Subagentes a nivel de usuario disponibles en todos tus proyectos.
Dónde viven los subagentes
Un subagente es un archivo Markdown con frontmatter YAML. La ubicación define su alcance, y cuando dos comparten nombre gana el de mayor prioridad:
| Ubicación | Alcance | Prioridad |
|---|---|---|
| Configuración administrada (enterprise) | Toda la organización | 1 (más alta) |
| Bandera CLI --agents (JSON al lanzar) | Sesión actual | 2 |
| .claude/agents/ | Proyecto actual | 3 |
| ~/.claude/agents/ | Todos tus proyectos | 4 |
| Directorio agents/ de un plugin | Donde el plugin está habilitado | 5 (más baja) |
Los subagentes de proyecto (.claude/agents/) se commitean al repositorio: así todo el equipo los usa y los mejora con control de versiones. Los de usuario (~/.claude/agents/) son personales y viajan con vos entre proyectos.
El frontmatter de un subagente
Cuatro campos definen el comportamiento: name, description, tools y model. Un subagente revisor de código, tomado del tutorial oficial, se ve así:
--- name: code-improver description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code. tools: Read, Grep, Glob model: sonnet --- You are a code improvement specialist. For each issue you find, explain the problem, show the current code, and provide an improved version.
La description es el mecanismo de disparo automático: Claude la lee para decidir cuándo delegar. Una description vaga produce un subagente que nunca se invoca (o se invoca cuando no corresponde).
tools es tu control de seguridad. Un subagente de investigación no necesita Write ni Bash; dárselo es riesgo gratis.
Nota de versión: desde Claude Code v2.1.198, el comando /agents ya no abre el asistente interactivo de creación; la forma recomendada es pedirle a Claude que escriba el archivo, o editarlo directamente en .claude/agents/. Los archivos, campos y ubicaciones no cambiaron.
Qué es una skill (y el archivo SKILL.md)
Una skill es un directorio con un archivo SKILL.md que empaqueta conocimiento procedimental: instrucciones, checklists, formatos de salida, material de referencia. Claude la carga automáticamente cuando el pedido coincide con su description, o la invocás vos con /nombre-de-la-skill. La documentación oficial de skills da el criterio de creación exacto: creá una skill cuando te encuentres pegando el mismo manual o procedimiento de varios pasos en el chat una y otra vez, o cuando una sección de tu CLAUDE.md dejó de ser un hecho y se convirtió en un procedimiento.
La diferencia clave con CLAUDE.md es la carga diferida: el contenido de CLAUDE.md entra al contexto en cada sesión, mientras que el cuerpo de una skill se carga solo cuando se usa. En palabras de la doc oficial: "el material de referencia largo cuesta casi nada hasta que lo necesita". Eso convierte a las skills en el lugar correcto para procedimientos extensos que no querés pagar en tokens todo el tiempo.
Un dato que confunde a muchos: los comandos personalizados se fusionaron con las skills. Un archivo en .claude/commands/deploy.md y una skill en .claude/skills/deploy/SKILL.md crean ambos /deploy y funcionan igual; las skills agregan archivos de apoyo, frontmatter de control de invocación y carga automática.
Estructura de una skill
mi-skill/ ├── SKILL.md # instrucciones principales (obligatorio) ├── references/ # documentación de referencia detallada ├── assets/ # plantillas, ejemplos de salida └── scripts/ # scripts que Claude puede ejecutar
Solo SKILL.md es obligatorio. El resto es material que Claude carga bajo demanda si el SKILL.md lo referencia. El consejo oficial: mantené el SKILL.md por debajo de 500 líneas y mové el detalle a archivos separados.
Dónde viven las skills
| Nivel | Ubicación | Alcance |
|---|---|---|
| Enterprise | Configuración administrada | Toda la organización |
| Personal | ~/.claude/skills/<nombre>/SKILL.md | Todos tus proyectos |
| Proyecto | .claude/skills/<nombre>/SKILL.md | Solo ese proyecto |
| Plugin | <plugin>/skills/<nombre>/SKILL.md | Donde el plugin está habilitado |
Si dos skills comparten nombre, enterprise pisa a personal y personal pisa a proyecto. El nombre del comando sale del nombre del directorio: .claude/skills/deploy-staging/SKILL.md se invoca como /deploy-staging. Las ediciones a una skill existente surten efecto en la sesión actual sin reiniciar.
El frontmatter de una skill
| Campo | Para qué sirve |
|---|---|
| name | Etiqueta visible en los listados (el comando sale del directorio) |
| description | Cómo decide Claude cuándo cargar la skill automáticamente |
| disable-model-invocation: true | Solo vos podés invocarla. Para flujos con efectos secundarios (deploy, envíos) donde no querés que Claude decida el momento |
| user-invocable: false | Solo Claude puede invocarla. Para conocimiento de fondo que no tiene sentido como comando |
| arguments | Argumentos nombrados que se expanden como $nombre en el cuerpo |
Los dos campos de control de invocación son de las herramientas más subestimadas: separan "conocimiento que Claude aplica cuando corresponde" de "acciones que solo un humano dispara". En nuestro sistema, todo lo que toca dinero o comunicación con clientes es invocación manual.
Subagente o skill: cuándo usar cada uno
La regla corta: una skill define QUÉ saber hacer; un subagente define QUIÉN lo hace y con qué contexto. No compiten, se complementan.
| Criterio | Skill | Subagente |
|---|---|---|
| Qué es | Conocimiento procedimental (SKILL.md) | Instancia de Claude con contexto propio |
| Cuándo conviene | Procedimiento repetido, formato de salida fijo, checklist | Tarea que genera mucho ruido de contexto, o que requiere herramientas/permisos restringidos |
| Contexto | Se carga en tu conversación al usarse | Ventana de contexto separada |
| Costo en tokens | Cero hasta que se usa; luego queda en contexto la sesión | El trabajo pesado queda fuera de tu ventana |
| Ejemplo típico | “Todo reporte mensual sigue este formato” | “Investigá estos 20 resultados y traeme un resumen” |
| Señal de que lo necesitás | Pegás el mismo procedimiento en el chat otra vez | Tu conversación se llena de logs y búsquedas que no releés |
Y la jugada que la documentación habilita y casi nadie usa: combinarlos. Una skill puede ejecutarse dentro de un subagente, y un subagente puede tener skills precargadas. El procedimiento vive en la skill (versionado, editable, compartido por el equipo) y la ejecución sucia sucede en el subagente (sin contaminar tu contexto). Esa combinación es la base de cualquier sistema serio con Claude Code.
Cómo se combinan en producción: nuestro sistema de 53 skills
Lo anterior es la mecánica. Lo que sigue es lo que aprendimos operando esto en serio: en Duotach construimos un sistema interno sobre Claude Code para entregar servicios de SEO y GEO a múltiples clientes, y su estado actual es de 53 skills en producción. La arquitectura tiene tres capas:
Skills de trabajo
Cada tarea repetible del servicio es una skill: auditar un sitio, analizar una SERP, escribir un brief, redactar un artículo, monitorear menciones en LLMs, analizar un lead entrante. Cada una define entrada, procedimiento y formato de salida.
Validadores
Skills cuyo único trabajo es auditar el output de otra skill contra una rúbrica fija y devolver violaciones por severidad. Un artículo, un análisis de pricing o una propuesta comercial no se dan por terminados hasta que su validador devuelve cero blockers. Este artículo que estás leyendo pasó por ese loop.
Orquestadores
Skills que encadenan a las demás en pipelines completos (por ejemplo: análisis SERP → brief → redacción → optimización GEO → validación), delegando pasos a subagentes para no quemar el contexto de la sesión principal.
El patrón que hace que esto funcione no es la cantidad de skills sino el loop cerrado: cada pieza de trabajo pasa por un validador con una condición de corte objetiva antes de avanzar. Sin esa capa, un sistema de agentes produce volumen, no calidad. Con ella, el criterio de "esto está bien" deja de vivir en la cabeza de una persona y pasa a estar versionado en el repositorio.
El sistema completo, con resultados, está documentado en nuestro caso de éxito, y la introducción general a los agentes está en la guía de agentes IA con Claude Code.
Errores comunes al crear subagentes y skills
Los que vimos (y cometimos) construyendo el sistema:
Descriptions vagas. “Ayuda con el código” no le dice a Claude cuándo invocar. La description debe describir la situación de disparo: “Use after writing or modifying code”.
Skills kilométricas. Si tu SKILL.md pasa las 500 líneas, el material de referencia va a references/ y se carga bajo demanda. Una vez cargada, la skill queda en contexto toda la sesión: cada línea es costo recurrente.
Subagentes con todas las herramientas. Un subagente de solo lectura con acceso a Write y Bash es un incidente esperando turno. Dale el mínimo que necesita.
Todo automático. Acciones con efectos secundarios (deploys, envíos, publicaciones) van con disable-model-invocation: true. Que Claude sepa hacer algo no significa que deba decidir cuándo.
Meter procedimientos en CLAUDE.md. Si es un procedimiento y no un hecho del proyecto, es una skill: se versiona igual y no paga tokens en cada sesión.
Skills sin validador. El error de arquitectura más caro. Una skill que produce entregables sin otra que los audite escala la producción de errores. Nuestro ratio actual es aproximadamente un validador cada cuatro skills de trabajo.
No commitear los subagentes de proyecto. .claude/agents/ y .claude/skills/ en el repo convierten el criterio del equipo en un activo compartido y versionado. Fuera del repo, cada uno reinventa lo suyo.
Paso a paso: tu primera skill y tu primer subagente
Mínimo reproducible, verificado contra la documentación oficial.
Tu primera skill (5 minutos)
- Creá el directorio:
mkdir -p ~/.claude/skills/resumen-cambios - Guardá esto en
~/.claude/skills/resumen-cambios/SKILL.md:
--- description: Resume los cambios recientes del repositorio en lenguaje claro. Usar cuando pidan un resumen de qué cambió. --- Revisá los últimos commits con git log y resumí los cambios en 3-5 bullets en español, agrupados por área. Cerrá con una línea sobre qué convendría revisar con más atención.
Invocala con /resumen-cambios, o pedile a Claude "resumime qué cambió" y va a cargarla sola por la description.
Tu primer subagente (5 minutos)
- En Claude Code, pedilo en lenguaje natural: "Creá un subagente revisor en .claude/agents/ que revise código en busca de problemas de legibilidad y seguridad. Solo lectura, con las herramientas Read, Grep y Glob."
- Claude escribe el archivo con name, description, tools y el mensaje de sistema. Revisá el frontmatter antes de usarlo.
- Probalo: "Usá el subagente revisor sobre este proyecto". Si no lo encuentra y el directorio .claude/agents/ no existía al iniciar la sesión, reiniciá Claude Code.
A partir de ahí, el camino es incremental: cada vez que repitas un procedimiento, skill nueva; cada vez que una tarea ensucie tu contexto, subagente nuevo; cada vez que una skill produzca entregables importantes, validador que la audite.
Qué significa esto para una empresa
Para un equipo que ya usa Claude (no solo developers), skills y subagentes son la diferencia entre "cada persona chatea con la IA a su manera" y "la empresa tiene procedimientos versionados que la IA ejecuta igual todas las veces". El manual de calidad deja de ser un PDF que nadie abre y pasa a ser una skill que se aplica sola en cada tarea.
En Duotach trabajamos esto por dos vías:
Capacitación de equipos en Claude: programas donde el equipo aprende a trabajar ordenado con Claude sobre sus propios casos reales, incluyendo cómo convertir sus procedimientos en skills.
Builds a medida: diseñamos y construimos sistemas de agentes con esta arquitectura (skills + validadores + orquestadores) para operaciones específicas del cliente.
Si estás evaluando esto para tu equipo, escribinos y lo conversamos sobre tu caso concreto. Y si recién llegás a Claude Code, empezá por la guía de precios y uso en Argentina.
Preguntas Frecuentes
¿Cuál es la diferencia entre un subagente y una skill?+
¿Las skills gastan tokens aunque no se usen?+
¿Dónde se guardan los subagentes y las skills?+
¿Puedo evitar que Claude dispare una skill automáticamente?+
¿Sirven para trabajo que no es programación?+
¿Qué aprendo primero: MCP, skills o subagentes?+
¿Listos para operar con Claude Code?
¿Querés un sistema de skills y subagentes para tu operación?
Capacitamos equipos para trabajar ordenado con Claude y construimos sistemas de agentes a medida con la arquitectura de este artículo. Reunión inicial sin cargo, implementación cotizada por scope.
Artículos Relacionados
Agentes IA con Claude Code: la guía completa
Qué es un agente, cómo se construye con Claude Code y qué puede automatizar en tu empresa.
Claude Code en Argentina: guía de desarrollo y automatización
Qué es Claude Code, cuánto cuesta y cómo lo usamos para construir software y automatizaciones.
Capacitación en Claude para empresas
Cómo se estructura un programa de capacitación en Claude que termina en adopción real.
Duotach es una consultora de automatización e inteligencia artificial de Buenos Aires que construye sistemas de agentes con Claude Code para clientes de Argentina, México y España. Este artículo fue producido y validado con el sistema de skills que describe.