CLAUDE IA: Skills y Subagentes, la guía completa para enseñarle conocimiento a Claude y delegarle tareas (Sesión 5)

La quinta sesión del curso deja el terreno visual de Claude Design y vuelve al corazón de Claude Code, pero para abrir una puerta nueva: cómo enseñarle a Claude conocimiento que se reutiliza solo, y cómo delegarle tareas completas a asistentes que trabajan en su propio espacio, sin saturar la conversación principal. Son las Habilidades (Skills) y los Subagentes, dos mecanismos de personalización que resuelven problemas muy distintos y que, combinados, cambian la forma en que se usa Claude Code para trabajo serio y repetitivo. Aquí va el resumen completo de la sesión, con ejemplos, tablas y el contexto que la rodea.

1. ¿Qué son las habilidades?

Una habilidad (Skill) es una carpeta de instrucciones y recursos que Claude Code puede descubrir y usar por su cuenta para ejecutar tareas con mayor precisión. No es un plugin que se activa manualmente ni un comando que hay que recordar escribir: es conocimiento que Claude consulta solo, en el momento justo.

Cada habilidad vive en un archivo SKILL.md, con metadatos (name y description) en la parte superior y las instrucciones completas debajo. Claude compara la descripción de cada habilidad disponible con lo que el usuario está pidiendo y activa la que coincide semánticamente, sin que nadie tenga que invocarla por nombre.

La parte más importante para entender el diseño: las habilidades se cargan bajo demanda. Al iniciar una conversación, Claude solo lee los nombres y las descripciones de todas las habilidades disponibles — nunca el contenido completo de entrada. El cuerpo de instrucciones solo entra a la ventana de contexto cuando Claude decide que esa habilidad concreta aplica.

Regla práctica: si te encuentras explicándole lo mismo a Claude una y otra vez, esa es una habilidad que todavía no has escrito.

2. ¿Dónde residen las habilidades?

Las habilidades pueden guardarse en dos lugares, y la diferencia importa para decidir dónde escribir cada una:

Ámbito	Ubicación	Uso típico
Personales	~/.claude/skills (en Windows, C:/Users/<usuario>/.claude/skills)	Te acompañan en todos tus proyectos: tu estilo de commits, tu formato de documentación
De proyecto	.claude/skills dentro del repositorio	Estándares de equipo, guías de marca, fuentes y colores corporativos

Las habilidades de proyecto se integran al control de versiones junto con el código: cualquiera que clone el repositorio obtiene automáticamente las habilidades del proyecto, sin instalación adicional. Nadie tiene que acordarse de configurar nada; simplemente heredan el mismo conocimiento que el resto del equipo.

3. Habilidades vs. CLAUDE.md vs. comandos slash

Claude Code ofrece tres mecanismos distintos para darle contexto o instrucciones adicionales, y es fácil confundirlos porque los tres modifican el comportamiento de Claude. La diferencia está en cuándo se cargan y para qué sirve mejor cada uno:

Mecanismo	¿Cuándo se carga?	Mejor para
CLAUDE.md	Siempre, en cada conversación	Estándares del proyecto y restricciones permanentes
Habilidades (Skills)	Bajo demanda, por coincidencia semántica con tu solicitud	Experiencia específica para una tarea concreta
Comandos slash ( / )	Solo cuando el usuario los escribe explícitamente	Acciones puntuales invocadas a propósito

En otras palabras: CLAUDE.md es la regla que nunca se apaga, la habilidad es el especialista que aparece cuando hace falta, y el comando slash es el botón que solo se aprieta cuando alguien decide apretarlo.

4. ¿Cuándo usar habilidades?

Los casos de uso más comunes que se plantearon en la sesión son bastante concretos: estándares de revisión de código que sigue el equipo, formatos preferidos de mensajes de commit o de descripción de pull request, directrices de marca de la organización, plantillas de documentación para tipos específicos de documentos, y checklists para depurar frameworks o tecnologías específicas.

La regla general es sencilla: si repites la misma explicación en cada conversación, conviértela en una habilidad.

5. Creando tu primera habilidad

¿Por qué? una habilidad personal de "descripción de PR" evita repetir el mismo formato cada vez que pides una revisión de cambios.

El flujo de trabajo para crear una habilidad desde cero tiene cuatro pasos:

Paso	Acción
1	mkdir -p ~/.claude/skills/pr-description — crea el directorio con el nombre exacto de la habilidad.
2	Crea un archivo SKILL.md con name y description en el encabezado (front matter), separado por guiones.
3	Debajo del segundo bloque de guiones, escribe las instrucciones: el formato deseado, la lista de verificación, etc.
4	Reinicia Claude Code y confirma que la habilidad aparece en la lista de habilidades disponibles.

