Skills: qué se paga siempre y qué se paga cuando hace falta

Todo lo que está siempre se paga siempre

Cada token del system prompt viaja en cada request, se cobra como input, y ocupa lugar en la atención del modelo junto a la conversación y a la tarea concreta. El prompt caching baja el costo monetario —lo vimos en el artículo sobre el modelo mental de los LLMs— pero no baja el costo de atención. El modelo sigue leyendo esas instrucciones cada vez que decide qué hacer.

Y el caching tiene su propia letra chica acá. El cache es un match de prefijo: cualquier byte que cambie invalida todo lo que viene después. La metadata de las skills instaladas vive en ese prefijo. Instalar una skill, borrarla o editarle la descripción reescribe el prefijo e invalida el cache de esa sesión. Editar descripciones en caliente durante una sesión larga sale bastante más caro de lo que parece, y ese costo es presupuesto de contexto puro.

Ese es el problema real de los system prompts que crecen. Nadie borra nada. Se agrega la convención de commits, la guía de estilo del SQL, el procedimiento de deploy, el formato del reporte trimestral. Cada agregado individual parece barato. El agregado número treinta ya cambió la distribución de atención de todos los pedidos, incluidos los que no tienen nada que ver con ninguno de esos treinta.

Una skill es una decisión de presupuesto de contexto: difiere el costo de una instrucción hasta que la tarea la pida. Es una carpeta con un SKILL.md que empaqueta instrucciones y archivos para una tarea, y la documentación de Anthropic llama a ese diferimiento revelación progresiva — la metadata vive en el system prompt siempre, el cuerpo del archivo se lee recién cuando la tarea lo amerita.

La pregunta no es "¿esto es útil?". Es "¿esto justifica estar presente en todos mis requests?".

Los tres niveles de carga

Los 5k del nivel 2 son el orden de magnitud que da la documentación, no un tope que el sistema imponga. El único límite duro que la doc enuncia para el cuerpo es de 500 líneas, y es una recomendación de autoría, no una validación.

El caso de los scripts es el más limpio del cuadro. Si la skill trae un validate.py, el modelo lo ejecuta por bash y solo la salida entra al contexto. El código nunca se carga: un validador de doscientas líneas cuesta lo que ocupe imprimir "OK" o el mensaje de error.

La descripción es lo único que pagás siempre

De acá se deduce todo el resto del diseño. La description tiene un máximo de 1024 caracteres y es el único texto de la skill que está en el contexto de cada request. Todo lo que escribas ahí lo pagás cuando la skill se usa y cuando no.

Así se ve una skill completa. El frontmatter es todo lo que el modelo ve siempre; lo demás llega solo si la tarea lo pide.

---
name: conciliando-movimientos
description: Genera y valida reportes de conciliación bancaria a partir de exports de movimientos. Usar cuando el pedido implique cerrar un período contable, cruzar movimientos contra comprobantes, o explicar diferencias entre saldos.
---

# Conciliación de movimientos

## Cuándo aplica
Exports de los cuatro bancos con los que operamos. Para cualquier otro
origen, pedí confirmación del mapeo antes de procesar.

## Procedimiento
Normalizá el export, cruzá contra comprobantes por monto y fecha, y
listá las diferencias con su causa probable. El criterio para agrupar
diferencias es de juicio: agrupá por lo que un contador miraría junto.

Antes de entregar, corré exactamente este comando:
`python scripts/validate.py <archivo-normalizado>.csv`

## Referencias
- `REFERENCE.md` — mapeo de columnas por banco
- `scripts/validate.py` — validador de totales y duplicados

El name tiene sus reglas y son baratas de cumplir: máximo 64 caracteres, minúsculas, números y guiones, sin las palabras reservadas "anthropic" y "claude". La forma gerundio funciona bien y es la que usan los ejemplos de la documentación: processing-pdfs, analyzing-spreadsheets.

La descripción tiene que decir dos cosas: qué hace la skill y cuándo usarla. Las dos. Una descripción que solo dice qué hace deja la decisión de disparo librada a la inferencia, y ahí es donde las skills no se activan nunca o se activan siempre. Es el mismo problema que con las descripciones de herramientas: la falla más común es sub-describir, y conviene ser prescriptivo sobre el cuándo, no solo sobre el qué. Escribila además en tercera persona: la descripción se inyecta en el system prompt, y el punto de vista inconsistente ("puedo ayudarte a...") genera problemas de discovery.

El error caro es otro, y conviene verlo en las dos versiones lado a lado. Esta es la descripción rota:

