Agora seus pacotes Dart podem ensinar a IA a usá-los

magine instalar um pacote Flutter e, além do código, receber automaticamente instruções dizendo para a IA como aquele pacote deve ser usado.

Não estamos falando de mais uma documentação em Markdown que o desenvolvedor precisa abrir.

Estamos falando de instruções que podem ser descobertas e instaladas diretamente no projeto para serem utilizadas por agentes de IA.

Essa é a proposta do Skills CLI 1.0, agora mantido e publicado pela equipe do Dart.

E existe um detalhe especialmente interessante:

O próprio pacote pode carregar o conhecimento necessário para a IA trabalhar corretamente com ele.

---

O problema não é a IA não saber programar

Agentes de código já conseguem escrever Dart, Flutter, TypeScript, React e praticamente qualquer outra linguagem moderna.

O problema aparece quando entramos em um código real.

Imagine que seu projeto utilize uma biblioteca chamada networking.

A IA provavelmente consegue descobrir como fazer uma requisição:

final response = await client.fetchData();

Mas será que ela sabe que, na versão específica instalada no seu projeto, existe uma NetworkException que precisa ser tratada?

Ou que requisições precisam de fallback?

Ou que determinadas APIs devem ser utilizadas em vez de outras?

Ou que existe uma convenção arquitetural adotada pela biblioteca?

A documentação tradicional resolve parte desse problema.

Mas existe uma limitação:

a documentação explica o software para humanos.

Agent Skills introduz outra possibilidade:

ensinar o agente a trabalhar com aquele software.

---

O que são Agent Skills?

Uma Skill é, essencialmente, um conjunto estruturado de instruções que um agente de IA pode consultar quando precisa executar determinada tarefa.

Um exemplo simples:

skills/
└── networking-error-handling/
    └── SKILL.md

Dentro do SKILL.md, podemos definir:

---
name: networking-error-handling
description: >-
  Use when the user is making network requests using
  the networking APIs to ensure safe patterns.
---

# Networking Error Handling

## Guidelines

- Operations must always be wrapped in a try/catch block.
- You must catch NetworkException specifically.
- Provide fallback UI state on timeout.

Isso parece apenas documentação.

Mas existe uma diferença importante.

O arquivo não precisa ser lido inteiro pelo agente o tempo todo.

Skills utilizam um conceito chamado progressive disclosure: primeiro o agente descobre que aquela capacidade existe e só carrega informações mais detalhadas quando elas são relevantes.

Isso reduz o desperdício de contexto.

E, em agentes de IA, contexto é um recurso valioso.

---

Agora imagine que a Skill venha junto com o pacote

É aqui que o skills CLI fica realmente interessante.

Um pacote Dart pode começar a distribuir suas próprias Skills:

my-package/
├── lib/
├── test/
├── skills/
│   └── my-package-api/
│       └── SKILL.md
├── pubspec.yaml
└── README.md

Isso cria uma relação que até pouco tempo atrás era incomum:

Package
   │
   ├── Código
   ├── API
   ├── Documentação
   │
   └── Skills para agentes de IA

O pacote deixa de distribuir apenas software.

Ele também passa a distribuir conhecimento operacional para agentes.

---

E isso resolve um problema importante: versão

Esse talvez seja o detalhe mais interessante da proposta.

Imagine que seu projeto tenha:

dependencies:
  some_package: ^2.4.0

A IA pode conhecer a biblioteca.

Mas conhecimento geral não significa necessariamente conhecimento da versão que você está utilizando.

Agora imagine que a Skill esteja dentro da própria dependência.

O fluxo passa a ser:

pubspec.yaml
     │
     ▼
Dependência instalada
     │
     ▼
skills/
     │
     ▼
SKILL.md
     │
     ▼
Agente de IA

A Skill acompanha o pacote.

Isso abre espaço para um modelo muito mais interessante de documentação:

A biblioteca não apenas informa como funciona. Ela pode informar ao agente como deve ser utilizada.

---

Conhecendo o skills CLI

A instalação das Skills das dependências pode ser feita com:

dart run skills@ get

O CLI analisa as dependências imediatas do projeto e procura diretórios skills/.

Encontrando Skills disponíveis, ele apresenta essas opções para instalação.

E o processo é incremental.

Ou seja, execuções posteriores podem identificar:

• Skills novas;
• Skills atualizadas;
• Skills removidas;
• Skills que foram ignoradas anteriormente.

Também existe a opção de instalar tudo:

dart run skills@ get --all

O uso de:

dart run skills@

também tem uma vantagem interessante: ele permite executar a versão mais recente do CLI sem precisar instalar e manter uma instalação global manualmente.