Pruébala pidiendo: "escribe una descripción de PR para mis cambios" — Claude debe indicar que está usando la habilidad y seguir tu plantilla.

6. Campos del encabezado de SKILL.md

El encabezado (front matter) de un SKILL.md solo tiene dos campos obligatorios, pero admite otros dos que le dan control adicional:

Campo	¿Obligatorio?	Función
name	Sí	Identifica la habilidad: minúsculas, números y guiones; máx. 64 caracteres; coincide con el nombre del directorio.
description	Sí	Máx. 1024 caracteres. Es el criterio que usa Claude para decidir cuándo activar la habilidad.
allowed-tools	No	Restringe qué herramientas puede usar Claude mientras la habilidad está activa.
model	No	Especifica qué modelo de Claude ejecuta la habilidad.

7. Cómo escribir descripciones efectivas

La descripción es el único texto que Claude carga al inicio de cada conversación para decidir si una habilidad aplica, así que su redacción determina si la habilidad se activa cuando debería. Una buena descripción responde dos preguntas a la vez: ¿qué hace la habilidad? y ¿cuándo debería usarla Claude?

Sé explícito: "ayuda con documentos" no es suficiente — Claude necesita el mismo nivel de detalle que necesitaría una persona para saber si esa herramienta le sirve. Si la habilidad no se activa cuando esperas, agrega frases que coincidan con cómo realmente formulas tus solicitudes en el día a día.

Ejemplo de frases disparadoras a probar: "ayúdame a analizar esto", "¿por qué es lento?", "haz que esto sea más rápido".

8. Restringir herramientas con allowed-tools

El campo allowed-tools es útil para flujos de solo lectura o de alta seguridad, donde Claude no debe editar ni escribir nada mientras esa habilidad está activa. Si el campo se omite por completo, la habilidad no restringe nada: Claude usa su modelo de permisos habitual.

Un ejemplo real de habilidad pensada para explorar un código base nuevo sin riesgo de que Claude modifique algo por accidente:

--- name: codebase-onboarding description: Ayuda a nuevos desarrolladores a entender cómo funciona el sistema. allowed-tools: Read, Grep, Glob, Bash model: sonnet ---

9. Divulgación progresiva

Las habilidades comparten la ventana de contexto con el resto de la conversación, así que conviene evitar concentrar todo el conocimiento en un solo archivo gigante. La recomendación de Anthropic es mantener el SKILL.md por debajo de 500 líneas y enlazar a archivos de referencia que Claude solo lee cuando hace falta.

La estructura sugerida separa tres tipos de contenido: scripts/ para código ejecutable, references/ para documentación adicional, y resources/ para plantillas, imágenes y datos. Un detalle importante: los scripts se ejecutan sin cargar su contenido en el contexto — solo la salida que producen consume tokens.

Es como tener un índice en la ventana de contexto en lugar del documento completo.

10. Jerarquía cuando los nombres coinciden

Si dos habilidades comparten el mismo nombre en distintos niveles, Claude Code resuelve el conflicto con un orden de prioridad fijo, de mayor a menor:

Prioridad	Nivel	Detalle
1	Empresa	Configuración administrada — máxima prioridad
2	Personal	~/.claude/skills — tu directorio personal
3	Proyecto	.claude/skills dentro del repositorio
4	Complementos	Plugins instalados — prioridad más baja

La configuración administrada por la empresa tiene sentido como techo: es ideal para estándares y cumplimiento obligatorios en organizaciones que necesitan garantizar, por ejemplo, que solo se instalen habilidades de mercados conocidos (strictKnownMarketplaces).

11. Compartiendo habilidades con tu equipo

Existen dos caminos principales para distribuir una habilidad más allá de tu propia máquina, y cada uno tiene un caso de uso natural:

Vía	Cómo funciona	Mejor para
Repositorio Git	.claude/skills se comparte automáticamente al clonar el repositorio; las actualizaciones llegan a todos en el siguiente pull.	Estándares de equipo y flujos de trabajo específicos del proyecto
Plugins y marketplaces	Empaquetan habilidades para distribuirlas entre repositorios y proyectos; otros usuarios las descubren e instalan por sí mismos.	Cuando la habilidad interesa más allá de tu equipo inmediato

12. Habilidades y subagentes: la sorpresa

