Skills de la app
Un skill de la app es un conjunto de instrucciones que uno de los agentes de IA de tu app carga cuando las necesita, en lugar de llevarlas en su system_prompt en cada turno.
Al principio el agente solo ve el nombre y la descripción de cada skill. Cuando una tarea necesita un skill, el agente carga sus instrucciones. Un skill no cuesta nada hasta que el agente lo carga, así que puedes dar al agente procedimientos largos y material de referencia sin hacer más pesada cada conversación.
Los skills de la app son instrucciones para los agentes propios de tu app. No son el skill que Desarrollar con Claude Code instala para tu agente de programación.
¿Skill o system prompt?
El system_prompt se lee en cada turno. Un skill se lee solo cuando el agente decide cargarlo.
Poner en el system_prompt | Poner en un skill |
|---|---|
| El rol del agente | Conocimiento que solo necesitan algunas tareas |
| Reglas que siempre se aplican | Procedimientos largos, como un diagnóstico o una comprobación de puesta en marcha |
| Reglas de seguridad: lo que el agente nunca debe hacer o debe confirmar primero | Referencia del dominio, como códigos de fallo o los parámetros de una máquina |
| Datos breves |
Un agente que nunca carga un skill debe seguir cumpliendo todas las reglas de seguridad, así que esas reglas permanecen siempre en el system_prompt.
Formato de la carpeta de un skill
Los skills viven en el repositorio de tu app, junto a los demás archivos de .ironflock/:
.ironflock/
├── ai-template.yml
└── skills/
└── machine-diagnosis/
├── SKILL.md
└── references/
└── codes-press.md.ironflock/skills/<name>/SKILL.mdes obligatorio. Empieza con un frontmatter YAML, seguido de las instrucciones en Markdown..ironflock/skills/<name>/references/<file>.mdes opcional. Usa archivos de referencia para el material que solo necesitan algunas tareas. El agente carga cada uno solo cuando necesita ese archivo, por lo que cada archivo de referencia debe entenderse por sí solo.SKILL.mdindica qué archivo leer y cuándo.- No puede haber nada más en la carpeta de skills: ni scripts, ni imágenes, ni enlaces simbólicos. Todos los archivos son texto UTF-8.
El frontmatter tiene dos campos:
---
name: machine-diagnosis
description: >-
How to find out why a machine is TOO_HOT or shows NO_READING. Load it
before you answer such a question.
---| Campo | Descripción |
|---|---|
name | Debe ser igual al nombre de la carpeta. |
description | Texto plano. Es todo lo que el agente ve hasta que carga el skill. |
Indicar un skill en un agente
Un skill no hace nada hasta que un agente lo indica. En .ironflock/ai-template.yml, añade la clave skills al agente y nombra cada skill por el nombre de su carpeta:
machines:
main: true
skills: [machine-diagnosis]Escribe solo el nombre de la carpeta. No empieces nunca una entrada con app/ ni project/.
Al agente se le ofrece el skill como app/<name>, aquí app/machine-diagnosis. El texto de tu system_prompt o de tu tool_description que menciona un skill usa esa forma.
Cada carpeta de skill debe ser indicada por al menos un agente, y cada agente indica un skill una sola vez.
Skills de la plataforma
Una entrada con la forma platform/<name> está reservada para los skills que la plataforma ofrece a las apps. Todavía no hay ningún skill de la plataforma disponible, así que una entrada así hace fallar hoy la compilación del release.
Límites
| Qué | Límite |
|---|---|
| Nombre del skill | Letras minúsculas y dígitos, unidos por guiones simples; como máximo 64 caracteres |
| Descripción | Como máximo 500 caracteres |
Instrucciones (SKILL.md) | Como máximo 20.000 caracteres |
| Un archivo de referencia | Como máximo 40.000 caracteres |
| Archivos de referencia por skill | Como máximo 20 |
| Skills por app | Como máximo 20 |
| Todos los archivos de skills de una app juntos | Como máximo 2 MiB |
| Skills que indica un agente | Como máximo 20 |
Qué comprueba la compilación del release
Cuando creas un release, la compilación comprueba los skills junto con ai-template.yml. Si una comprobación falla, el release no se compila y se muestra el primer problema encontrado. Corrígelo y crea el release de nuevo.
La compilación falla cuando:
- un agente indica un skill que no tiene carpeta;
- una carpeta de skill no la indica ningún agente;
- la app tiene una carpeta de skills pero no tiene
ai-template.yml; - una entrada de
skillsempieza conapp/oproject/; - una entrada empieza con
platform/(todavía no hay ningún skill de la plataforma disponible); - un archivo de la carpeta de skills no es texto UTF-8, es un enlace simbólico, o no es
SKILL.mdni un archivoreferences/<file>.md; - se supera un límite de la tabla anterior;
- un agente tiene una herramienta llamada
load_skill. El nombre está reservado para cargar skills, en todas las apps.
Ejemplo
Este skill le dice al agente cómo averiguar por qué una máquina notifica un fallo. Aquí está abreviado. Una app nueva empieza con tres skills completos en .ironflock/skills/ que puedes leer, cambiar o eliminar.
.ironflock/skills/machine-diagnosis/SKILL.md:
---
name: machine-diagnosis
description: >-
How to find out why a machine is TOO_HOT or shows NO_READING, or what is
wrong with a machine a user asks about: which rows to read, when to read the
machine now with current_reading, and what to tell the user. Load it before
you answer such a question.
---
# Diagnosing a machine
A user asked why a machine is too hot, why it has no reading, or what is wrong
with it. Find the cause in the app's tables and at the machine, then answer
with the evidence. You only read: you cannot change the limit or a machine.
## 1. Find the device and its state
Run with `execute_sql`:
```sql
SELECT DISTINCT ON (device_id) device_id, device_name, state, tsp
FROM devices
ORDER BY device_id, tsp DESC
```
`state` is `OK`, `TOO_HOT` or `NO_READING`. When the user named no machine,
take the devices whose state is not `OK`.
## 2. Check the machine now
Call `current_reading` for the device and compare its values with the newest
rows of `measurements`. When the call fails, the device is offline: say since
when.
Do not tell anyone that a machine running too hot is safe to keep running.El agente que lo indica, en .ironflock/ai-template.yml:
machines:
main: true
tool_description: |
Delegate to this agent when the user asks about the state of a machine.
system_prompt: |
You answer questions about the machines this app watches. You only read.
Never tell anyone that a machine running too hot is safe to keep running.
When a user asks why a machine is too hot or has no reading, load the
skill app/machine-diagnosis and follow it.
data_access: true
skills: [machine-diagnosis]
tools:
current_reading:
description: Reads the machine at one device now.
topic: current_readingLa frase del system_prompt que empieza con “When a user asks” se refiere al skill como app/machine-diagnosis. La regla de seguridad permanece en el system_prompt, porque un agente que no carga el skill debe seguir cumpliéndola.
Probar skills sin un release
No necesitas un release para probar un agente o un skill. El IDE en la nube tiene un chat de desarrollo que ejecuta tu propia copia de trabajo.
En el panel lateral del IDE en la nube, la sección Agentes de IA tiene dos acciones:
- Abrir chat de desarrollo aplica tu copia de trabajo y abre un chat que la usa.
- Actualizar agentes de IA aplica los cambios posteriores en
ai-template.ymly en los skills.
El chat de desarrollo:
- ejecuta tu copia de trabajo de la app, con el backend de datos de desarrollo del proyecto;
- es el asistente habitual del proyecto, con los agentes, herramientas y skills de esta app tomados de tu copia de trabajo;
- es el único chat que los recibe. A nadie más, ni a ningún otro chat, se le ofrece tu copia de trabajo.
Un chat de desarrollo en marcha usa tus cambios a partir de su siguiente mensaje, así que puedes cambiar un skill, hacer clic en Actualizar agentes de IA y volver a preguntar en el mismo chat.
Si la plantilla o un skill no es válido, se muestra el mismo mensaje que en la compilación de un release y se sigue usando la versión anterior.
El chat de desarrollo necesita el backend de datos de desarrollo de la app en el proyecto del dispositivo seleccionado.
Dónde ven los usuarios los skills
En el Studio, la pestaña Plugin de IA de la app lista cada agente con sus skills y muestra el nombre y la descripción de cada skill. El texto del skill nunca se muestra ahí.
Instalaciones anteriores
Un appliance que todavía no se ha actualizado instala la app y la ejecuta. Sus agentes funcionan sin los skills y se lo dicen al usuario cuando una tarea necesita uno. Cuando el appliance se actualiza, los skills llegan con la siguiente sincronización de la app.
Escribir buenos skills
- La descripción dice para qué sirve el skill y cuándo cargarlo. Hasta que el agente carga el skill, la descripción es todo lo que ve. Usa las palabras que usan tus usuarios y tus datos, como valores de estado, síntomas y tareas, y termina con cuándo cargar el skill: “Load it before you answer why a machine is TOO_HOT.” Una descripción como “Information about machines” nunca se carga en el momento adecuado.
- Haz que las instrucciones sean autosuficientes. El agente las lee en mitad de una tarea, con un usuario esperando. Nombra con exactitud las tablas, columnas y herramientas de tu app en lugar de depender del
system_prompt. - Escribe pasos imperativos en el orden en que deben seguirse. Indica cuándo parar y qué decirle al usuario.
- Indica lo que no se debe hacer.
Siguientes pasos
- Agentes y Herramientas de IA — La referencia de
ai-template.yml - Releases y la tienda de aplicaciones — Publica tu app