Skills

Un skill es saber hacer algo, escrito una vez y adjuntado a muchos agents: cómo se gestionan los reembolsos, cuál es el estilo de la casa, qué comprobaciones tiene que pasar un informe antes de salir.

Lo que sustituye es un campo de instrucciones que no para de crecer.

Veinte procedimientos en un solo prompt significa que cada run paga por los veinte, y el vigesimoprimero empuja la conversación fuera de la ventana. Los skills le dan la vuelta a eso:

flowchart LR
    A["the agent's capability catalog<br/><i>names + one-line descriptions only</i>"] --> B{is one relevant?}
    B -->|no| Z["no body loaded"]
    B -->|yes| C["load_capability - the body"]
    C --> D{does the body<br/>point at a file?}
    D -->|no| Z2[answer]
    D -->|yes| E["read_skill_resource - one file beside it"]
    E --> Z2

Veinte skills cuestan aproximadamente veinte descripciones en lugar de veinte procedimientos.

Descubrir es barato, no gratis

Cada skill vinculado está en el catálogo de capabilities que el modelo lee en cada turno, con su nombre y su descripción de una línea — así que vincular un skill cuesta tokens tanto si el modelo llega a abrirlo como si no.

Es una línea por skill frente a un cuerpo por skill, y por eso salen las cuentas. No es motivo para vincular un catálogo sin límite.

La otra mitad de la cuestión es quién los escribe. Un skill es una fila en la base de datos, editable en la UI, así que un responsable de soporte puede arreglar la política de reembolsos un martes por la tarde. Sin deploy, sin pull request, sin ingeniero.

¿Skill, archivo de contexto o colección de conocimiento?

Un skill es un procedimiento que el modelo carga cuando decide que la tarea ha llegado. Un archivo de contexto es conocimiento permanente — corto, siempre relevante, inyectado o leído bajo demanda. Una colección de conocimiento es un corpus demasiado grande para leerlo, al que se llega por búsqueda.

La forma

---
name: refund-policy
description: When a refund is given without asking, when it needs approval, and how to say no.
category: support
---

# Refunds

Most refund questions are decided by the order date and one exception. Check
those before escalating anything.

La página **Skills** muestra en cada tarjeta el comienzo del cuerpo — sin front
matter, unas pocas líneas — con una hoja apilada detrás por cada archivo que
lleva el skill. `GET /api/v1/skills` devuelve ese comienzo como `excerpt`; el
cuerpo en sí se carga al abrir el skill.

## Decide without asking
...

description es el campo que decide si el skill llega a cargarse alguna vez

Es la única parte que el modelo ve gratis. Escríbela como cuándo recurrir a esto, no como un título.

Un skill puede llevar recursos — más archivos a su lado, cargados bajo demanda. refund-policy incluye un exceptions.md, y el cuerpo dice cuándo consultarlo.

Eso es la misma revelación progresiva un nivel más abajo: el detalle que solo algunas conversaciones necesitan no tiene por qué estar en el cuerpo que carga cada conversación relevante.

category es una de veinte sugerencias (support, engineering, finance, legal, security, marketing, …) y alimenta el filtro del listado de skills. No tiene ningún efecto sobre lo que ve el agent — el modelo elige por description, nunca por categoría.

Cómo lee uno un agent

A través de la capability skills. Cada skill que recibe un agent se convierte en una capability propia, listada para el modelo con su nombre y su descripción y abierta cuando hace falta:

Cómo	Qué hace
El catálogo de capabilities	Nombres y descripciones de una línea de todo lo vinculado a este agent
load_capability	El cuerpo completo de un skill, traído a la conversación
read_skill_resource	Un archivo al lado de un skill

load_capability es la herramienta del propio framework de agents, no una que publique esta plataforma, así que un spec no la concede ni la renombra. Sí puede controlarla, porque es la llamada que abre un skill: tool_approval sobre ella es como un agent pregunta a una persona antes de que un skill llegue al modelo, y un spec que controlaba el antiguo load_skill se migra a ella en lugar de quedarse sin control. Lo que la capability aporta como herramienta propia es read_skill_resource, y solo cuando al menos uno de los skills vinculados trae un archivo que leer.

Un spec vincula skills por id en skill_ids, así que un agent ve los que se le dieron y nada más.