description: Reportes de conciliación. Usar cuando el usuario diga armá la
  conciliación, hacé la conciliación, necesito conciliar, conciliame el mes,
  cerrá el mes, hacé el cierre, cerrame julio, preparame el cierre contable,
  cruzá los movimientos, cruzame el extracto contra los comprobantes.

Y esta es la misma intención nombrada por categoría:

description: Genera y valida reportes de conciliación bancaria a partir de
  exports de movimientos. Usar cuando el pedido implique cerrar un período
  contable, cruzar movimientos contra comprobantes, o explicar diferencias
  entre saldos.

La primera ronda los 210 tokens, la segunda los 60. La documentación describe que el modelo compara el pedido contra la descripción; no describe con qué mecanismo lo hace, así que no hay que sostener la diferencia sobre una teoría del matching. Se sostiene sobre dos cosas que sí se pueden afirmar. La primera es aritmética: esos 150 tokens de diferencia viajan en cada request, use la skill o no. La segunda es de diseño: diez frases casi sinónimas gastan el presupuesto en repetir una misma señal en vez de en delimitar contra qué se distingue esta skill de las otras. Nombrar la categoría de intención cubre más superficie con menos tokens.

El cuerpo: especificidad que coincida con la fragilidad

Una vez que la skill se disparó, el cuerpo entra al contexto y compite con la conversación. La recomendación oficial es mantener el SKILL.md por debajo de 500 líneas y partir en archivos separados antes de llegar ahí.

El criterio para escribir el cuerpo no es "cuánto explico" sino "cuánta libertad le dejo". Los guiones exactos para decisiones de juicio sobre-restringen. La prosa vaga para operaciones frágiles sub-restringe. La analogía de la documentación es buena: un puente angosto con precipicio a los costados pide instrucciones exactas —una migración de base de datos, un comando que se corre así y no de otra forma— mientras que un campo abierto pide dirección general y confianza. En el ejemplo de arriba conviven las dos cosas a propósito: agrupar diferencias es juicio y va en prosa, correr el validador es una única secuencia segura y va como comando literal.

Hay una trampa acá que se paga en calidad. Los prompts y skills escritos para modelos anteriores suelen ser demasiado prescriptivos para los actuales, y reducen la calidad en vez de mejorarla. Enunciar el objetivo y las restricciones rinde más que enumerar los pasos. El caso más claro es la verificación: pedir explícitamente que el modelo verifique su trabajo hoy produce sobre-verificación, porque el comportamiento ya viene de fábrica. Una instrucción que era necesaria hace dos generaciones ahora es ruido caro.

Dos detalles de arquitectura que evitan lecturas parciales. Mantené las referencias a un nivel de profundidad desde el SKILL.md — si advanced.md linkea a details.md, el modelo puede terminar previsualizando con head -100 y quedarse con información incompleta. Y a los archivos de referencia de más de 100 líneas ponéles una tabla de contenidos arriba, para que una lectura parcial igual muestre el alcance completo de lo que hay.

Cuándo una skill y cuándo es entusiasmo

Acá está la decisión real. La documentación de Anthropic propone cuatro tiers de complejidad —una sola llamada a la API, un workflow con lógica en tu código, un agente con tus propias herramientas, un agente gestionado donde el proveedor corre el loop y hospeda el sandbox— y la recomendación explícita es empezar por el más simple que resuelva. La misma lógica aplica adentro del diseño de un agente: la skill es un tier, y hay tiers más baratos.

Ojo con la segunda fila, que es la que más se subestima. Un schema de herramienta con sus parámetros descritos y sus condiciones de disparo cuesta habitualmente cientos de tokens: es del mismo orden que varias skills juntas. Una herramienta dedicada no es la opción barata; es la opción que compra control.

La última fila es la que más se ignora. El supuesto por defecto de la documentación es que el modelo ya es muy capaz, y que cada párrafo tiene que justificar su costo en tokens. Explicarle qué es un PDF antes de decirle qué librería usar es pagar 150 tokens por 50 tokens de información.

Los cuatro criterios que Anthropic usa para decidir si construir un agente sirven igual de bien acá, y si alguno da que no conviene quedarse un tier más abajo. Complejidad: ¿la tarea es multi-paso y difícil de especificar de antemano? Si son tres líneas fijas, van en el system prompt. Valor: ¿el resultado justifica el costo? Si la skill se dispara una vez por semana pero su descripción viaja en diez mil requests, hacé la cuenta. Viabilidad: ¿el modelo es capaz en este tipo de tarea? Existe un benchmark que ataca esa pregunta de frente —87 tareas en 8 dominios, con skills curadas y verificadores determinísticos— y es mejor punto de partida que la intuición. Costo del error: ¿se detecta y se revierte? Una skill que orquesta operaciones destructivas sin validación intermedia tiene un blast radius que no se corresponde con su aparente inocencia de archivo markdown.

