🧩 Qué es una skill
Una skill es una capacidad reutilizable que Claude Code carga bajo demanda. En la práctica, es un archivo SKILL.md: un frontmatter con name e description, más un cuerpo en Markdown con los pasos y archivos de referencia opcionales.
A description es el disparador: cuando la tarea que pides coincide con ella, la skill se activa sola e inyecta los pasos en el contexto. Enseñas una vez, la usas siempre, sin reescribir el procedimiento en cada conversación.
💡 Consejo práctico
Piensa en la skill como un colega que ya conoce el procedimiento. No tienes que volver a explicárselo: solo dices «haz aquello» y la description reconoce la solicitud. Cuanto mejor sea la descripción, más preciso será el disparador.
lo enseña una vez
carga cuando hace falta
frontmatter + pasos
la descripción activa
🕵️ Qué es un subagente
Un subagente es una instancia separada de Claude, con su propia ventana de contexto, su propio system prompt y sus propias herramientas. Recibe una tarea, trabaja de forma aislada y devuelve solo el resultado, para que el contexto del agente principal siga limpio.
Es un trabajador dedicado. Lo que lee, descarga y procesa queda en su contexto, no en el tuyo. Tú solo recibes el resumen de lo importante: el equivalente a delegar una investigación pesada sin ahogar la conversación.
Recibe la tarea
El agente principal delega un trabajo específico —"investiga la empresa X", "analiza ese sector"— con instrucciones claras.
Trabaja de forma aislada
Lee decenas de páginas, realiza búsquedas, procesa datos — todo en su propio contexto. Nada de eso contamina tu thread.
Devuelve el resumen
Devuelve solo la conclusión: los hallazgos que importan. El agente principal sigue con el contexto ligero y enfocado.
contexto propio
prompt + tools propios
solo lo que importa
protege lo principal
⚖️ Skill vs agente: cuándo usar cada uno
La confusión más común es usar un agente cuando bastaba con una skill y sobreingenierizar. La regla es sencilla. Skill es una capacidad que le das al agente principal (generar un PPTX, ejecutar un diagnóstico). Subagente es un trabajador independiente para un trabajo que consume mucho contexto o necesita aislamiento (recorrer la web, investigar una empresa).
Regla práctica: mismo thread + procedimiento reutilizable → skill. Thread separado + trabajo pesado o independiente → subagente.
✓ Se convierte en SKILL cuando…
- ✓Es un procedimiento que se repite en el mismo thread
- ✓Quieres darle una capacidad al agente principal
- ✓El resultado queda en la conversación (deck, diagnóstico, SOW)
- ✓No consume mucho contexto al ejecutarse
✓ Se convierte en AGENTE cuando…
- ✓El trabajo consume mucho contexto (recorrer la web)
- ✓Necesita aislamiento — no quiere ensuciar el hilo
- ✓Es independiente y puede ejecutarse en paralelo
- ✓Solo quieres recibir el resumen, no el proceso
💡 Si tienes dudas, empieza con una skill
Un subagente ofrece más poder, pero también implica más piezas móviles. Si la tarea cabe en el mismo hilo sin saturar el contexto, crea una skill. Promuévela a subagente solo cuando el aislamiento o el volumen de contexto lo requieran.
capacidad
delegación intensiva
→ skill
→ subagente
🔬 Anatomía de una skill (SKILL.md)
Una skill es un solo archivo. En la parte superior, un frontmatter YAML con name e description. Abajo, un cuerpo en Markdown con los pasos. Mira el esqueleto mínimo de una skill de diagnóstico de IA.
// .claude/skills/diagnostico-ia/SKILL.md
--- name: diagnostico-ia description: Use ao diagnosticar a maturidade de IA de uma empresa descrita em texto — gera maturidade 1-5, quick wins e roadmap 30/60/90. --- # Diagnóstico de IA ## Passos 1. Ler a descrição da empresa. 2. Pontuar a maturidade de IA (1-5). 3. Listar 3 quick wins (esforço × impacto). 4. Sugerir um roadmap 30/60/90.
id corto — el nombre de la skill, usado para referirse a ella. Sin espacios, directo al grano.
el detonante — describe cuándo usar la skill. Es lo que Claude lee para decidir si la activa.
los pasos — el procedimiento en Markdown que el agente sigue después de activarse.
💡 La description es la parte más ignorada
Es la pieza más importante y la más descuidada. Una description vaga ("ayuda con estrategia") nunca se activa en el momento adecuado. Di cuándo usar, con activadores concretos — eso es lo que hace que la skill aparezca sola.
id corto
el detonante
los pasos
todo en un SKILL.md
📁 Dónde viven las skills y los subagentes
Todo está en una carpeta .claude/. Las Skills están en .claude/skills/<nome>/SKILL.md; subagentes en .claude/agents/<nome>.md. La elección es entre el alcance del proyecto (va junto con Git) y el alcance personal (se aplica a todos tus proyectos).
📦 Del proyecto (.claude/)
- ✓Vive en la raíz del repositorio del proyecto
- ✓Se incluye en Git: todo el equipo lo hereda
- ✓Ideal para la Fábrica: versionada junto con el código
🏠 Personal (~/.claude/)
- ✓Vive en tu home, fuera de cualquier repo
- ✓Aplica a todos los proyectos que abras
- ✓Ideal para tus herramientas de uso general
// estructura del proyecto
.claude/
├── skills/
│ ├── diagnostico-ia/SKILL.md
│ └── gerar-entregavel/SKILL.md
└── agents/
├── pesquisador-empresa.md
└── redator-estrategia.md
un SKILL.md cada uno
un .md cada uno
va en Git
vale en todo
💎 El ecosistema de recursos reutilizables
Aquí está la razón por la que todo esto se convierte en un activo. Cada skill y cada agente se construye una vez y se reutiliza para siempre. Juntos, forman los engranajes de la Fábrica: tu arsenal.
Es la tesis "entrada mínima, salida máxima" convertida en código. El esfuerzo se dedica a la construcción, no a la entrega. Cuantas más piezas acumules, más entregará la Fábrica por sí sola y más caerá el costo marginal de cada nuevo cliente.
💡 Construye el arsenal, no el entregable
Cada vez que hagas una tarea a mano, pregúntate: «¿esto se convierte en skill o agente?». Si la respuesta es sí, transfórmala y no vuelvas a hacerla. El entregable es descartable; la pieza reutilizable es lo que se acumula y te da apalancamiento.
reutilizar siempre
piezas de la Fábrica
se acumula
costo marginal ↓
✅ Resumen del módulo
🎯 Misión 3.1 — Mapea tu arsenal
Enumera tus tareas y clasifica cada una como skill o subagente:
- 3 tareas repetitivas las tuyas que se convierten skill (p. ej., diagnosticar una empresa, generar una presentación, redactar un SOW).
- 2 tareas que se convierten en subagente (p. ej., investigar una empresa en la web, analizar un sector entero).
Éxito: 3 skills + 2 agentes mapeados. Lo que obtuviste: el diseño de tu arsenal: qué construir en las próximas clases.
Siguiente módulo:
3.2 — Construye tu primera skill (diagnostico-ia)