Skip to Content
Desarrollo de apps IoTSkills de la app

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_promptPoner en un skill
El rol del agenteConocimiento que solo necesitan algunas tareas
Reglas que siempre se aplicanProcedimientos 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 primeroReferencia 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.md es obligatorio. Empieza con un frontmatter YAML, seguido de las instrucciones en Markdown.
  • .ironflock/skills/<name>/references/<file>.md es 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.md indica 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. ---
CampoDescripción
nameDebe ser igual al nombre de la carpeta.
descriptionTexto 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 skillLetras minúsculas y dígitos, unidos por guiones simples; como máximo 64 caracteres
DescripciónComo máximo 500 caracteres
Instrucciones (SKILL.md)Como máximo 20.000 caracteres
Un archivo de referenciaComo máximo 40.000 caracteres
Archivos de referencia por skillComo máximo 20
Skills por appComo máximo 20
Todos los archivos de skills de una app juntosComo máximo 2 MiB
Skills que indica un agenteComo 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 skills empieza con app/ o project/;
  • 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.md ni un archivo references/<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_reading

La 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.yml y 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

Last updated on