De ahí sale una heurística, y la declaro como lo que es: una heurística sin medir. Una skill se justifica cuando el conocimiento es largo, específico de tu organización, y aplica a una fracción chica de los pedidos. Las tres condiciones juntas. Si es corto, va arriba. Si aplica a todo, va arriba. Si el modelo ya lo sabe, no va a ningún lado. Lo que convierte esa regla en dato es la medición de la sección siguiente.

Skill o herramienta dedicada

Son cosas distintas y se confunden seguido. Una skill le dice al modelo cómo hacer algo. Una herramienta le da al harness un punto de intercepción.

Una herramienta bash da alcance máximo, pero al harness solo le llega un string opaco: no puede pedir confirmación con sentido, ni verificar que el archivo no cambió desde la última lectura, ni renderizar UI propia, ni paralelizar lo que es seguro paralelizar. Promover una acción a herramienta dedicada le da argumentos tipados y con eso todo lo anterior. La regla práctica: empezar con bash por alcance, promover a herramienta dedicada lo que necesite gate, render, auditoría o paralelismo. La reversibilidad es el mejor criterio disponible — lo difícil de revertir se promueve.

Si lo que te falta es procedimiento, escribí una skill. Si lo que te falta es control, escribí una herramienta. Una skill que dice "antes de correr esto pedí confirmación" es un guardrail que depende de que el modelo obedezca. Una herramienta dedicada con confirmación en el harness es un guardrail que no depende de nadie.

Lo que cuesta tener muchas

Los ~100 tokens por skill hacen que veinte skills se sientan gratis. La cuenta es la que sigue, y conviene hacerla con los números propios.

Cuarenta skills instaladas son unos 4.000 tokens de metadata en cada request. Un equipo chico que hace diez mil requests al mes paga 40 millones de tokens de metadata en el mes, y los paga en todos los pedidos, incluidos los que no disparan ninguna skill. La aritmética es propia; lo verificado es el multiplicando.

El segundo número es peor y es el que nadie mira. Los ~100 tokens son la estimación de la doc para una descripción normal. Una descripción que usa los 1024 caracteres completos cae —por estimación mía, no de la documentación— más cerca de 260 a 290 tokens: unas dos veces y media la cifra de referencia. Ese múltiplo lo paga cada pedido que no usa la skill. Cuarenta skills con descripciones maxeadas no son 4.000 tokens fijos, son más de 10.000. La documentación de Codex de OpenAI pone la restricción del otro lado y en formato de presupuesto: como máximo 2% de la ventana de contexto del modelo, u 8.000 caracteres cuando la ventana es desconocida. Es una buena vara para chequear si tu setup se pasó.

Sobre esos tokens fijos se apilan dos costos que no se cuentan en tokens. Uno ya lo vimos: cada instalación, borrado o edición de descripción invalida el cache de la sesión. El otro es la selección. La documentación menciona explícitamente escenarios de 100+ skills disponibles, y ahí la descripción deja de ser una etiqueta y pasa a ser un problema de desambiguación. Dos skills con descripciones que se solapan producen disparos erráticos: a veces una, a veces la otra, a veces ninguna. Ese fallo no aparece en una prueba manual — aparece en producción, de forma intermitente.

Lo que corresponde acá es lo mismo que en cualquier otro componente que puede fallar en silencio: medirlo. La recomendación oficial es construir las evaluaciones antes de escribir la documentación extensa. Corré tareas representativas sin la skill, documentá los fallos concretos, armá al menos tres escenarios que testeen esos gaps, medí la línea de base, y recién ahí escribí lo mínimo que los haga pasar.

Un escenario de disparo tiene esta forma, y se escribe antes que el SKILL.md:

Caso 3 — cierre de conciliación con skill vecina instalada

skills declaradas:
  - conciliando-movimientos
  - exportando-planillas
  - desplegando-servicios

query: "armá el cierre de julio para el equipo de finanzas"

archivos de entrada:
  - fixtures/movimientos-julio.csv
  - fixtures/comprobantes-julio.csv