Este es uno de los detalles menos intuitivos de todo el sistema, y por eso se destacó en la sesión como una advertencia aparte: los subagentes NO heredan tus habilidades automáticamente. Comienzan con un contexto nuevo y limpio, como si acabaran de arrancar Claude Code por primera vez.

Los agentes incorporados (Explorador, Plan, Verificador) no pueden acceder a habilidades en absoluto, bajo ninguna circunstancia. Los subagentes personalizados sí pueden usarlas, pero solo si las enumeras explícitamente en el campo skills de su configuración — no basta con que existan en el mismo proyecto.

13. Resolución de problemas de habilidades

Síntoma	Causa probable	Solución
No se activa	La descripción no coincide semánticamente con tu solicitud	Añade frases que coincidan con cómo realmente pides las cosas
No se carga	Estructura de carpeta o nombre de archivo incorrectos	SKILL.md dentro de un directorio con nombre; verifica mayúsculas exactas
Se usa la habilidad equivocada	Descripciones demasiado parecidas entre sí	Hazlas más distintas y específicas
Conflicto de prioridad	Otra habilidad de mayor jerarquía comparte el nombre	Renombra la tuya o consulta con tu administrador
Falla en tiempo de ejecución	Dependencias, permisos o separadores de ruta	Instala dependencias, chmod +x, usa barras diagonales

14. ¿Qué son los subagentes?

Si las habilidades añaden conocimiento a la conversación actual, los subagentes son algo distinto: asistentes especializados a los que Claude Code delega tareas completas. Cada subagente recibe un mensaje de sistema propio (su rol) y una descripción de la tarea escrita por el agente principal, y a partir de ahí trabaja de forma independiente — lee archivos, hace búsquedas, edita código según su función.

Lo esencial es qué pasa al terminar: el subagente solo devuelve un resumen a la conversación principal; toda la exploración intermedia —los archivos que leyó, las búsquedas que hizo, los callejones sin salida que descartó— se descarta por completo.

Diferencia clave: las habilidades añaden conocimiento a tu conversación actual; los subagentes operan en un contexto aparte.

15. Por qué importan los subagentes

Delegar una tarea a un subagente es un intercambio consciente entre limpieza y visibilidad, y vale la pena verlo en dos columnas:

Lo que ganas	Lo que pierdes
La ventana de contexto principal se mantiene limpia	Visibilidad sobre cómo el subagente llegó a sus conclusiones
Obtienes la respuesta sin el ruido del proceso que llevó a encontrarla	Los pasos intermedios (lecturas, búsquedas, llamadas) se descartan por completo
Puedes seguir trabajando más tiempo sin saturar la conversación	Solo queda disponible el resumen final que el subagente decide reportar

16. Ejemplo: investigar sin saturar el contexto

La sesión propuso un ejemplo sencillo de imaginar: la pregunta "¿qué servicio gestiona los reembolsos?" en un código fuente completamente desconocido. Sin un subagente, Claude podría necesitar leer quince archivos y rastrear varias llamadas a funciones para llegar a la respuesta, llenando la ventana de contexto por un solo dato.

Con el subagente Explorador, esa investigación ocurre en un contexto aparte y solo regresa una respuesta precisa. El hilo principal registra únicamente la pregunta y el resumen — no los quince archivos que se leyeron en el camino.

17. Subagentes incorporados vs. personalizados

Tipo	Ejemplos	Uso típico
Incorporados	Propósito general, Explorador, Plan	Exploración rápida y análisis previo a presentar un plan de acción
Personalizados	Revisor de código, redactor de pruebas, generador de documentación	Roles especializados con prompt y herramientas propias, definidos en .claude/agents

18. Práctica: creando un subagente

¿Por qué? un subagente de revisión de código aplica tus criterios de calidad sin cargar el historial de cómo se escribió ese código.

Paso	Acción
1	Ejecuta el comando /agents y selecciona "Crear nuevo agente".
2	Elige el alcance: nivel de proyecto (solo ese repositorio) o nivel de usuario (todos tus proyectos).
3	Describe el rol que quieres; deja que Claude genere el nombre, la descripción y el mensaje de sistema.
4	Personaliza el acceso a herramientas (lectura, edición, ejecución, MCP, otras) y elige modelo y color.

Pruébalo pidiéndole a Claude que delegue en el subagente la revisión de tus últimos cambios de código.

