Divide una función en tareas verificables
Qué es
Una función como marketing se divide en procesos, y cada proceso en entregas menores. Producir un artículo a partir de un video es una entrega; administrar todo el marketing no lo es. Use el árbol del video como herramienta para encontrar las hojas que tienen un comienzo y un final.
Por qué aprender
Cuando una skill hace investigación, creación, publicación y análisis financiero, una falla se vuelve difícil de localizar. Separar responsabilidades permite probar cada parte y encadenarlas después, con entradas y salidas explícitas.
Conceptos clave
Función: contenido
├── Planear agenda
├── Convertir video en artículo
├── Revisar artículo
└── Publicar artículo aprobado
✓ Haz así
Separa la publicación cuando exija una decisión diferente.
✗ Evita este error
Crear una skill llamada “hacer-todo” con decenas de gatillos.
Practica antes de revelar
Descompón “cuidar a los clientes” en tres tareas delimitadas.
Ver respuesta comentada
Clasificar una solicitud; redactar una respuesta con base en la política; preparar un resumen semanal de llamados. Cada una puede tener una prueba diferente.
Conoce el archivo que guarda el procedimiento
Qué es
El nombre correcto es SKILL.md, respetando la capitalización. Empieza con metadatos YAML entre líneas de tres guiones y continúa con instrucciones Markdown. Los campos name y description identifican la skill y su situación de uso.
Por qué aprender
Un error en el encabezado puede impedir el descubrimiento o perjudicar la selección. Mantenga el primer ejemplo mínimo y legible. Los campos extra vistos en otras herramientas no deben tratarse como obligatorios en Codex.
Conceptos clave
---
name: relatorio-semanal
description: Convierte CSV de ventas en reporte semanal local. Úsalo al pedir totales por canal y pendientes; no actualiza CRM.
---
# Reporte semanal
1. Validar la entrada.
2. Calcular totales.
3. Generar reporte y verificar.
Del concepto a la acción
- SKILL.md: identificar la condición inicial.
- Metadatos YAML: aplicar la decisión descrita.
- Instrucciones: verificar el efecto en el ejemplo.
- Recursos opcionales: registrar la evidencia de salida.
✓ Haz así
Empieza por los campos confirmados en la documentación oficial.
✗ Evita este error
Copiar argument-hint de otra herramienta como requisito de Codex.
Practica antes de revelar
¿Qué campo necesita mencionar “CSV de ventas” para ayudar a la selección?
Ver respuesta comentada
description. El cuerpo puede profundizar el formato, pero el escenario principal necesita estar claro en los metadatos de descubrimiento.
Elige el alcance de la instalación
Qué es
Para este laboratorio, coloque la carpeta de la skill en .agents/skills dentro del proyecto. Las skills de usuario pueden quedar en ~/.agents/skills. El alcance del proyecto acompaña ese trabajo; el alcance de usuario pone el procedimiento a disposición en otros proyectos.
Por qué aprender
Una skill específica de un cliente puede causar confusión si se instala globalmente con un gatillo genérico. Evite copias independientes con el mismo nombre: con el tiempo, deja de saber qué versión se está ejecutando.
Conceptos clave
meu-projeto/
.agents/
skills/
relatorio-semanal/
SKILL.md
scripts/
references/
✓ Haz así
Pide al Codex la ruta de la skill que seleccionó.
✗ Evita este error
Suponer que dos skills con el mismo nombre se fusionan.
Practica antes de revelar
Una skill usa convenciones de un solo proyecto. ¿Dónde ponerla primero?
Ver respuesta comentada
En el alcance del proyecto. Solo generalízala después de separar reglas específicas y probar otros contextos. No es necesario instalarla globalmente para aprender.
Escribe gatillos y también no gatillos
Qué es
La descripción debe responder cuándo usar la skill. Un gatillo explícito es pedirle a la skill por su nombre; uno implícito es describir una tarea compatible. En Codex CLI o extensión, la documentación presenta /skills y la mención con $ para selección explícita.
Por qué aprender
Frases amplias como “siempre que hable de un informe” capturan tareas de más. Pruebe pedidos que deberían activar y pedidos cercanos que no deberían. La ausencia de una prueba negativa oculta colisiones con otras skills.
Conceptos clave
SÍ: “Resuma este CSV de ventas de la semana.”
NO: “Escriba un reporte de investigación sobre energía.”
AMBIGUO: “Haz mi reporte.” → pedir entrada y objetivo.
EXPLÍCITO: “Usa $relatorio-semanal en este archivo.”
✓ Haz así
Prueba sin citar el nombre de la skill para evaluar el gatillo implícito.
✗ Evita este error
Creer que una prueba explícita prueba la selección automática.
Practica antes de revelar
Crea un pedido negativo con la palabra “vendas”.
Ver respuesta comentada
“Escribe un anuncio para aumentar las ventas.” Comparte vocabulario, pero no pide convertir CSV en un informe; por lo tanto no pertenece al alcance.
Distribuye instrucciones, referencias y scripts
Qué es
Deje en SKILL.md el camino principal y las condiciones para consultar material adicional. Una referencia puede guardar la rúbrica editorial; un script puede calcular valores. El agente no necesita cargar todos los ejemplos largos para descubrir el propósito de la skill.
Por qué aprender
Esta organización reduce la repetición y hace el mantenimiento más preciso. La descripción no debe convertirse en un manual entero. Al mismo tiempo, ocultar una regla esencial en un archivo que nunca se menciona impide que se aplique.
Conceptos clave
En SKILL.md:
“Ejecuta scripts/gerar_relatorio.py para los totales.
Para revisar los comentarios, consulta references/rubrica.md.
Si la entrada es inválida, informa el mensaje del validador.”
Del concepto a la acción
- Descubrir: identificar la condición inicial.
- Leer el procedimiento: aplicar la decisión descrita.
- Consultar lo necesario: verificar el efecto en el ejemplo.
- Ejecutar: registrar la evidencia de salida.
✓ Haz así
Diga cuándo y para qué abrir cada referencia.
✗ Evita este error
Mover todo el contrato a un archivo sin enlace ni condición.
Practica antes de revelar
¿Dónde colocar veinte ejemplos largos de reportes?
Ver respuesta comentada
En una referencia dedicada, manteniendo en SKILL.md solo los ejemplos mínimos y la instrucción de consulta. Los datos sensibles deben eliminarse antes de crear esa biblioteca.
Ejecuta la primera versión y registra el disparo
Qué es
Abra el proyecto en Codex, pida la tarea con el archivo de ejemplo y verifique qué procedimiento se usó. Si la skill no aparece, revise ruta, nombre, encabezado y descripción. La documentación recomienda reiniciar si una actualización no se detecta.
Por qué aprender
Hay diferencia entre no descubrir la skill y ejecutarla mal. Diagnosticar la fase evita reescribir todo el contenido por un archivo en el lugar incorrecto. Registre pedido, skill seleccionada y artefactos producidos.
Conceptos clave
Usa $relatorio-semanal con dados/vendas.csv.
Muestra el camino de la skill usada.
Guarda la salida en saidas/rodada-01/.
Informa las pruebas ejecutadas y las limitaciones observadas.
✓ Haz así
Inspecciona los archivos entregados además del mensaje final.
✗ Evita este error
Considerar “usé la skill” como suficiente para aprobar el resultado.
Practica antes de revelar
El test explícito funciona y el implícito no. ¿Qué revisar primero?
Ver respuesta comentada
La descripción y los pedidos de prueba. El cuerpo ya demostró ser ejecutable; el problema más probable está en la selección. También verifica skills concurrentes con un alcance parecido.
Verifique su comprensión
¿Qué descripción delimita mejor la skill?
¿Qué te llevas de este módulo?
Crear un SKILL.md pequeño, accionable y con pruebas de disparo.
- Divide una función en tareas verificables.
- Conoce el archivo que guarda el procedimiento.
- Elige el alcance de la instalación.
- Escribe disparadores y también no disparadores.
- Distribuye instrucciones, referencias y scripts.
- Ejecuta la primera versión y registra el disparo.
Próxima acción: guarde el ejercicio en su laboratorio y registre lo que todavía necesita revisión.