🏷️ Dos sentidos de "skill"
La palabra «skill» tiene dos sentidos que cuestan cosas diferentes. (a) La descripción de la skill — la línea corta que aparece en la lista de skills — queda siempre en el prefijo estable. (b) O contenido completo (el documentazo) solo se carga cuando la skill está invocada.
Qué es
Una skill se presenta al modelo con una descripción breve (barata, siempre presente) y carga su contenido solo cuando se necesita. Son dos bloques con costos y momentos distintos.
Por qué aprenderlo
Porque, si no separas las dos cosas, piensas que "toda skill es cara". En realidad, solo pesa el contenido, y eso ocurre una sola vez, al invocarla.
Descripción (a)
Línea breve en la lista de skills. Siempre al principio estable. Barata y constante.
Contenido (b)
El documento completo. Solo se incluye cuando se invoca la skill. Pesa una vez; después se convierte en una lectura barata.
Conceptos clave
Descripción = siempre presente, barato.
Contenido = bajo demanda, cuesta 1×.
Invocar = traer el contenido a la conversación.
Tener muchas skills listadas ≠ cargarlas todas.
➕ Skill en medio NO reinicia el caché
Cuando se invoca una skill en medio de la conversación, su contenido se incorpora adjuntado al FINAL del historial — no en la posición 0. Todo lo anterior sigue siendo válido y se lee a bajo costo; solo se guarda el bloque nuevo de la skill (un write). En los turnos siguientes, ya está lectura barata.
Qué es
Anexar al final preserva todo el prefijo anterior: la coincidencia de prefijo sigue funcionando hasta el punto donde comienza el contenido nuevo. Por lo tanto, no hay reinicio, solo una escritura incremental.
Por qué aprenderlo
Porque quita el miedo a invocar skills durante el trabajo. Ese turno puede mostrar un % de caché más bajo (la escritura de la skill), pero es una inversión única: ya en el siguiente turno cuesta poco.
La misma cantidad de contenido nuevo, resultados opuestos: añadir al final conserva la caché; cambiar la posición 0 lo reinicia todo.
Conceptos clave
Anexa al final = prefijo intacto.
Write único del bloque de la skill.
Turnos siguientes = read barato.
Invocar skill ≠ restablecer la caché.
💥 Romper la lista de tools = posición 0
Las herramientas se renderizan en la posición 0 — antes de system y del historial. Por eso, cambiar la lista tools
invalida TODO: como la coincidencia del prefijo empieza desde el primer byte,
cualquier cambio en el bloque de herramientas invalida todo el prefijo a partir de ahí.
Qué es
La lista tools ocupa la posición 0 en el orden de montaje tools → system → messages. Cambiar cualquier byte allí es el peor caso posible para el caché.
Por qué aprenderlo
Porque es el invalidator silencioso más caro. Saber que la posición 0 es sagrada cambia la forma en que conectas MCPs, editas descripciones de tools y armas la lista.
Atención
No es solo «agregar una tool». Eliminar, reordenar o cambiar un carácter también cuenta en una descripción. La posición 0 debe ser idéntica byte por byte entre requests.
Conceptos clave
tools = posición 0 del prompt.
Cambiar tools = reinicio total.
Orden: tools → system → messages.
Posición 0 = idéntica byte a byte.
🔨 Ejemplos de ruptura
Cuatro formas clásicas de romper la posición 0 sin darse cuenta. Todas modifican la lista
tools — a propósito o por accidente.
Conectar/desconectar un MCP a mitad de
Registra (o elimina) herramientas nuevas en la lista → la posición 0 cambia → invalida todo.
Cambiar description o input_schema
Basta con que cambie una palabra en una description o un campo en el schema: los bytes de tools cambian.
Orden no determinista
Montar tools de un set/dict sin ordenar → el orden varía entre solicitudes → fallo silencioso. (Es el tema del ejemplo copy-run de abajo.)
Activar/desactivar tools por modo/permiso
Cambiar de modo para habilitar o deshabilitar herramientas modifica la lista renderizada en la posición 0.
Qué es / Por qué aprender
Qué es: las cuatro causas más comunes de que la caché «desaparezca» sin motivo aparente — todas alteran la posición 0.
Por qué aprenderlo: reconocer el patrón hace que primero desconfíes de la lista de tools cuando cache_read_input_tokens se pone en cero.
Conceptos clave
MCP conectado en medio = tools nuevas.
1 palabra en la description ya lo rompe.
set/dict sin sort = orden variable.
El modo/permiso activa y desactiva tools.
🔍 Tool Search se anexa a propósito
O Tool Search carga el schema de una herramienta
adjuntando — sin cambiar la lista tools.
Esto se diseñó justamente para NO rompas la caché: descubrir una
herramienta mediante Tool Search es seguro; conectar un MCP que reescribe la lista, no.
Qué es
Tool Search trae el schema de una herramienta bajo demanda y lo adjunta al final (como una skill), preservando el prefijo. Es el mismo patrón «adjuntar al final = seguro» aplicado a las herramientas.
Por qué aprenderlo
Porque distingue dos caminos que parecen iguales: "traer una herramienta nueva a la conversación" puede ser seguro (Tool Search, se añade) o destructivo (reescribir tools, posición 0).
✓ Seguro
- ✓Descubrir una tool mediante Tool Search (se agrega al final).
- ✓Invocar skill (anexa contenido al final).
✗ Se rompe
- ✗Conectar un MCP que reescribe la lista de tools.
- ✗Editar la description/schema de una tool existente.
Conceptos clave
Tool Search adjunta el schema.
Hecho para no romper la caché.
Descubrir una tool ≠ reescribir tools.
El mismo principio que con las skills (el final = seguro).
👍 Regla práctica
La frase que resuelve el 90% de las decisiones del día a día: contenido nuevo al FINAL =
seguro. Cambiar la lista de tools o en el
prompt de sistema = reinicio de la posición 0.
Qué es
Una prueba mental de una línea: antes de cualquier cambio, pregúntate «¿esto cambia el comienzo del prompt o solo agrega algo al final?». Final = write barato; comienzo = reset.
Por qué aprenderlo
Porque no necesitas memorizar cada caso: la regla práctica clasifica cualquier acción nueva al instante como "segura" o "reinicio".
Consejo práctico
Pregunta siempre: «¿esto cambia el comienzo o solo agrega algo al final?» Si cambia el comienzo (tools/system), espera un reinicio. Si se añade al final (skill/Tool Search/mensaje nuevo), es un único write barato.
Ejemplo copy-run — hacer que el montaje de tools determinística
Objetivo: garantizar que la lista tools (posición 0) quede idéntica byte por byte en cada request. Iterar un set/dict sin ordenar, el orden varía → la caché nunca coincide.
# ❌ QUEBRA — ordem varia entre requests (cache nunca bate)
tools = [tool_schema(name) for name in <meu_set_de_tools>]
# ^ set/dict: ordem não garantida
# ✅ ESTÁVEL — ordena por nome → mesma sequência de bytes sempre
tools = [tool_schema(name) for name in sorted(<meu_set_de_tools>)]
# (se as tools forem dicts, serialize com chaves ordenadas também)
# payload = json.dumps(tool, sort_keys=True)Cómo verificar: haz la misma solicitud dos veces seguidas y mira el usage. Con el sorted(...), o cache_read_input_tokens deja de ser 0 entre requests iguales: señal de que la posición 0 quedó idéntica y el prefijo coincidió.
No arquivo <caminho que monta a lista de tools>, procure
onde `tools` é construída a partir de um set ou dict e:
1. ordene a serialização por nome (sorted / sort_keys=True);
2. confirme que a ordem fica estável entre dois requests;
3. me mostre o antes/depois do trecho.Conceptos clave
Fin = seguro (un solo write).
Inicio (tools/system) = restablecimiento.
sorted(...) deja estable la posición 0.
cache_read > 0 entre requests iguales = bien.
Resumen del módulo
Siguiente módulo:
2.3 — Invalidación a fondo