🧩 Entiende qué es una skill
Una skill es una capacidad reutilizable que guía al agente en una tarea específica: analizar un repositorio, generar especificaciones, crear un plan, reproducir un bug, generar pruebas, revisar la arquitectura, revisar la seguridad, actualizar la documentación, preparar un pull request, modernizar un módulo heredado, analizar un incidente, validar un deploy.
Cómo leer: las cajas en cian son skills; cada una amplía lo que el agente puede hacer bien. La línea punteada alrededor representa las rules: no enseñan nada, solo definen por dónde nadie puede pasar. Agregar una skill sin cerco es como aumentar la potencia sin frenos.
Capacidad
Skill amplía
Límite
Rule establece límites
Reutilización
Menos variación
Una tarea
Por skill
🧱 Estructura una skill
Diez campos son suficientes. Los dos que más diferencian una skill útil de un prompt guardado son "cuándo usar" (hace que el agente elija correctamente) y "acciones prohibidas" (evita el daño).
🧪 Ejercicio copiable — tu primera skill
Objetivo: transformar un prompt que ya repites en una skill versionada. Crea skills/<nome>/SKILL.md con este esqueleto.
# Skill: <nome curto e verbal, ex.: revisar-api> ## Objetivo <o que esta skill entrega, em uma frase> ## Quando usar <gatilhos concretos: "quando o diff altera arquivos em src/api/"> ## Quando NÃO usar <casos em que outra skill é melhor> ## Entradas - <spec, diff, caminho, log... o que precisa existir antes> ## Ferramentas permitidas - <leitura de arquivos, execução de testes, busca... e nada além> ## Etapas 1. <passo> 2. <passo> 3. <passo> ## Ações proibidas - <não alterar testes, não instalar dependências, não commitar...> ## Tratamento de falhas - <se X falhar, pare e relate; não tente contornar> ## Formato da saída <estrutura exata: tabela, lista com severidade, arquivo:linha...> ## Verificações obrigatórias - <o que rodar antes de declarar pronto, com a saída real anexada>
Cómo verificar: pídele a alguien del equipo que use la skill en una tarea real sin que le expliques nada. Si esa persona necesita preguntar algo, lo que faltó se convierte en un campo nuevo. Una buena skill funciona sin que su autor esté cerca.
Cuándo usar
El campo más importante
Prohibiciones
Dentro de la propia skill
Formato
Lo hace componible
Verificación
Cierra el loop
🗂️ Elige qué skills crear primero
Prioriza según frecuencia × variación de calidad: tareas que repites mucho y que hoy salen diferentes según quién las haga. Crear una skill para una tarea poco frecuente es mantenimiento sin retorno.
✓ Buenas primeras skills
- ✓Generar una especificación a partir de una tarea
- ✓Revisa el PR con una perspectiva de seguridad
- ✓Reproducir el bug y escribir la prueba que falla
- ✓Preparar un PR con evidencias adjuntas
✗ Skills que no se amortizan
- ✗"Hacer cualquier cosa en el repositorio" (demasiado genérica)
- ✗Tarea que ocurre una vez cada semestre
- ✗Proceso que todavía cambia cada semana
- ✗Treinta skills creadas antes de usar la primera
💡 Consejo práctico
Empieza con tres a cinco skills. Si en un mes no usaste una de ellas, no era una prioridad — elimínala. Una colección grande de skills sin usar tiene el mismo problema que la documentación muerta: ocupa espacio en el contexto y estorba.
Frecuencia
Primer criterio
Variación
Dónde hay más beneficio
3 a 5
No treinta
No usada
Borra
📏 Entiende qué son las rules
Las Rules son reglas permanentes o condicionales que limitan el comportamiento de los agentes. Se aplican en todas las tareas, independientemente de la skill que uses. Las Rules reducen las decisiones arbitrarias.
Conjunto base — copia y adapta
- nunca modificar pruebas para ocultar una falla - nunca incluir secretos en el repositorio - no agregar dependencias sin justificarlo - preservar las API públicas - no ejecutar un deploy sin aprobación - no modificar directamente la base de datos de producción - no eliminar logs de seguridad - generar evidencia de las pruebas - limitar el número de intentos - detenerse cuando el costo supere el límite - pedir aprobación antes de realizar acciones destructivas - no refactorizar fuera del alcance
Permanente
Aplica a toda tarea
Arbitrariedad
Es lo que la rule evita
Clara
Una línea, sin ambigüedad
Pocas
Las listas largas se ignoran
🔐 Escribe rules de seguridad y compatibilidad
Este es el núcleo duro: las reglas cuya violación cuesta caro y es difícil de revertir. Merecen quedar por escrito y, siempre que sea posible, convertirse en un gate automático.
Nunca cambies las pruebas para ocultar un fallo
Es la regla que protege el propio concepto de «listo». Sin ella, todo lo demás del curso pierde sentido: el verificador deja de ser confiable.
Nunca insertes secretos en el repositorio
Combínalo con el gate de detección de secretos del módulo 3.3. Regla y verificación juntas: una orienta y la otra impide.
Preservar las API públicas y producir evidencia
El contrato público no cambia sin versionado. Y cada entrega viene con el resultado real de las pruebas: la evidencia es una obligación, no una cortesía.
⚠️ Atención
Rule sin verificación depende de la obediencia, y la obediencia en un sistema probabilístico no es una garantía. Siempre que la regla sea crítica e automatizable, conviértela en un gate. La rule sigue orientando; el gate es lo que impide.
Prueba intocable
Protege el "listo"
Secreto
Rule + gate
API pública
Contrato preservado
Evidencia
Obligación
🎚️ Usa rules para limitar la autonomía
Límite de intentos, tope de costo, aprobación antes de acciones destructivas, prohibición de refactorizar fuera del alcance: es la versión escrita y permanente de los límites que configuraste en la ruta 2.
🔗 Dónde vive cada pieza
- •Rule (texto, siempre válida): "pedir aprobación antes de acciones destructivas".
- •Harness (configuración): el permiso que simplemente no existe para el agente.
- •Gate (verificación): el pipeline que bloquea el cambio si se incumplió la regla.
- •Las tres capas se refuerzan. Depender de una sola es una apuesta.
Chequeo rápido: escribiste la rule "nunca commitar secretos". ¿Es suficiente?
Rule
Orienta
Harness
Ni siquiera da el permiso
Gate
Lo impide al salir
Tres capas
Si refuerzan
📌 Resumen del módulo
Próximo módulo:
5.2 - Skills y Rules: empaquetar capacidades y fijar límites permanentes.