Skills de pacotes

Agentes de codificação com IA, como Cursor, Gemini, Claude Code, Cline e Copilot, ajudam você a escrever, testar e refatorar código Dart. Para gerar código preciso e idiomático, esses agentes dependem de contexto sobre as bibliotecas e pacotes que o seu projeto usa.

Skills de pacotes permitem que os autores de pacotes distribuam instruções padronizadas e ricas em contexto para agentes de IA, diretamente com seus pacotes do pub. Usando a ferramenta de linha de comando package:skills (invocada como dart run skills@ <command>), você pode descobrir, instalar e atualizar skills para as dependências do seu projeto, fazendo seus agentes de IA escreverem códigos melhores com menos alucinações. Para aprender a criar e publicar skills para o seu próprio pacote, consulte Distribua skills com pacotes.

Uma skill de agente é um conjunto estruturado de instruções, exemplos de código e boas práticas empacotado junto com uma biblioteca. As skills seguem a especificação aberta de Agent Skills, que padroniza a forma como os agentes de codificação com IA descobrem e leem instruções.

Uma skill normalmente inclui:

• Regras de contexto: orientações sobre padrões de biblioteca, arquitetura e antipadrões a evitar.
• Padrões de código: exemplos concretos e prontos para copiar e colar de tarefas comuns.
• Scripts de ferramentas e fluxo de trabalho: scripts e comandos auxiliares opcionais que um agente pode executar para realizar tarefas ou validar código.

As skills ficam armazenadas no diretório de agentes do seu projeto (como .agents/skills/), onde as ferramentas e os agentes de codificação com IA as descobrem e usam automaticamente.

Modelos de IA de uso geral são treinados com código público de várias linguagens, o que significa que eles podem:

• Sugerir APIs obsoletas ou sintaxe desatualizada.
• Deixar de lado convenções arquiteturais específicas de um pacote.
• Inventar APIs que não existem na versão específica que você usa.

Quando você instala skills de pacotes, seu agente de IA ganha conhecimento imediato e confiável, escrito e mantido pelos próprios autores dos pacotes.

Para instalar e atualizar as skills fornecidas pelas dependências do seu projeto, use dart run skills@ get:

$ dart run skills@ get

Ao ser executada em um diretório de projeto, a ferramenta analisa suas dependências diretas no pubspec.yaml em busca de pacotes que disponibilizam um diretório skills/, e pede que você escolha quais skills instalar:

Scanning dependencies for available skills...
? Select skills to install:
  [x] shelf: routing - Define and handle HTTP routes
  [ ] shelf: middleware - Add logging and CORS middleware
  [x] dio: error-handling - Configure retry interceptors

Use as setas do teclado e a barra de espaço para selecionar skills individualmente, ou pressione Ctrl+A para selecionar ou desmarcar todas as skills, e depois pressione Enter.

Para instalar ou atualizar skills de uma única dependência de pacote, use a opção -p (ou --package):

$ dart run skills@ get -p <package_name>

Para instalar uma skill específica pelo nome, use a opção -s (ou --skill):

$ dart run skills@ get -p <package_name> -s <skill_name>

Para instalar todas as skills disponíveis de todas as fontes de dependência sem os prompts interativos, passe a flag -a (ou --all):

$ dart run skills@ get --all

Você também pode instalar skills diretamente de qualquer repositório Git usando dart run skills@ add:

$ dart run skills@ add <git_repository_url>

Para instalar todas as skills do repositório Git sem perguntar, adicione a flag --all:

$ dart run skills@ add <git_repository_url> --all

Depois de adicionado como fonte, você pode atualizar as skills dos seus repositórios Git configurados a qualquer momento executando dart run skills@ get.

Quando você instala skills, elas são copiadas para o diretório apropriado para o seu agente de codificação com IA (como .agents/skills/):

my_project/
├── .agents/
│   └── skills/
│       ├── shelf-routing/
│       │   └── SKILL.md
│       └── dio-error-handling/
│           ├── SKILL.md
│           └── examples/
├── lib/
├── test/
└── pubspec.yaml

Depois de instaladas, as skills ficam imediatamente disponíveis para o seu agente durante a geração de código, a refatoração e o chat.

Se você commitar as skills instaladas depende do fluxo de trabalho do seu time:

• Se você commitar o diretório de skills (como .agents/skills/), commite também o diretório .config/dart_skills/, para que todos os membros do time compartilhem as mesmas definições de skills e o mesmo controle de atualizações.
• Se você ignorar o diretório de skills, adicione também .config/dart_skills/ ao .gitignore. Assim, cada desenvolvedor pode executar dart run skills@ get no seu workspace local.

Conforme os pacotes evoluem, os autores atualizam suas skills com novas boas práticas e mudanças de API. Para atualizar todas as skills instaladas para as versões mais recentes das suas dependências, execute:

$ dart run skills@ get

Uma grande vantagem das skills de agentes é que você pode editá-las localmente para personalizar as instruções de acordo com a arquitetura ou o estilo do seu time.

Quando você executa dart run skills@ get, o package:skills acompanha as skills instaladas anteriormente e detecta alterações nos seus arquivos locais antes de atualizar.

Se uma modificação local for detectada:

• O package:skills avisa que a skill foi modificada localmente.
• Você é solicitado a escolher entre sobrescrever suas alterações locais com a versão do autor original ou manter suas personalizações.

Para ver todas as skills gerenciadas atualmente instaladas no seu workspace, execute dart run skills@ list:

$ dart run skills@ list

Se você remover uma dependência do seu pubspec.yaml, as skills dela podem continuar no diretório de skills do seu agente. Para remover automaticamente as skills de pacotes que não são mais dependências, execute dart run skills@ prune:

$ dart run skills@ prune

Para remover explicitamente skills gerenciadas do seu workspace, use dart run skills@ remove:

$ dart run skills@ remove -p <package_name>

As skills de pacotes dão ao seu agente contexto confiável sobre os pacotes de que o projeto depende. Para dar ao seu agente o mesmo tipo de contexto confiável sobre a linguagem Dart, as bibliotecas principais e as ferramentas, conecte-o ao servidor MCP Developer Knowledge. Esse servidor remoto MCP permite que o agente pesquise e recupere documentação oficial de desenvolvedores do Google, incluindo dart.dev e docs.flutter.dev, por meio das suas ferramentas search_documents, get_documents e answer_query. Ele complementa o servidor MCP do Dart e Flutter, que se concentra no seu projeto local, no SDK e no app em execução.

Para adicioná-lo ao seu agente de codificação, siga as instruções em Configure seu IDE ou agente de codificação e selecione o seu cliente. Para ajudar o agente a decidir quando pesquisar na documentação e qual ferramenta usar, instale também a skill de agente retrieving-developer-knowledge.

Com as skills de pacotes e o servidor MCP Developer Knowledge disponíveis, seu agente pode combinar orientações específicas do pacote com consultas à documentação oficial em uma única tarefa:

Look up the current dart.dev guidance on null safety and records,
then refactor this `dio` error handler to return a record
instead of throwing.

• Distribua skills com pacotes
• package:skills no pub.dev
• package:skills_lint no pub.dev
• Especificação de Agent Skills
• Servidor MCP do Dart e Flutter
• Servidor MCP Developer Knowledge