🧭 Qué cambió (y qué no cambió)
Circulan videos sobre «10 reglas nuevas» para skills. Al consultar la página oficial de buenas prácticas de Anthropic y la documentación de Claude Code, las reglas básicas se mantienen estables desde hace aproximadamente un año. Lo que cambió fueron las modelos: Fable 5, Opus 5.5 y Sonnet 5.5 siguen las instrucciones con más precisión y hacen más cosas por su cuenta. Una skill escrita para modelos antiguos sigue funcionando, pero puede arrastrar peso muerto.
El aviso que motivó esta clase
Según la guía de prompting citada por skill-creator-plus, las skills escritas para modelos antiguos suelen ser demasiado prescriptivas para los modelos 5.5 y pueden empeorar el resultado. No encontramos esa frase en la documentación oficial; considérala una hipótesis que debes probar en tu skill, no una regla de Anthropic.
Estable (ya visto en el curso)
- ›SKILL.md de menos de 500 líneas
- ›Divulgación progresiva en tres niveles
- ›Descripción como activador: qué hace y cuándo usarla
Qué aporta esta clase
- ›Grados de libertad por paso
- ›Límites de caracteres y el corte de 5.000 tokens
- ›Hooks en la skill, sin pedir razonamiento, lista de verificación con respuesta
🎚️ Grados de libertad: alto, medio, bajo
La documentación oficial pide ajustar el nivel de detalle de cada paso según su fragilidad. La imagen de Anthropic: en un puente estrecho con precipicios a ambos lados, instrucciones exactas; en un campo abierto, una dirección y confianza. Para cada paso, la pregunta es: "¿y si el agente hace este paso de otra manera?"
Alto
Instrucción en texto simple. Hay varios enfoques válidos y el contexto decide.
Ej.: revisión de código, lluvia de ideas.
Medio
Modelo o script con parámetros. Hay un patrón preferido y se acepta cierta variación.
Ej.: informe semanal.
Bajo
Script exacto, con pocos parámetros o ninguno. Un error cuesta caro o el orden no puede cambiarse.
Ej.: factura, impuesto, migración bancaria.
una skill, tres niveles:
## 1. Draft the post (high) Write in the brand voice. Context decides the angle. ## 2. Build the summary (medium) Use templates/summary.md. Sections may grow or shrink. ## 3. Publish (low) Run exactly: python scripts/publish.py --verify Do not add flags.
💡 Consejo
Una buena skill suele combinar las tres: escritura libre, resumen con modelo y publicación bloqueada en un comando. Bloquear todo vuelve rígida la skill; dejar todo libre deja el paso a merced del azar.
✍️ Descripción en tercera persona, con «cuándo usar»
La descripción es la única parte de la skill que el agente ve antes de elegirla, entre posiblemente más de cien. Se incluye en el prompt del sistema, por eso la documentación pide tercera persona («Crea facturas…», no «Yo creo…» ni «Puedes…»). Formato: una frase sobre lo que hace la skill y luego «Úsala cuando…» con las situaciones y las palabras que la persona realmente escribe. Y solo lo que el modelo no sabe: no expliques qué es una factura.
✗ No se activa bien
- ✗"Ayudo con las facturas." (primera persona, sin cuándo)
- ✗"Puedes usarla para documentos." (vago)
- ✗Activador principal al final de un texto largo
✓ Se activa
- ✓"Crea facturas a partir de la hoja de horas y envía recordatorios de cobro. Úsala cuando alguien pida una factura, un cobro o un recordatorio de pago."
- ✓Primero, el caso de uso principal
Máximo del campo description, sin etiquetas XML (best-practices de Anthropic).
Claude Code recorta description + when_to_use sumados en este punto de la lista de skills. El agente no lee lo que supera ese límite.
💡 Consejo
Cuando el listado supera el presupuesto, Claude Code también descarta descripciones completas de skills poco usadas. Un motivo más para poner el activador más importante en la primera frase.
🪝 Hooks en el frontmatter de la skill
El texto se sigue con criterio: puede omitirse y, después de la compactación, solo queda el comienzo de la skill. "Nunca enviar una factura de más de R$ 50 mil sin aprobación" en mayúsculas casi siempre se sigue. Un hook siempre se sigue. La novedad es que la propia skill puede declarar sus hooks en el frontmatter: estos registran cuándo se llama a la skill y permanecen activos el resto de la sesión.
SKILL.md (Claude Code):
---
name: safe-deploying
description: Deploys the app to staging with a safety check on
each shell command. Use when the user asks to deploy or ship.
disable-model-invocation: true
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/check-command.sh"
---
Se invoca la skill
Los hooks del frontmatter entran en vigor en ese momento.
El evento ocurre
Antes de cada comando Bash, Claude Code ejecuta el script; sigue al agente, use la skill o no.
Hasta el final de la sesión
El hook sigue registrado. Usa once: true en el hook que solo debe ejecutarse la primera vez que funciona.
💡 Consejo
El criterio queda en el texto; las reglas estrictas se convierten en hooks. Los hooks son solo de Claude Code: en claude.ai, mantén la regla en texto y cerca del principio.
🗜️ Compactación: solo se conservan los primeros 5.000 tokens
Cuando la conversación se compacta, Claude Code vuelve a adjuntar solo los primeros 5.000 tokens de cada skill en uso. Una regla importante al final de un SKILL.md largo simplemente desaparece en una sesión extensa. Por eso, el orden del archivo es el orden de importancia.
✗ Orden que pierde una regla
- ✗Historia del proyecto y contexto general al principio
- ✗"Reglas importantes" como última sección
✓ Orden que conserva las reglas
- ✓Reglas que no pueden fallar, desde el inicio
- ✓Instrucciones permanentes («comprueba el resultado después de cada cambio»), no pasos para hacer una sola vez
- ✓Detalles en references/, enlazados directamente desde SKILL.md
🚫 No pidas el razonamiento en la respuesta
Las instrucciones como «escribe tu razonamiento paso a paso» o «transcribe lo que pensaste» pueden ser rechazadas por los modelos 5.5 (la negativa reasoning_extraction). La skill se detiene a mitad de camino sin hacer el trabajo. Pide el resultado: la respuesta, una explicación breve o el resumen de las acciones.
✗ Reemplaza
- ✗"Muestra todo tu razonamiento antes de responder."
- ✗"Piensa paso a paso y escribe cada pensamiento."
✓ Porque
- ✓"Empieza por el resultado y explica en dos frases por qué vale la pena."
- ✓"Al final, enumera las acciones que ejecutaste."
Los otros ajustes para modelos nuevos
- ★Recorta el andamiaje, pero prueba antes: El paso a paso de lo que el modelo ya sabe y el sentido común repetido son candidatos a eliminar. Solo una ejecución con la línea y otra sin ella demuestra que era contenido innecesario.
- ★Da el motivo: "por debajo de 1.536 caracteres, porque Claude Code corta la lista ahí" deja que el modelo resuelva el caso que la regla no contempló.
- ★Indícalo en una frase: mayúsculas solo para reglas estrictas. Cuando todo grita, nada se destaca.
- ★Verificación explícita: di cómo y cuándo se revisa el trabajo; en ejecuciones largas, un subagente que no hizo el trabajo lo verifica según la especificación.
☑️ Lista de verificación copiada + «vuelve al paso X»
Para una tarea de muchos pasos, la documentación recomienda darle al agente un checklist que él copia en la propia respuesta y va marcando. Cada paso termina con un «listo cuando…» que se puede comprobar, y la lista indica a qué paso volver si falla una verificación. Así, el agente no se salta pasos ni declara victoria antes de tiempo.
en el SKILL.md:
Copy this checklist into your reply and tick each step: - [ ] 1. Load the timesheet done when: every row has hours - [ ] 2. Compute the totals done when: sum matches the sheet - [ ] 3. Render the invoice done when: PDF opens, 1 page - [ ] 4. Validate python scripts/validate.py out.pdf If step 4 fails on the total, go back to step 2.
💡 Consejo
La verificación no tiene que ser código: comparar el borrador con la guía de estilo y enumerar cada desviación también es un ciclo de verificación. Ejecuta, corrige lo que falló y repite hasta que pase.
🔎 Audita antes de reescribir
No reescribas skills de memoria: mídelo. El proyecto INEMA auditar-skills es el reflejo de skill-creator-plus (RoboNuggets, licencia MIT), con una guía en portugués. El validador está hecho solo en Python, no requiere instalar nada ni llamar a una API: revisa la parte mecánica de todas las skills de una carpeta en aproximadamente un segundo.
dentro de la carpeta de auditar-skills:
python3 ~/.claude/skills/skill-creator-plus/scripts/validate_skill.py --all ~/.claude/skillsskills auditadas en una máquina real (la de Nei)
errores encontrados
skills sin ningún error
Los mayores infractores
- ST5Una referencia de más de 100 líneas sin índice al principio. Una lectura parcial no muestra todo lo que abarca el archivo.
- ST4Referencia anidada: un archivo al que solo se llega a través de otro archivo puede mostrarse solo como vista previa (las primeras líneas). Todo debe estar enlazado directamente desde SKILL.md.
- DS3Descripción sin «cuándo usar», sin las palabras que la persona escribe.
Ejecuta el validador
Una tabla por skill con errores, advertencias y las reglas incumplidas.
Elige cinco
Las que tienen más errores o las que más usas. Auditar toda la biblioteca no compensa el costo.
Informe antes de editar
Pide el informe y elige qué aplicar. ST5 y ST4 son correcciones mecánicas.
Prueba con y sin
Antes de borrar una línea, ejecuta la skill con ella y sin ella. Las reglas que siempre deben cumplirse van en un hook.
📋 Lista de verificación de las 10 reglas (copia y usa)
Antes de publicar o al revisar una skill antigua, sigue esta lista. El botón la copia en formato de checklist Markdown, lista para pegar en tu editor o en la solicitud al agente.
- SKILL.md de menos de 500 líneas; todos los archivos de referencia enlazados directamente desde SKILL.md (un nivel de profundidad).
- Una referencia de más de 100 líneas empieza con un índice.
- Grado de libertad según el riesgo: texto libre cuando el contexto decide, modelo cuando hay un patrón, script exacto cuando el error cuesta caro.
- Probada en cada modelo que vaya a usarla (Haiku, Sonnet, Opus/Fable).
- Solo lo que el modelo no sabe; descripción en tercera persona, con "Usa cuando…" y las palabras que escribe la persona.
- Descripción de hasta 1.024 caracteres; descripción + when_to_use por debajo de 1.536; primero, el caso de uso principal.
- Una tarea larga tiene un checklist que el agente copia en la respuesta, con "listo cuando…" y "si falla, vuelve al paso X".
- Ciclo de verificación: ejecutar, corregir lo que falló, repetir hasta que pase.
- Reglas críticas al principio, porque tras la compactación solo quedan los primeros 5.000 tokens de la skill; no pidas que escriba el razonamiento.
- Una regla que no puede incumplirse se convierte en un hook en el frontmatter; paquetes listados con la línea de instalación.
💡 Fuentes
Guía de buenas prácticas para skills de Anthropic (platform.claude.com), documentación de skills, hooks y ventana de contexto de Claude Code, consultados el 6 de octubre de 2026. La advertencia sobre skills demasiado prescriptivas proviene de la guía de prompting citada por skill-creator-plus. Las cifras cambian: consulta el enlace oficial antes de citarlas.
✅ Resumen del módulo · Fin del curso
¡Terminaste el curso! 🎉
Cinco rutas, desde la visión del ecosistema hasta la gobernanza y las reglas de 2026. Ahora te toca: ejecuta el validador en tus skills, corrige las cinco peores, escribe la próxima usando ya la checklist y sigue aprendiendo en el portal.