comportamientos esperados:
  - se lee conciliando-movimientos/SKILL.md, y ninguna otra skill
  - NO se dispara exportando-planillas: el pedido no menciona planilla
  - las columnas del output siguen el mapeo de REFERENCE.md para ese banco
  - los totales cuadran contra fixtures/esperado-julio.csv
  - se ejecuta scripts/validate.py y su salida es "OK"

Cada línea de la lista se verifica sola y falla sola. La tercera es la que la mayoría de las suites olvida: el disparo de más es un fallo, no un empate. Si eso te suena al artículo sobre evals, es exactamente eso: si tu eval de disparo de skills no puede bloquear un merge, no es una eval.

Lo que se rompe

Cuatro cosas que sorprenden después de haber decidido bien todo lo anterior.

Las skills no sincronizan entre superficies. Una skill subida a claude.ai no está disponible en la API, las de la API no están en claude.ai, y las de Claude Code son filesystem y están separadas de las dos. Si tu equipo trabaja en varias, es distribución manual por cada una.

El entorno de ejecución cambia según dónde corra, y son tres entornos distintos, no dos. En la API no hay acceso a red ni instalación de paquetes en runtime: solo lo preinstalado. En Claude Code hay el mismo acceso a red que cualquier programa de la máquina. Y en claude.ai el acceso a red no es fijo: depende de la configuración del usuario y del administrador, y puede ser total, parcial o nulo. Una skill que hace un fetch anda perfecto en Claude Code, falla siempre en la API, y en claude.ai depende de una configuración que vos no controlás. Es la combinación más incómoda de las tres, porque el mismo archivo se comporta distinto para dos personas del mismo equipo.

Cargar la skill tampoco garantiza que siga viva al final. Hay un estudio white-box sobre agentes de auditoría de código que fija la tarea y 24 chequeos, varía el contexto alrededor y clasifica dónde falla primero: en trayectorias largas con muchas herramientas, los requisitos que la skill trajo al principio dejan de estar activos mucho antes de que el agente termine. Diferir el costo resuelve el problema de entrada, no el de permanencia.

Y la superficie de seguridad es real. Una skill es instrucciones más código que el modelo va a ejecutar con los permisos que tenga en ese momento. La recomendación oficial es tratarlas como instalación de software: auditar todos los archivos del paquete —SKILL.md, scripts, recursos— y desconfiar particularmente de las que traen contenido de URLs externas, porque ese contenido puede portar instrucciones. Una skill maliciosa no necesita un exploit; le alcanza con texto convincente en un archivo que el modelo lee como si fuera propio.

Herramientas

• anthropics/skills — el repositorio oficial y público. La mejor fuente de SKILL.md reales para ver estructura en vez de inventar un ejemplo de juguete; incluye el skill-creator y las skills de documentos.
• Claude Code (Skills) — el harness donde las skills son puro filesystem: se dejan en ~/.claude/skills/ o en .claude/skills/ del proyecto y el agente las descubre solo. Es el camino más corto para escribir la primera. Requiere plan pago o créditos de API.
• VS Code Agent Skills — la implementación con Copilot. Documenta la misma carga en tres etapas y lee de .github/skills/, .claude/skills/ o .agents/skills/. La prueba concreta de que el formato ya es compartido.
• APM (Agent Package Manager) — gestor de dependencias de Microsoft para skills, servidores MCP y configuración de agentes. Se declaran en apm.yml y se instalan igual en Claude Code, Codex, VS Code y Cursor, con resolución transitiva estilo npm. La respuesta al problema de no saber qué skill está instalada dónde.
• agent-skills-eval — test runner para medir si una skill efectivamente mejora el output. Encaja con la recomendación de medir la línea de base sin la skill antes de escribirla.
• Ratel — utilidad de ingeniería de contexto que rutea skills y herramientas con búsqueda BM25 en proceso, para no volcar todos los descriptores en la ventana. Un ejemplo concreto de cómo se mitiga el costo de tener muchas.

El criterio

Antes de escribir el SKILL.md, tres preguntas en orden. ¿Esta instrucción aplica a la mayoría de los pedidos? Entonces va en el system prompt y no es una skill. ¿El modelo ya lo sabe? Entonces no va a ningún lado. ¿Lo que falta es control y no procedimiento? Entonces es una herramienta dedicada, no una skill.

Lo que sobrevive a las tres preguntas se escribe: descripción corta y prescriptiva sobre el cuándo, cuerpo por debajo de 500 líneas, especificidad proporcional a la fragilidad, referencias a un nivel, y tres escenarios de disparo que puedan fallar.

Todo lo demás se paga en cada request, para siempre, en pedidos que nada tienen que ver.