Skills do App
Um skill do app é um conjunto de instruções que um dos agentes de IA do seu app carrega sob demanda, em vez de carregá-las no system_prompt a cada turno.
O agente vê primeiro apenas o nome e a descrição de cada skill. Quando uma tarefa precisa de um skill, o agente carrega as instruções dele. Um skill não custa nada até o agente carregá-lo, então você pode dar ao agente procedimentos longos e material de referência sem tornar cada conversa mais pesada.
Os skills do app são instruções para os agentes do próprio app. Não são o skill que o Desenvolva com o Claude Code instala para o seu agente de programação.
Skill ou System Prompt?
O system_prompt é lido a cada turno. Um skill é lido apenas quando o agente decide carregá-lo.
Coloque no system_prompt | Coloque em um skill |
|---|---|
| O papel do agente | Conhecimento de que só algumas tarefas precisam |
| Regras que sempre valem | Procedimentos longos, como um diagnóstico ou uma verificação de comissionamento |
| Regras relevantes para a segurança: o que o agente nunca deve fazer ou deve confirmar antes | Referência do domínio, como códigos de falha ou os parâmetros de uma máquina |
| Fatos curtos |
Um agente que nunca carrega um skill ainda precisa manter todas as regras relevantes para a segurança, por isso elas ficam sempre no system_prompt.
Formato da Pasta de Skills
Os skills ficam no repositório do seu app, ao lado dos outros arquivos de .ironflock/:
.ironflock/
├── ai-template.yml
└── skills/
└── machine-diagnosis/
├── SKILL.md
└── references/
└── codes-press.md.ironflock/skills/<name>/SKILL.mdé obrigatório. Ele começa com um frontmatter YAML, seguido das instruções em Markdown..ironflock/skills/<name>/references/<file>.mdé opcional. Use arquivos de referência para material de que só algumas tarefas precisam. O agente carrega cada um apenas quando precisa daquele arquivo, então cada arquivo de referência deve fazer sentido por si só. OSKILL.mddiz qual arquivo ler e quando.- Nada mais pode estar na pasta de skills: nem scripts, nem imagens, nem links simbólicos. Todos os arquivos são texto UTF-8.
O frontmatter tem dois 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 | Descrição |
|---|---|
name | Deve ser igual ao nome da pasta. |
description | Texto simples. É tudo o que o agente vê até carregar o skill. |
Listando um Skill em um Agente
Um skill não faz nada até que um agente o liste. Em .ironflock/ai-template.yml, adicione a chave skills ao agente e nomeie cada skill pelo nome da sua pasta:
machines:
main: true
skills: [machine-diagnosis]Escreva apenas o nome da pasta. Nunca comece uma entrada com app/ ou project/.
O agente recebe o skill como app/<name>, aqui app/machine-diagnosis. O texto do seu system_prompt ou tool_description que menciona um skill usa essa forma.
Toda pasta de skill deve ser listada por pelo menos um agente, e cada agente lista um skill uma única vez.
Skills da Plataforma
Uma entrada no formato platform/<name> é reservada para skills que a plataforma fornece aos apps. Ainda não há nenhum skill da plataforma disponível, então uma entrada assim faz o build do release falhar hoje.
Limites
| O quê | Limite |
|---|---|
| Nome do skill | Letras minúsculas e dígitos, unidos por hifens simples; no máximo 64 caracteres |
| Descrição | No máximo 500 caracteres |
Instruções (SKILL.md) | No máximo 20.000 caracteres |
| Um arquivo de referência | No máximo 40.000 caracteres |
| Arquivos de referência por skill | No máximo 20 |
| Skills por app | No máximo 20 |
| Todos os arquivos de skills de um app juntos | No máximo 2 MiB |
| Skills que um agente lista | No máximo 20 |
O que o Build do Release Verifica
Ao criar um release, o build verifica os skills junto com o ai-template.yml. Se uma verificação falha, o release não é construído e o primeiro problema encontrado é exibido. Corrija-o e crie o release novamente.
O build falha quando:
- um agente lista um skill que não tem pasta;
- uma pasta de skill não é listada por nenhum agente;
- o app tem uma pasta de skills, mas não tem
ai-template.yml; - uma entrada em
skillscomeça comapp/ouproject/; - uma entrada começa com
platform/(ainda não há nenhum skill da plataforma disponível); - um arquivo na pasta de skills não é texto UTF-8, é um link simbólico ou não é
SKILL.mdnem um arquivoreferences/<file>.md; - um limite da tabela acima é excedido;
- um agente tem uma ferramenta chamada
load_skill. O nome é reservado para carregar skills, em todos os apps.
Exemplo
Este skill diz ao agente como descobrir por que uma máquina reporta uma falha. Ele está abreviado aqui. Um app novo começa com três skills completos em .ironflock/skills/ que você pode ler, alterar ou remover.
.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.O agente que o lista, em .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_readingA frase no system_prompt que começa com “When a user asks” refere-se ao skill como app/machine-diagnosis. A regra de segurança fica no system_prompt, porque um agente que não carrega o skill ainda precisa mantê-la.
Testar Skills sem um Release
Você não precisa de um release para testar um agente ou um skill. O Cloud IDE tem um chat de desenvolvimento que usa a sua própria cópia de trabalho.
No painel lateral do Cloud IDE, a seção Agentes de IA tem duas ações:
- Abrir chat de desenvolvimento aplica a sua cópia de trabalho e abre um chat que a usa.
- Atualizar agentes de IA aplica outras alterações feitas no
ai-template.ymle nos skills.
O chat de desenvolvimento:
- executa a sua cópia de trabalho do app, com o backend de dados de desenvolvimento do projeto;
- é o assistente normal do projeto, com os agentes, as ferramentas e os skills deste app tirados da sua cópia de trabalho;
- é o único chat que os recebe. Ninguém mais, e nenhum outro chat, recebe a sua cópia de trabalho.
Um chat de desenvolvimento em andamento usa as suas alterações a partir da mensagem seguinte, então você pode alterar um skill, clicar em Atualizar agentes de IA e perguntar de novo no mesmo chat.
Se o template ou um skill for inválido, a mesma mensagem do build de um release é exibida, e a versão anterior continua em uso.
O chat de desenvolvimento precisa do backend de dados de desenvolvimento do app no projeto do dispositivo selecionado.
Onde os Usuários Veem os Skills
No Studio, a aba Plugin de IA do app lista cada agente com os seus skills, mostrando o nome e a descrição de cada skill. O texto do skill nunca é exibido ali.
Instalações Mais Antigas
Um appliance que ainda não foi atualizado instala o app e o executa. Os agentes dele funcionam sem os skills e avisam o usuário disso quando uma tarefa precisa de um. Depois que o appliance é atualizado, os skills chegam com a próxima sincronização do app.
Escrevendo Bons Skills
- A descrição diz para que serve o skill e quando carregá-lo. Até o agente carregar o skill, a descrição é tudo o que ele vê. Use as palavras que os usuários e os seus dados usam, como valores de estado, sintomas e tarefas, e termine dizendo quando carregar o skill: “Load it before you answer why a machine is TOO_HOT.” Uma descrição como “Information about machines” nunca é carregada no momento certo.
- Faça instruções autossuficientes. O agente as lê no meio de uma tarefa, com um usuário esperando. Nomeie exatamente as tabelas, as colunas e as ferramentas do seu app, em vez de depender do
system_prompt. - Escreva passos imperativos, na ordem em que devem ser seguidos. Diga quando parar e o que dizer ao usuário.
- Diga o que não fazer.
Próximos Passos
- IA: Definindo Agentes e Ferramentas — A referência do
ai-template.yml - Releases e a App Store — Publique o seu app