Skip to Content

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_promptColoque em um skill
O papel do agenteConhecimento de que só algumas tarefas precisam
Regras que sempre valemProcedimentos 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 antesReferê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ó. O SKILL.md diz 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. ---
CampoDescrição
nameDeve ser igual ao nome da pasta.
descriptionTexto 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 skillLetras minúsculas e dígitos, unidos por hifens simples; no máximo 64 caracteres
DescriçãoNo máximo 500 caracteres
Instruções (SKILL.md)No máximo 20.000 caracteres
Um arquivo de referênciaNo máximo 40.000 caracteres
Arquivos de referência por skillNo máximo 20
Skills por appNo máximo 20
Todos os arquivos de skills de um app juntosNo máximo 2 MiB
Skills que um agente listaNo 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 skills começa com app/ ou project/;
  • 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.md nem um arquivo references/<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_reading

A 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.yml e 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

Last updated on