19. El archivo del subagente (.claude/agents/*.md)

Campo	Función
name	Identificador único; se invoca preguntando a Claude o escribiendo @agent nombre-del-subagente en el mensaje.
description	Controla cuándo Claude decide usar el subagente; puede incluir ejemplos de conversación como guía.
tools	Lista de herramientas a las que puede acceder el subagente.
model	sonnet, opus, haiku, o inherit (hereda el modelo de la conversación principal).
color	Color de la interfaz para identificar visualmente al subagente en ejecución.

20. Cuatro pilares de un subagente eficaz

Pilar	Qué resuelve
1. Descripciones específicas	Controlan cuándo se activa y qué instrucción de entrada recibe
2. Salida estructurada	Define cuándo el subagente sabe que terminó y qué debe reportar
3. Informe de obstáculos	Evita que el hilo principal redescubra soluciones ya encontradas
4. Acceso limitado	Solo las herramientas que la tarea realmente necesita

21. Ejemplo: formato de un subagente revisor

Un buen ejemplo práctico es cómo estructurar la salida de un subagente dedicado a revisar código, para que su reporte sea siempre predecible y fácil de leer desde el hilo principal:

1. Resumen — visión general de lo revisado y evaluación global.
2. Problemas críticos — vulnerabilidades de seguridad o errores lógicos graves.
3. Problemas mayores — calidad, arquitectura o rendimiento.
4. Problemas menores — estilo, documentación, optimizaciones pequeñas.
5. Recomendaciones y estado de aprobación — listo para fusionar o requiere cambios.
6. Obstáculos encontrados — dependencias, permisos o configuraciones especiales detectadas en el camino.

Un formato definido crea un punto de parada natural: el subagente sabe que terminó al completar cada sección.

22. Acceso a herramientas por tipo de subagente

Tipo de subagente	Herramientas típicas
Investigación / solo lectura	Glob, Grep, Read — no puede modificar archivos accidentalmente
Revisor de código	Lo anterior + Bash (para git diff), sin Edit ni Write
Modificación de código / estilo	Lo anterior + Edit y Write, porque su función es cambiar el código

23. Cuándo brillan los subagentes (y cuándo dañan)

Úsalos para	Evítalos para
Investigación y exploración de código fuente desconocido	Subagentes "expertos" que no aportan nada que Claude no supiera ya
Revisiones de código con una perspectiva objetiva e independiente	Pipelines secuenciales donde cada paso depende del descubrimiento anterior
Tareas con un prompt de sistema muy distinto: copywriting, estilo de marca	Ejecutores de pruebas que ocultan la salida completa necesaria para depurar

24. ¿Importa el trabajo intermedio?

Hay una sola pregunta que decide si conviene delegar una tarea a un subagente o mantenerla en el hilo principal: ¿necesitas ver y reaccionar a lo que sucede durante el proceso?

Si cada paso depende del anterior y necesitas intervenir sobre la marcha, mantén el trabajo en tu hilo principal. Si solo necesitas la respuesta final —y el camino para llegar a ella no te interesa— delega la tarea a un subagente.

25. Habilidades, subagentes y el resto del ecosistema

Con habilidades y subagentes en el mapa, la sesión cierra ubicando ambos dentro de las cinco piezas de personalización que ofrece Claude Code hoy. Cada una resuelve un problema distinto, y saber cuál usar es tan importante como saber usarlas:

Función	Se activa por	Ámbito
CLAUDE.md	Siempre — en cada conversación	Contexto principal, estándares permanentes
Habilidades (Skills)	Solicitud — coincidencia semántica	Contexto principal, conocimiento bajo demanda
Hooks	Eventos — guardar archivo, llamada a herramienta	Automatización basada en eventos
Subagentes	Delegación explícita o automática	Contexto aislado, tarea independiente
Servidores MCP	Disponibilidad de la herramienta	Integraciones y herramientas externas

Vistas juntas, estas cinco piezas dejan de ser funciones sueltas y se convierten en un sistema: CLAUDE.md fija las reglas permanentes, las habilidades aportan experiencia puntual bajo demanda, los hooks automatizan reacciones a eventos, los subagentes delegan tareas completas en un contexto aparte, y los servidores MCP conectan a Claude con herramientas externas. Ninguna reemplaza a las demás — cada una entra en juego en el momento correcto.

Las mejores habilidades y subagentes nacen de problemas reales: empieza por lo que más repites.

Para un perfil de BI y Data Analytics que se está encaminando hacia la ingeniería de datos, esta sesión tiene una lectura muy directa: las habilidades son el lugar natural para fijar convenciones de nombrado de columnas, checklists de validación de calidad de datos o plantillas de documentación de pipelines; y los subagentes son el mecanismo ideal para delegar auditorías de esquemas, revisiones de transformaciones SQL o exploraciones de un repositorio de datos desconocido, sin que ese trabajo de reconocimiento sature la conversación principal.