🌱 Fundamentos

Agent skills são arquivos de instrução (SKILL.md) que ensinam comportamentos específicos a agentes de IA. Funcionam como "plugins" de conhecimento.

Skills permitem reutilizar, compartilhar e versionar comportamentos de agentes, tornando equipes mais eficientes e consistentes.

SKILL.md · frontmatter YAML · instruções para o agente · ativação por contexto

Assim como npm instala pacotes Node.js, o Skills CLI instala "pacotes" de habilidades para agentes de IA a partir de repositórios GitHub.

Entender a analogia acelera o aprendizado: scopes, instalação global vs. local, versioning — tudo funciona de forma similar ao npm.

npx skills add · scope global (-g) · scope projeto · skill como pacote · repositório como registry

skills.sh é o diretório público de skills com leaderboard de instalações. agentskills.io hospeda a especificação oficial do formato SKILL.md.

Descobrir skills prontas poupa tempo. O leaderboard mostra as mais confiáveis (100K+ instalações são um bom sinal de qualidade).

leaderboard · install count · descoberta · especificação oficial · validação de formato

Um agente sem skills é generalista. Com skills, ele adquire conhecimento específico: convenções de código, processos da empresa, integrações com ferramentas.

Skills eliminam a necessidade de repetir contexto em cada sessão. O agente já sabe as convenções do seu time, suas ferramentas, seu fluxo de trabalho.

contexto persistente · especialização · convenções de time · instrução reutilizável · ativação automática

Skills são projetadas para serem atômicas (uma responsabilidade), compostas (combinar várias) e reutilizáveis (funcionar em múltiplos agentes).

Entender a filosofia ajuda a criar skills melhores: pequenas, focadas, fáceis de manter e compartilhar com a comunidade.

responsabilidade única · composição · portabilidade entre agentes · versionamento · compartilhamento

O Skills CLI foi criado pelo Vercel Labs para resolver a fragmentação de instruções entre diferentes agentes de IA e equipes de desenvolvimento.

Conhecer a origem ajuda a entender as decisões de design e o roadmap. O projeto é open source — você pode contribuir.

Vercel Labs · open source · GitHub vercel-labs/skills · fragmentação de instruções · padronização

O frontmatter YAML fica entre delimitadores --- no topo do arquivo e contém os metadados da skill: name, description e campos opcionais.

O frontmatter é como o agente identifica e indexa a skill. Campos corretos garantem que a skill seja descoberta e ativada no momento certo.

frontmatter · delimitadores --- · campos obrigatórios · campos opcionais · YAML syntax

O campo name define o identificador único da skill. Deve ser lowercase com hyphens (kebab-case), sem espaços ou caracteres especiais.

O name é usado em npx skills remove e npx skills update. Um nome ruim torna o gerenciamento difícil.

kebab-case · lowercase · sem espaços · identificador único · convenção de nomenclatura

A description é lida pelo agente para decidir quando ativar a skill. Deve descrever claramente o que a skill faz e em quais situações é útil.

Uma description vaga resulta em skill nunca ativada ou ativada no momento errado. É o campo que mais impacta a usabilidade da skill.

gatilho de ativação · contexto de uso · clareza · especificidade · semântica para o agente

Após o frontmatter, o corpo da skill é Markdown livre. As seções recomendadas são "When to Use" (cenários de uso) e "Steps" (passos a seguir).

A estrutura das seções guia o agente de forma previsível. Seguir o padrão torna suas skills mais fáceis de entender e usar por outros.

Markdown · When to Use · Steps · instruções acionáveis · estrutura previsível

O campo metadata.internal: true oculta a skill da descoberta normal (npx skills find). Útil para skills de desenvolvimento interno que não devem ser públicas.

Times corporativos precisam de skills internas (políticas, segredos de processo) que não devem aparecer no diretório público do skills.sh.

metadata.internal · skills privadas · INSTALL_INTERNAL_SKILLS=1 · controle de acesso · visibilidade

A skill find-skills ajuda usuários a descobrir e instalar skills. Ela é ativada quando o usuário pergunta "como faço X?" ou "tem skill para Y?" — um ótimo modelo de skill bem escrita.

Estudar a find-skills ensina como escrever skills com gatilhos claros, instruções úteis e integração com o fluxo de trabalho do usuário.

gatilhos naturais · linguagem do usuário · busca integrada · modelo de referência · skills de meta-descoberta

O Skills CLI suporta 50+ agentes: Claude Code, Cursor, OpenCode, Codex, GitHub Copilot, Windsurf, Cline, Roo Code, Gemini CLI, Devin, Goose, Amp, Continue, OpenHands e mais.

Times que usam múltiplos agentes podem instalar a mesma skill para todos de uma vez. Seu investimento em criar skills se multiplica.

detecção automática · agentes populares · flag -a para agente específico · compatibilidade cruzada

Cada agente tem seu próprio caminho: Claude Code usa .claude/skills/, Cursor usa .cursor/rules/, Copilot usa .github/copilot/. O CLI sabe exatamente onde colocar cada arquivo.

Entender os caminhos permite inspecionar manualmente as skills instaladas e resolver conflitos quando necessário.

.claude/skills/ · .cursor/rules/ · ~/.claude/skills/ (global) · pastas de descoberta · hierarquia de caminhos

O CLI detecta agentes instalados verificando a presença de suas configurações no sistema (.claude/, .cursor/, etc.) e instala skills apenas para os agentes detectados.

Entender a detecção evita surpresas. Se um agente não é detectado, use -a para forçar a instalação para ele.

detecção por configuração · heurística de instalação · flag -a · instalação forçada · diagnóstico

Nem todos os agentes suportam todos os campos. allowed-tools funciona em todos, mas context:fork e hooks são exclusivos do Claude Code (e hooks também no Cline).

Usar features exclusivas sem saber a compatibilidade resulta em comportamento silenciosamente ignorado. A tabela de compatibilidade é essencial.

allowed-tools · context:fork · hooks · compatibilidade · funcionalidades exclusivas · graceful degradation

Claude Code é ideal para skills com hooks e contexto isolado. Cursor e Copilot são ótimos para skills de código inline. OpenCode para fluxos de terminal.

A escolha do agente certo para cada tipo de skill maximiza o benefício. Uma skill de hooks avançados só faz sentido com Claude Code.

Claude Code para hooks · Cursor para editor · Copilot para GitHub · OpenCode para terminal · seleção por caso de uso

O CLI busca skills em: skills/, .claude/skills/, .agents/skills/, .cursor/skills/ e pastas específicas de cada agente. A busca é recursiva.

Saber onde o CLI busca permite organizar repositórios de skills de forma que sejam descobertos automaticamente, sem configuração manual.

descoberta recursiva · múltiplas pastas · prioridade · skills/ · .claude/skills/ · convenção over configuração