Desde el propio skill. Cada tarjeta de la página de Skills tiene Add to an agent: eliges el agent y el skill se añade a su borrador, con la capability Skills activada, listo para publicar en el Builder. La tarjeta dice también qué agents usan el skill, o que todavía ninguno. Los archivos de contexto y las bases de conocimiento ofrecen lo mismo.

El nombre de un skill es el id con el que un modelo lo carga, así que tiene la forma en que los modelos escriben ids: minúsculas y dígitos unidos por guiones simples, como refund-policy. Un nombre con espacios o mayúsculas se rechaza al crear el skill. Un nombre que el modelo tuviera que reproducir exactamente, como Refund policy, lo cargaba como refund-policy, y dos suposiciones erróneas terminan el turno (#1911).

Un skill no puede llamarse como una capability. Cada uno se archiva bajo su propio nombre en el mismo espacio que knowledge, planning y los demás, así que un skill llamado planning en un agent que también tiene la capability de planning es un duplicado que el framework rechaza antes del primer token. Crearlo se rechaza, y publicar un agent vinculado a un skill con ese nombre, también.

Habilitar la capability sin ningún skill vinculado no sirve de nada — dale skills al agent, o deja la capability apagada.

En un workspace, un skill también son archivos

Un agent que tiene a la vez skills y un workspace recibe además cada skill escrito dentro de él:

/workspace/skills/<name>/SKILL.md      the body, with its name and description
/workspace/skills/<name>/<resource>    each resource, beside it

Esto es lo que hace útil el script de un skill. Un skill cuyo recurso era reconcile.py antes se le entregaba al modelo como texto que podía citar y no ejecutar, mientras el mismo agent tenía execute a una llamada de herramienta de distancia. En disco, se ejecuta.

No existe run_skill_script

El propio execute de la sandbox ya lleva las reglas de permisos del workspace y los techos que fija el operador. Una segunda forma de ejecutar cosas sería un segundo conjunto de reglas que equivocar.

Un agent puede proponer un cambio; una persona lo hace

Esos archivos se pueden escribir, y lo que el agent escribe no se aplica.

Un skill son instrucciones que sigue en cada run todo agent vinculado a él. Un agent que pudiera editar uno directamente podría reescribir lo que hace otro agent, dentro de una conversación que nadie está revisando, y el siguiente lector no tendría forma de distinguir una mejora meditada de una alucinada.

Así que una escritura se convierte en una propuesta, y aparece encima de la lista en la página Skills para cualquiera que tenga skills:edit:

• Apply reescribe el skill y sube su versión, lo que alcanza a cada agent vinculado en su siguiente run.
• Discard conserva el registro. Un agent que propone la misma edición una y otra vez le está diciendo algo a alguien sobre ese skill, y una fila borrada lo vuelve invisible.

Una decisión sobre una propuesta es definitiva

Aplicar dos veces subiría una versión contra un cuerpo ya almacenado, y descartar algo aplicado le diría a un lector que nunca llegó a entrar.

La propuesta lleva el cuerpo entero en lugar de un diff, así que un revisor semanas después está comparando dos versiones completas en vez de aplicando un parche en un sitio al que nunca estuvo destinado.

Dos cosas se rechazan en lugar de adivinarse: un directorio que el agent creó sin ningún SKILL.md dentro, y uno cuyo frontmatter destrozó. Y un recurso borrado deliberadamente no es un cambio, porque un archivo que el modelo nunca tocó y uno que quiso borrar dejan la misma ausencia.

Tres turnos de una conversación refinando el mismo skill dejan una propuesta, no tres. A un revisor al que se le hace la misma pregunta tres veces se le ha dado más trabajo, no más información. Las propuestas del workspace respetan los mismos límites que los skills almacenados: nombre de 1 a 64 caracteres y descripción de hasta 500. Una propuesta fuera de estos límites se omite con una advertencia; sus archivos originales permanecen intactos. Un savepoint aísla la escritura para que una propuesta rechazada no impida guardar el estado y el coste del turno.

Cómo llegan los skills a una organización

Escribe uno. Skills → New, en la UI. Este es el camino normal.

Los incluidos ya están ahí. El repositorio trae cuatro: tres ejemplos trabajados — refund-policy, code-review e incident-report — y artifact-pages, que enseña a un agent a construir una página para la capability Apps. Toda organización empieza con ellos. Crear una organización copia dentro la biblioteca entera que se distribuye, como skills normales, cuyo dueño es el owner de la organización y visibles para la organización.

La página de skills muestra una sola lista, con una insignia built-in sobre cualquiera cuyo nombre coincida con la biblioteca distribuida. Esos cuatro no se eligen — llegan solos, una vez, al crear la organización.

Y desde ese momento son vuestros. Un skill sembrado es una fila corriente: se edita, se deshabilita o se borra. Nada devuelve uno borrado.

Esto es un cambio. El listado se rellenaba solo — copiaba dentro cualquier nombre incluido que la organización no tuviera, cada vez que alguien abría la página —, así que un built-in borrado volvía en la visita siguiente y deshabilitarlo era la única forma de retirarlo. También significaba una página que escribía filas mientras leía. La galería es donde se elige un skill, y el comando de seed de abajo es como un deployment reparte a propósito uno nuevo de los incluidos.

Una organización creada antes de un nuevo skill incluido no lo recibe sola

Ejecutad seed-skills para ella, o instalad el skill desde la galería. Las dos vías son deliberadas, y de eso se trata: nada llega al cargar una página.

El comando de seed hace lo mismo desde un terminal, para instalaciones con scripts:

uv run agenticos cmd seed-skills                    # every organization
uv run agenticos cmd seed-skills --org <org-id>     # one
uv run agenticos cmd seed-skills --dry-run          # say what would happen, do nothing
uv run agenticos cmd seed-skills --replace          # also overwrite copies edited here

Instala lo que falta y actualiza lo que nadie ha editado. Cada copia registra de qué versión incluida se escribió, así que cuando una versión mejora un skill incluido, la copia intacta de una organización se sustituye por la nueva — con sus archivos, con la versión incrementada y una entrada de auditoría skill.refreshed.

Una copia editada aquí se deja exactamente como está, así que una política de reembolsos editada sobrevive a un reseed; --replace es la única forma de tomar la versión incluida por encima de esas ediciones, y la entrada de auditoría lo dice. Una copia hecha antes de que se registraran las versiones y distinta de la incluida también se informa y se deja, porque nada puede decir si se editó.

El comando imprime qué hizo con cada skill, y --dry-run imprime el mismo plan sin escribir.

e2e/seed.setup.ts también crea uno a través de la UI, que es contra lo que afirma la suite E2E.

La galería — setenta más, y ninguno llega sin invitación

Skills → Skill gallery abre un catálogo de skills listos para usar agrupados por sector: sanidad, finanzas y seguros, comercio electrónico e impresión bajo demanda, equipos de software, sector público y utilities, servicios jurídicos y profesionales, fabricación y logística. Diez de cada.

Elige un sector y luego instala un skill o el estante entero. Desde ese momento es un skill normal que la organización posee y edita, exactamente igual que uno incluido.

La galería es opcional, y esa es toda la diferencia

Los cuatro incluidos viven en app/core/catalog/skills/ y se copian automáticamente en todas las organizaciones. La galería vive en app/core/catalog/skill_gallery/ y no se copia en ninguna — la lee el mismo parser, desde un segundo directorio, y nunca se siembra.

Setenta skills sectoriales en el primer directorio habrían sido setenta filas que nadie pidió, en cada tenant, en el siguiente deploy.

Instalar un estante del que ya tienes uno de sus skills instala el resto y deja ese en paz: un nombre existente se omite en lugar de sobrescribirse, y la petición responde con lo que instaló, lo que omitió y cualquier clave que este deployment no incluya.

Añadir a la galería es igual que añadir un skill incluido — una carpeta con un SKILL.md, bajo el sector al que pertenece — con una regla extra: su nombre no puede chocar con el de un skill incluido ni con el de otro skill de la galería, y es el nombre de su carpeta. La instalación empareja por nombre, así que una colisión se saltaría en silencio para siempre. Un test lee los setenta y falla con cualquiera de los dos errores.

Sembrar crea copias

Un skill sembrado es un skill normal propiedad de la organización, editable desde el momento en que la organización existe. Es una copia, no un enlace.

Eso es deliberado. La gracia de un skill es que un responsable de soporte pueda arreglar la política de reembolsos sin un deploy, y un enlace vivo a la copia del repositorio le quitaría exactamente eso — la organización estaría leyendo un archivo que solo un ingeniero puede cambiar.

Editar y borrar son los dos definitivos, como siempre. Deshabilitar sigue ahí para un skill que la organización quiere conservar pero no ejecutar — cada agent lo respeta —, pero ha dejado de ser la única forma de deshacerse de un built-in.

Por qué la biblioteca se distribuye y no se descarga

Añadir un skill a la biblioteca distribuida o a la galería es un deploy.

La alternativa — importar desde una URL de git — cuesta red saliente desde el backend, un parser apuntando al repositorio de otra persona y una promesa sobre un contenido que nadie aquí ha leído. Cada carpeta de app/core/catalog/skills/ y app/core/catalog/skill_gallery/ es la misma pequeña promesa que hace el catálogo MCP: alguien lo miró.

¿Skills o conocimiento?

Responden a preguntas distintas, y la diferencia importa cuando un agent recibe la equivocada.

	Skills	Conocimiento
Contiene	Procedimiento — cómo hacemos esto	Documentos — lo que sabemos
Lo escribe	Una persona, deliberadamente	Se ingiere en bloque
Se recupera por	El modelo eligiendo un nombre	Búsqueda semántica sobre fragmentos
Cita	Nada; es la instrucción	El pasaje y su fuente
Escala	Decenas	Miles de documentos

Cuál es cuál

"Los reembolsos de más de 500 £ necesitan un manager" es un skill. El contrato firmado que lo dice es conocimiento.

Un agent que gestiona reembolsos normalmente quiere las dos cosas, y las dos capabilities se componen — skills para el procedimiento, knowledge para la evidencia.

Acceso

Los skills son recursos con ámbito de organización, gobernados igual que los agents y las colecciones: visibilidad más grants por fila encima del rol. Consulta Permisos.

Vincular un skill lo presta

Cada run del agent lee el cuerpo y los archivos, lo haya ejecutado quien lo haya ejecutado — así que publicar exige que el publicador tenga skills:view sobre esa fila.

Esa comprobación pasa por resolve_access, así que un grant cuenta: un miembro con quien se compartió un skill puede vincularlo sin ser promovido.

Un skill al que no pueden llegar se rechaza como Skill not found: <id>, redactado exactamente igual que un id que no existe. Los skills se vinculan por UUID desde la API y desde un borrador editado a mano, no solo se eligen de la lista del Builder, y un rechazo que se leyera distinto iría cartografiando los skills privados de la organización a golpe de conjetura.

La misma comprobación se ejecuta sobre los skill_ids de un especialista inline, y se informa con el nombre del especialista.

En tiempo de ejecución no se vuelve a comprobar nada. Los skills del spec congelado se resuelven dentro de la organización del run y se le entregan al agent — la regla que ya siguen las colecciones y los delegados, la de que la referencia se comprueba una vez, al publicar.

La alternativa es peor de dos maneras concretas:

• Todo contexto sin sujeto — una clave de API, un widget embebido, un mensaje de canal — es rechazado por resolve_access por diseño, así que una comprobación por runner despojaría de todos sus skills precisamente a esas superficies.
• Donde sí hay un sujeto, una misma versión publicada le daría a un miembro —cuyo rol solo alcanza los skills compartidos— instrucciones más pobres que las que le da a un builder, con la diferencia visible en ninguna parte.

Un skill borrado o deshabilitado después de publicar se omite con un aviso en lugar de hacer fallar el run. El agent es menos capaz, no está roto.

Recapitulación

• Un skill es procedimiento, escrito por una persona, y solo se carga cuando el modelo decide que su description es relevante — descubrir cuesta una línea por skill, y el cuerpo no cuesta nada hasta que se abre.
• En un workspace un skill también son archivos, que es lo que hace ejecutables sus scripts.
• Un agent propone una edición; una persona la aplica, una sola vez, y la decisión es definitiva.
• Vincular un skill lo presta, así que el publicador tiene que poder verlo — y no se vuelve a comprobar nada en tiempo de ejecución.
• La galería son setenta skills listos para usar por sector, instalados a petición — a diferencia de los tres incluidos, que llegan solos.