Pular para o conteúdo
SEGUNDA-FEIRA, NOVEMBRO 16, 2026NOTÍCIAS DE TECNOLOGIA INDEPENDENTES, ANÁLISES & GUIAS PRÁTICOS
SOBRE
ÚLTIMAS /

Agent Skills e servidores MCP explicados: como instalar, atualizar e corrigir no OpenCode, Claude Code, Codex e outros agentes de IA

LEIA O GUIA
AGENTES DE IAGM / 997

Agent Skills e servidores MCP explicados: como instalar, atualizar e corrigir no OpenCode, Claude Code, Codex e outros agentes de IA

Agent Skills e servidores MCP explicados de forma simples: instale, atualize e corrija no OpenCode, Claude Code e Codex, com a CLI npx skills passo a passo.

Agent skills and MCP servers explained: a tech.grahammiranda.com title card with SKILL.md, npx skills, MCP servers and .agents/skills, and a terminal running npx skills check and opencode mcp add

Um agente de codificação com IA recém-saído da caixa é como um novo contratado brilhante na primeira manhã. Ele consegue raciocinar, escrever código e executar comandos, mas não sabe como sua equipe faz as coisas e não tem nenhuma chave dos seus sistemas. Agent skills e servidores MCP preenchem exatamente essas duas lacunas. Uma skill é um playbook escrito que o agente pega na prateleira quando uma tarefa precisa dele. Um servidor MCP é um conjunto de chaves: um pequeno programa que permite ao agente usar algo que antes ele não alcançava, como suas issues do GitHub, um navegador de verdade ou documentação atualizada.

Este guia explica os dois em linguagem simples e depois mostra como instalar, atualizar, remover e solucionar problemas deles no OpenCode, Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot e Hermes Agent. A maior parte funciona do mesmo jeito em todos os lugares, porque ambos são padrões abertos hoje. Do lado das skills, uma pequena ferramenta de linha de comando amarra tudo, npx skills, e vou percorrê-la comando por comando.

Não sou desenvolvedor de formação. Comando uma pequena empresa de TI na Alemanha e construo software com agentes de IA, então aprendi a maior parte disso do jeito que você provavelmente vai aprender: quebrando as coisas. A Parte 6 nasceu das minhas próprias sessões de terminal num Mac e num Raspberry Pi, incluindo a vez em que a ferramenta me disse que todas as minhas skills estavam atualizadas quando ela não tinha conseguido verificar uma sequer.

Tudo abaixo foi conferido com a documentação oficial de cada agente e, para a skills CLI, com o código-fonte publicado das versões 1.5.18 a 1.8.1, em 15 de novembro de 2026. Essas ferramentas mudam toda semana: a CLI lançou duas versões só nesta semana, e o OpenCode chegou à 2.3.0 em 13 de novembro. Os números de versão e os comportamentos estão sinalizados onde provavelmente vão mudar. Confira antes de contar com eles.

Divulgação: Nenhuma empresa citada neste artigo patrocinou, revisou ou aprovou o conteúdo, e ele não contém links de afiliados. Os produtos são nomeados apenas no texto; as imagens usam meus próprios logos.


Resumo rápido — Agent Skills e servidores MCP em dez tópicos

  • Uma skill é uma pasta com um SKILL.md arquivo: um nome e uma descrição no topo, instruções abaixo e scripts ou arquivos de referência opcionais. Os agentes leem apenas a descrição até que uma tarefa precise da skill, então uma skill não usada custa cerca de 100 tokens da atenção do agente.
  • Um servidor MCP dá ao agente novas ferramentas, como GitHub, um navegador ou documentação ao vivo. As descrições das ferramentas podem ir junto com cada requisição, então conecte só os servidores que você usa. O Claude Code agora as adia até que sejam necessárias, e o OpenCode as agrupa por servidor.
  • A regra prática: as regras da casa para toda tarefa vão no AGENTS.md; o know-how necessário para algumas tarefas vira uma skill; o acesso ao vivo a um sistema exige um servidor MCP; e, se já existe uma boa ferramenta de linha de comando, uma skill que ensina essa ferramenta ao agente costuma sair mais barata do que um servidor.
  • Ambos são padrões abertos sob a Agentic AI Foundation da Linux Foundation: o MCP desde dezembro de 2025, o Agent Skills desde 22 de outubro de 2026. Uma skill escrita para um agente normalmente funciona nos outros.
  • .agents/skills é a pasta compartilhada. Codex, OpenCode, Cursor, Gemini CLI e GitHub Copilot todos leem .agents/skills num projeto e ~/.agents/skills na sua pasta home. O Claude Code lê apenas .claude/skills, e o Hermes Agent lê ~/.hermes/skills mais quaisquer pastas que você adicionar.
  • npx skills é o npm das skills. a CLI de código aberto da Vercel (versão 1.8.1) instala skills em 79 agentes: npx skills add owner/repo, -g para todos os projetos, -a opencode -a claude-code para escolher os agentes, npx skills ls para listar e npx skills remove para desinstalar.
  • Para ver se suas skills estão atualizadas, execute npx skills@latest check. Desde a versão 1.7.5 (2 de novembro de 2026) ele apenas informa; npx skills update instala. Em versões anteriores, check executava a atualização sem avisar.
  • Nunca confie no tique verde sozinho. Quando o limite do GitHub de 60 requisições anônimas por hora bloqueou todas as verificações no meu Mac, a CLI ainda imprimiu “Todas as skills globais estão atualizadas”. Execute gh auth login ou defina GITHUB_TOKEN, e leia as linhas ✗.
  • Nunca use sudo com skills ou agentes, e não execute a CLI a partir da sua pasta pessoal. O root tem uma pasta pessoal separada, então sudo cria um segundo repositório de skills invisível; e a partir de ~ a CLI confunde sua pasta pessoal com um projeto.
  • Trate skills e servidores MCP como software que você instala. Uma auditoria de fevereiro de 2026 de 3.984 skills públicas encontrou falhas de segurança em 36,82% delas e confirmou payloads maliciosos em 76. Leia antes de instalar, prefira skills dos próprios criadores da ferramenta, fixe as versões e mantenha ferramentas de risco em “perguntar”.

Os quatro blocos de construção em resumo

Bloco de construção O que é, em uma linha Pense nisso como Quando o agente lê Quanto custa Exemplo
AGENTS.md (CLAUDE.md no Claude Code) Um arquivo Markdown com as regras da casa para um projeto O manual da equipe No início de cada sessão, por inteiro Seu comprimento total, em cada requisição “Use a grafia britânica. Rode os testes antes de dizer que terminou.”
Habilidade Uma pasta com uma SKILL.md receita, além de scripts e referências opcionais Uma ficha de receita em um fichário Nome e descrição no início; a receita completa só quando uma tarefa precisar dela Cerca de 100 tokens por habilidade até que ela seja usada “Como escrevemos as notas de versão”
servidor MCP Um pequeno programa que dá novas ferramentas ao agente Um conjunto de chaves e adaptadores A lista de ferramentas no início (a menos que seu agente a adie); ferramentas individuais quando chamadas Descrições de ferramentas, muitas vezes em cada requisição Issues do GitHub, um navegador de verdade, documentação atualizada de bibliotecas
Plugin ou extensão Um pacote de habilidades, servidores MCP e, às vezes, hooks Um kit de boas-vindas Depende do que está dentro A soma das partes Superpowers, o kit inicial de um fornecedor
Agent skills e servidores MCP explicados: AGENTS.md como o manual sempre carregado, skills como cartões de receita carregados sob demanda, servidores MCP como ferramentas para GitHub, um navegador e documentação ao vivo, e plugins como pacotes
Quatro blocos de construção, um agente. O manual está sempre aberto, as fichas de receita saem da estante quando necessário, e os servidores MCP são as chaves para tudo o que está fora do terminal.

Índice


Parte 1 — Agent Skills e servidores MCP em linguagem simples

A imagem do novo contratado

Imagine contratar alguém brilhante. No primeiro dia você daria três coisas a essa pessoa: um manual curto com as regras que todo mundo segue, um fichário de receitas para as tarefas que sua equipe faz do seu jeito particular, e um conjunto de chaves e crachás para que ela acesse os sistemas de que precisa. Você também entregaria a algumas pessoas um kit de boas-vindas que junta algumas receitas e chaves.

Agentes de IA precisam exatamente do mesmo, e cada peça agora tem um nome padrão:

  • O manual é AGENTS.md (O Claude Code chama a sua versão CLAUDE.md).
  • As receitas são habilidades.
  • As chaves são servidores MCP.
  • Os kits de boas-vindas são plugins, chamados de extensões em alguns agentes.

O resto deste guia trata das receitas e das chaves, porque é aí que mora a maior parte da confusão.

O que é uma skill

Uma skill é uma pasta. Dentro dela fica um arquivo obrigatório, SKILL.md, e, opcionalmente, tudo o mais que a tarefa precisar:

release-notes/
├── SKILL.md          ← obrigatório: nome, descrição, instruções
├── references/       ← opcional: documentos mais longos, lidos só quando necessário
├── scripts/          ← opcional: código que o agente pode executar
└── assets/           ← opcional: modelos, imagens, arquivos de dados

O SKILL.md tem um cabeçalho curto entre duas --- linhas (esse cabeçalho se chama front matter), seguidas de instruções simples:

---
name: release-notes
description: Escreve notas "What's New" da App Store a partir dos commits recentes. Use quando pedirem notas de versão, um changelog ou um texto de "novidades".
---

# Notas de versão

1. Leia os commits desde a última tag git.
2. Mantenha apenas as mudanças que um usuário notaria.
3. Escreva de três a cinco marcadores curtos em linguagem simples, com menos de 400 caracteres no total.

O padrão aberto pede dois campos. O nomear só pode usar letras minúsculas, números e hífens, pode ter no máximo 64 caracteres e deve ser igual ao nome da pasta. A descrição pode ter até 1.024 caracteres e deve dizer o que a skill faz e quando usá-la, porque é pela descrição que o agente decide se abre a skill ou não.

Por que você pode instalar dezenas de skills: o truque das três camadas

As skills carregam em camadas, o que o padrão chama de divulgação progressiva. Pense em uma estante:

  1. As contracapas. Quando uma sessão começa, o agente lê apenas o nome e a descrição de cada skill. A especificação reserva cerca de 100 tokens por skill para isso. (Um token é mais ou menos uma palavra curta ou parte de uma; é a unidade em que os modelos contam sua memória de trabalho.)
  2. O capítulo. Quando uma tarefa corresponde a uma descrição, o agente lê na íntegra o SKILL.md. O padrão recomenda mantê-lo abaixo de 5.000 tokens e 500 linhas.
  3. O apêndice. Arquivos de referência e scripts só carregam se as instruções apontarem para eles.

É por isso que cem skills sem uso custam muito menos do que um único manual comprido. Mas não é de graça: as descrições se acumulam, e os agentes impõem limites. O Codex limita a lista inicial de skills a 2% da memória de trabalho do modelo (8.000 caracteres se não conseguir saber o tamanho), e o Claude Code corta o texto de listagem de cada skill em 1.536 caracteres. Instale o que você vai usar.

O que é um servidor MCP

MCP, o Model Context Protocol, é um padrão aberto para conectar agentes de IA a ferramentas e dados. A Anthropic o apresentou em novembro de 2024 e o entregou à nova Agentic AI Foundation da Linux Foundation em dezembro de 2025, junto com o AGENTS.md da OpenAI e o goose da Block.

An servidor MCP é um programa pequeno que diz ao seu agente: “aqui estão as ferramentas que eu ofereço”. Um servidor de GitHub pode oferecer create_issue e search_code; um servidor de navegador oferece navigate e take_screenshot; um servidor de documentação oferece query_docs. Seu agente é o cliente MCP: ele mostra a lista ao modelo e, quando o modelo quer usar uma ferramenta, o agente verifica suas permissões, pede ao servidor que a execute e devolve o resultado.

Os servidores são de dois tipos:

  • Servidores locais rodam no seu próprio computador. O agente os inicia com um comando como npx @playwright/mcp@latest e conversa com eles pela entrada e saída do programa (o nome técnico é stdio).
  • Servidores remotos rodam nos computadores do provedor. Você se conecta com um endereço web, como https://mcp.context7.com/mcp, e normalmente entra pelo navegador ou cola uma chave de API. O nome técnico da conexão é Streamable HTTP.

Aqui está o detalhe. Toda ferramenta vem com um nome, uma descrição e uma lista de parâmetros, escritos para o modelo ler. A menos que seu agente as adie, essas descrições viajam em cada requisição, e vinte servidores com dez ferramentas cada deixam toda resposta mais lenta, mais cara e menos focada. A Parte 7 mostra o que cada agente faz a respeito.

AGENTS.md e plugins, em resumo

AGENTS.md é um arquivo Markdown simples na pasta raiz do seu projeto que o agente lê no início de cada sessão: o propósito do projeto, seus comandos, seus pontos inegociáveis. OpenCode, Codex, Cursor e GitHub Copilot o leem diretamente. O Claude Code lê CLAUDE.md em vez disso, e sua documentação sugere um CLAUDE.md que simplesmente importa o outro arquivo com uma linha assim @AGENTS.md. Como ele é carregado sempre, mantenha-o curto e mova tudo que é específico de tarefa para skills.

Plugins empacotam as outras peças. Um plugin do Claude Code pode conter skills, subagentes, hooks (scripts que rodam em eventos) e servidores MCP e LSP. Codex, Cursor, GitHub Copilot CLI e Hermes Agent também têm plugins, e o Gemini CLI os chama de extensões. A Parte 9 cobre eles.

Um glossário de bolso

Termo O que significa aqui
Agente (ou harness) O programa com quem você conversa: OpenCode, Claude Code, Codex e assim por diante. Ele executa o modelo, lê arquivos e chama ferramentas
Modelo A IA que faz o raciocínio, como GLM, Claude ou GPT
Janela de contexto A memória de trabalho do modelo para uma requisição. Tudo que você carrega disputa espaço nela
Token A unidade em que os modelos contam texto; mais ou menos uma palavra curta ou parte dela
Habilidade Uma pasta com uma SKILL.md arquivo que ensina uma tarefa ao agente
Front matter O cabeçalho no topo do SKILL.md, entre duas --- linhas
servidor MCP Um programa que oferece ferramentas ao agente por meio do Model Context Protocol
Ferramenta Uma ação que um servidor MCP oferece, como create_issue
stdio / Streamable HTTP Como o agente conversa com um servidor local e um servidor remoto
OAuth O fluxo “Entrar com…” no seu navegador que dá um token ao agente sem você colar uma senha
Escopo do projeto / escopo global Instalado só para um projeto ou para todos os projetos do seu computador
Arquivo de lock Um recibo que lista o que você instalou, de onde veio e uma impressão digital de cada skill
Link simbólico Um atalho para uma pasta. A CLI skills mantém uma cópia real e conecta os agentes a ela

Parte 2 — Habilidade, servidor MCP ou AGENTS.md? O teste das cinco perguntas

Quando você quer que um agente faça algo melhor, faça estas perguntas em ordem e pare no primeiro “sim”. A pergunta 4 é a única com um desdobramento:

  1. Isso vale para cada tarefa deste projeto? Coloque em AGENTS.md. “Use a grafia britânica” e “rode os testes antes de dizer que terminou” ficam aqui.
  2. Isso precisa ser aplicado, não apenas sugerido? Use uma regra de permissão ou um hook. Skills e AGENTS.md são instruções, e um modelo pode ignorar instruções. “Nunca faça push para a main” precisa de uma deny regra.
  3. É um conhecimento que só importa para algumas tarefas? Escreva ou instale uma skill. Rotinas de lançamento, listas de verificação de revisão, a voz da sua marca e seu fluxo de trabalho test-first são todas skills.
  4. O agente precisa de acesso ao vivo a um sistema fora dos arquivos dele? Seus relatórios de falhas atrás de um login, um navegador que ele possa controlar, um aplicativo de gestão de projetos. Se for o caso, faça a pergunta 5 antes de recorrer a um servidor.
  5. Já existe uma boa ferramenta de linha de comando para esse sistema? Se sim, uma skill que ensina essa ferramenta ao agente geralmente supera um servidor: o agente já sabe executar comandos, uma CLI não custa nada até ser usada, e sua saída pode ser filtrada antes de chegar ao modelo. Se não houver uma boa CLI, se o seu agente não puder executar comandos, ou se a tarefa for interativa (como controlar um navegador), adicione um servidor MCP.

Aqui está o teste aplicado a dez desejos do dia a dia:

Você quer que o agente… Uso Por que
Sempre use a grafia britânica AGENTS.md Vale para toda tarefa
Nunca faça push para a branch main Uma regra de permissão Precisa ser aplicado, não sugerido
Escreva notas de lançamento do seu jeito Uma skill Conhecimento, necessário às vezes
Siga um fluxo de trabalho test-first rigoroso Uma skill (o Superpowers tem uma) Um procedimento para algumas tarefas
Ler e registrar issues do GitHub Uma skill que ensina gh, ou o servidor MCP do GitHub gh sai mais barata; o servidor serve para agentes que não conseguem executar comandos
Consultar a documentação atual de uma biblioteca Um servidor MCP (Context7) ou sua CLI com uma skill (ctx7) Dados ao vivo de qualquer jeito
Navegue pelo seu aplicativo web e tire capturas de tela Um servidor MCP (Playwright) Ele precisa de um navegador em execução que o agente consiga controlar
Verifique os travamentos da noite passada Um servidor MCP (Sentry) Dados ao vivo atrás de um login
Gere um relatório em PDF a partir do seu modelo Uma skill com um script e o modelo dentro assets/ Um procedimento mais uma ferramenta incluída
Mantenha longe dos seus .env arquivos Uma regra de permissão Isso precisa ser aplicado

Skills e servidores MCP não são rivais. Algumas das melhores configurações combinam os dois: uma skill explica quando e como como usar as ferramentas de um servidor, e o servidor faz o trabalho. O Codex ainda deixa uma skill declarar os servidores MCP dos quais depende, em um campo opcional agents/openai.yaml baixado.

Skill, servidor MCP ou AGENTS.md: um fluxo de cinco perguntas que envia as regras de todas as tarefas para o AGENTS.md, as regras obrigatórias para as permissões, o know-how para as skills e o acesso ao sistema ao vivo para uma skill de CLI ou um servidor MCP
Cinco perguntas, feitas em ordem. A maioria dos desejos acaba virando skill; um servidor ganha seu lugar quando o agente precisa de acesso ao vivo e não existe uma boa ferramenta de linha de comando.

Parte 3 — Onde cada agente procura habilidades

Todo agente procura em dois tipos de lugar. Pastas do projeto ficam dentro do seu repositório, então as skills viajam com o código e sua equipe também as recebe. Pastas pessoais ficam na sua pasta pessoal e valem para todos os projetos no seu computador. A maioria das ferramentas chama instalações pessoais de globais.

Em 2026 os agentes convergiram para um único local compartilhado: .agents/skills num projeto e ~/.agents/skills na sua pasta pessoal. Coloque uma skill lá e a maioria dos agentes a encontra sem nenhum trabalho extra.

Agente Pastas do projeto Pastas pessoais Chame uma skill você mesmo Vale saber
OpenCode .opencode/skills, .agents/skills, .claude/skills ~/.config/opencode/skills, ~/.agents/skills, ~/.claude/skills Mencione @skill-id no seu prompt O ID é o nome da pasta. Restrinja skills com a skill permissão
Claude Code .claude/skills ~/.claude/skills /skill-name Não lê .agents/skills. Skills de plugin aparecem como /plugin-name:skill-name
Codex .agents/skills, em todas as pastas de onde você inicia até a raiz do repositório ~/.agents/skills, mais /etc/codex/skills para administradores $skill-name, ou /skills Vem com um $skill-installer
Gemini CLI .agents/skills, .gemini/skills ~/.agents/skills, ~/.gemini/skills /skills list; o modelo pede sua permissão antes de ativar uma .agents/skills vence quando duas skills têm o mesmo nome
Cursor .agents/skills, .cursor/skills (e lê .claude/skills e .codex/skills) ~/.agents/skills, ~/.cursor/skills /skill-name A caminhos campo limita uma skill a arquivos correspondentes
GitHub Copilot .github/skills, .agents/skills, .claude/skills ~/.copilot/skills, ~/.agents/skills Carrega skills quando são relevantes Funciona no Copilot CLI, no agente de nuvem e no modo agente no VS Code e no JetBrains
Hermes Agent .hermes/skills, .agents/skills, depois de executar hermes skills trust ~/.hermes/skills, além de quaisquer pastas listadas em skills.external_dirs /skill-name, e até cinco seguidos Verifica cada instalação do hub em busca de conteúdo malicioso

Caminhos conforme a documentação de cada agente em 15 de novembro de 2026. Os agentes adicionam locais com frequência; confira a página de skills do seu agente se algo não aparecer.

Três detalhes que evitam confusão

  • O Claude Code é a exceção. Ele lê apenas .claude/skills e ~/.claude/skills. A CLI de skills cuida disso para você ao criar um link da pasta do Claude Code para a cópia compartilhada. Se você copiar skills manualmente, vai precisar colocá-las (ou um symlink) na pasta do Claude Code por conta própria.
  • O Hermes Agent mantém sua própria biblioteca. Sua pasta principal é ~/.hermes/skills. Para ele ler também a pasta compartilhada, adicione-a em ~/.hermes/config.yaml:

yaml skills: external_dirs: - ~/.agents/skills

Ou instale com a CLI de skills e inclua -a hermes-agent. Escolha uma abordagem, não as duas, ou você terá cada skill em dobro. – Nomes duplicados causam surpresas silenciosas. Cada agente tem sua própria regra sobre qual cópia vence. O OpenCode registra suas pastas em uma ordem fixa e a última vence, com a do seu projeto .opencode/skills por último. O Claude Code faz o contrário: uma skill pessoal vence uma skill de projeto com o mesmo nome. O Gemini CLI prefere o workspace ao do usuário e .agents em vez de .gemini, e o Codex simplesmente mostra os dois. A solução é sem graça e confiável: não mantenha duas skills com o mesmo nome.

O OpenCode tem dois extras que vale a pena conhecer. Um único arquivo Markdown na raiz de uma pasta de skills (como skills/review.md) também conta como uma skill, e uma skills array em opencode.jsonc pode adicionar pastas extras ou até um catálogo web de skills. Meu guia do OpenCode aborda suas permissões de skills com mais profundidade.

Onde os agentes de IA procuram skills: a pasta compartilhada .agents/skills lida pelo Codex, OpenCode, Cursor, Gemini CLI e GitHub Copilot, com links para .claude/skills do Claude Code e ~/.hermes/skills do Hermes Agent
Uma pasta compartilhada cobre a maioria dos agentes. O Claude Code sempre precisa de um link, e o Hermes Agent precisa de um para skills globais; a CLI de skills cria os dois.

Parte 4 — O skills CLI: npm para Agent Skills, passo a passo

Você pode instalar skills copiando pastas de um lado para o outro, e para uma ou duas isso funciona. Além disso, você quer um gerenciador de pacotes: algo que sabe onde cada agente procura, mantém uma cópia em vez de cinco, lembra de onde veio cada skill e sabe avisar quando existe uma versão mais nova. É isso que skills faz. É uma ferramenta de linha de comando de código aberto (MIT) do Vercel Labs, você a executa com npx skills, e o diretório de skills públicas dela fica em skills.sh.

Os fatos que importam em 15 de novembro de 2026:

  • Versão 1.8.1, lançada em 11 de novembro. Ela anda rápido: de 1.7.5 a 1.8.1 foram nove dias.
  • Precisa do Node.js 22.20 ou mais recente.
  • Suporta 79 agentes, incluindo OpenCode, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot e Hermes Agent.
  • Ela instala a partir do GitHub (owner/repo), GitLab, Azure Repos, qualquer endereço Git, uma pasta local ou um link direto de download para um SKILL.md ou um arquivo compactado.

Passo 0 — Verifique o Node.js e sempre peça a versão mais recente

node --version      # precisa da v22.20.0 ou mais recente

Se isso imprimir uma versão mais antiga ou “command not found”, instale a versão LTS atual a partir de nodejs.org. Em um Mac com Homebrew, brew install node também funciona. Em um Raspberry Pi, a versão na lista de pacotes do próprio sistema operacional costuma ser antiga demais, então use os instaladores indicados nessa mesma página.

Depois, torne um hábito automático: digite npx skills@latest em vez do simples npx skills para qualquer coisa que verifique ou atualize. O simples npx pode reutilizar uma cópia que baixou semanas atrás e, com esta ferramenta, a versão que você executa muda o que os comandos fazem (a Parte 5 explica o maior exemplo).

Passo 1 — Olhe antes de instalar

npx skills@latest add vercel-labs/agent-skills --list

--list mostra todas as skills do repositório com a descrição e não instala nada. Depois abra o repositório no navegador e leia o SKILL.md de tudo o que você está prestes a instalar, além de quaisquer scripts que estejam ao lado. No skills.sh, a página de cada skill também mostra os resultados da auditoria de segurança (Parte 11).

Passo 2 — Instale uma skill para os agentes que você usa

# Uma skill, para OpenCode e Claude Code, no projeto atual
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a opencode -a claude-code

# A mesma skill para todos os projetos deste computador
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -g -a opencode -a claude-code

# Fixe uma tag de release ou um commit completo, para que as atualizações sejam deliberadas
npx skills add owner/[email protected] --skill my-skill

Omita --skill e -a e a CLI pergunta de forma interativa: quais skills, quais agentes e se deve criar link ou copiar. Veja onde cada coisa fica:

Escopo A única cópia real Links para agentes com pasta própria O registro do que você instalou
Projeto (o padrão) ./.agents/skills/<name> ex. ./.claude/skills/<name> para o Claude Code ./skills-lock.json
Global (-g) ~/.agents/skills/<name> ex. ~/.claude/skills/<name>, ~/.hermes/skills/<name> ~/.agents/.skill-lock.json

A CLI mantém uma única cópia real em .agents/skills, que a maioria dos agentes lê diretamente, e cria links (symlinks, essencialmente atalhos) para agentes que procuram em outro lugar. Uma cópia significa uma atualização. Se o seu sistema não lida bem com symlinks, o que pode acontecer no Windows, adicione --copy para obter cópias independentes.

Passo 3 — Veja o que está instalado

npx skills ls              # skills deste projeto
npx skills ls -g           # seus skills globais
npx skills ls -a opencode  # apenas o que o OpenCode recebe
npx skills ls --json       # legível por máquina, para scripts

Para skills de projeto, as versões atuais também mostram um status: rastreada (corresponde ao arquivo de lock), modificada (você ou o agente editou), não rastreada (sem entrada no arquivo de lock, como uma skill que você escreveu à mão) ou ausente (está no arquivo de lock, mas não no disco).

Passo 4 — Encontre skills

npx skills find                    # busca interativa
npx skills find seo                # buscar por palavra-chave
npx skills find react --owner vercel   # apenas os repositórios de uma organização

Ou navegue por skills.sh, que classifica as skills por número de instalações e as agrupa por tópico. A skill mais instalada lá hoje é find-skills do próprio repositório da Vercel, que ensina seu agente a procurar skills sozinho. As contagens de instalação mudam todos os dias, então trate o ranking como uma dica, não como uma avaliação.

Passo 5 — Teste uma skill sem instalá-la

npx skills use vercel-labs/agent-skills@web-design-guidelines

Isso imprime um prompt pronto para essa skill, que você pode passar por pipe ou colar em um agente no mesmo computador. Adicione --agent claude-code e a CLI inicia o Claude Code com a skill carregada. É uma boa forma de testar uma skill antes que ela faça parte da sua configuração.

Passo 6 — Remova skills

npx skills remove web-design-guidelines            # deste projeto
npx skills rm --global web-design-guidelines       # dos seus skills globais
npx skills remove --agent claude-code my-skill     # de um único agente
npx skills remove vercel-labs/agent-skills         # tudo daquela origem
npx skills remove                                  # escolher de uma lista

npx skills remove --all remove todas as skills registradas no arquivo de lock e ignora pastas que não instalou, como skills que você mesmo escreveu, então não vai apagar seu próprio trabalho.

Passo 7 — Crie a sua própria

npx skills init my-skill cria my-skill/SKILL.md a partir de um modelo. A Parte 10 mostra um exemplo completo passo a passo.

A ferramenta inteira em um cartão

Quero… Comando
Ver o que um repositório oferece npx skills@latest add owner/repo --list
Instalar uma skill neste projeto npx skills add owner/repo --skill name
Instalar em todos os projetos add -g
Escolher os agentes add -a opencode -a claude-code (ou --agent '*' para todos)
Instalar sem nenhuma pergunta add -y
Fixar uma versão npx skills add owner/[email protected] --skill name
Listar skills instaladas npx skills ls · npx skills ls -g
Buscar npx skills find keyword
Verificar atualizações (somente leitura) npx skills@latest check · adicione -g ou -p
Instalar atualizações npx skills update · -g · -p · -y · ou nomeie as skills
Remover npx skills remove name · adicione -g para global
Restaurar as skills de um projeto a partir do arquivo de lock npx skills install
Criar uma nova skill npx skills init name

Comandos do skills 1.8.1. npx skills install (um alias de experimental_install) e o experimental_sync comando para skills distribuídas dentro de pacotes npm são marcados como experimentais e podem mudar.

O guia rápido da CLI npx skills: os comandos add, list, find, use, check, update, remove e init com suas flags mais úteis, os locais de instalação no projeto e global e os dois arquivos de lock
O skills CLI em uma ficha só. Dois hábitos fazem a maior parte do trabalho: --list antes de instalar, e @latest sempre que você verificar ou atualizar.

O que é um lock file, e devo fazer commit dele?

Um lock file é um recibo. Para cada skill, ele registra de onde ela veio e uma impressão digital da pasta dela (tecnicamente um hash: um código curto que muda sempre que qualquer arquivo na pasta muda). A CLI mantém dois tipos:

  • skills-lock.json em um projeto. Faça commit dele no Git. Em outro computador, ou para um colega, npx skills install restaura exatamente as mesmas skills, e --frozen-lockfile (o padrão em CI) se recusa a continuar se algo estiver diferente. Isso torna as skills de um projeto reproduzíveis, como package-lock.json faz com o código.
  • ~/.agents/.skill-lock.json para suas skills globais. Ele pertence à sua conta de usuário (ou fica em $XDG_STATE_HOME/skills/.skill-lock.json se você definiu essa variável). Não edite à mão, e note que cada usuário de um computador tem o seu, o que importa na Parte 6.

Telemetria, em resumo

A CLI envia dados de uso anônimos. Segundo a documentação dela, nomes de repositórios do GitHub e de skills só são incluídos quando o GitHub confirma que o repositório é público; outros tipos de origem também podem ser nomeados. Para desativar, adicione export DISABLE_TELEMETRY=1 (ou DO_NOT_TRACK=1) ao perfil do seu shell. Isso também desliga as consultas de auditoria de segurança que a CLI faz para skills públicas, então decida o que você valoriza mais.

Outros instaladores que você vai encontrar

A CLI de skills não é o único caminho. Vários agentes e ferramentas têm seus próprios instaladores, e todos seguem o mesmo padrão aberto:

Ferramenta Exemplo Vale saber
GitHub CLI (gh skill, versão 2.90 ou posterior, em prévia) gh skill install owner/repo skill-name --agent claude-code gh skill preview mostra uma skill antes de você instalá-la; --pin fixa uma versão
Hermes Agent hermes skills install <identifier> Seu hub inclui skills.sh, e toda instalação passa por verificação de segurança
Gemini CLI gemini skills install <git-url> --scope workspace para um projeto; pede consentimento a menos que você passe --consent
Codex $skill-installer <name> Uma skill de sistema integrada
Claude Code /plugin install name@marketplace Plugins empacotam skills com servidores MCP e hooks (Parte 9)

Uma regra evita a maioria das dores de cabeça: atualize uma skill com a mesma ferramenta com que você a instalou. Cada instalador mantém seus próprios registros, e nenhum deles sabe o que os outros fizeram.


Parte 5 — “Meu pacote de habilidades foi atualizado dois dias atrás. Como eu sei que tenho essa versão?”

Essa foi exatamente a minha pergunta quando Superpowers, a popular biblioteca de skills de Jesse Vincent, anunciou uma atualização. npx skills ls lista nomes, não versões, então não pode te dizer. Veja como a CLI realmente sabe.

Como a verificação funciona

Quando você instala uma skill, a CLI guarda a impressão digital da pasta dela no arquivo de trava. Quando você verifica, ela pede à origem (normalmente o GitHub) a impressão digital da mesma pasta hoje. Mesma impressão digital: atualizada. Diferente: há uma atualização. Ela não compara números de versão nem datas, e é por isso que funciona mesmo para skills que não têm nenhum dos dois.

cd /tmp                        # or a project folder, but never your home folder
npx skills@latest check -g     # your global skills

cd ~/code/my-app
npx skills@latest check -p     # this project's skills

Um resultado típico na 1.8.1 é assim:

↑ brainstorming tem uma atualização
↑ writing-plans tem uma atualização
2 skill(s) podem ser atualizadas; execute npx skills update para instalar

check também informa skills de projeto cujos arquivos não correspondem mais ao arquivo de lock (tem alterações locais), e ele sai com um código de erro sempre que algo está desatualizado ou modificado, então você pode usá-lo para parar uma build de CI que se desviou.

check mudou em novembro, então execute a versão mais recente

Desde a versão 1.7.5 (2 de novembro de 2026), check apenas informa. Em versões anteriores, pelo menos da 1.5.18 até a 1.7.4, check era simplesmente outro nome para update: ele perguntava “Update scope?” e instalava as atualizações conforme avançava. Se você já usou npx skills check antes de novembro e se perguntou por que ele estava “atualizando” coisas, é por isso. Use npx skills@latest check e você terá o comportamento somente leitura.

Mais dois detalhes que confundem as pessoas:

  • check escolhe um escopo por conta própria. Se a pasta em que você está contém um skills-lock.json arquivo, ou uma .agents/skills pasta com uma skill dentro, ele verifica projeto skills; caso contrário, ele verifica globais as globais. Adicione -g ou -p para indicar de qual você está falando.
  • Não existe a opção “atualizar tudo de um único repositório”. Ou você atualiza tudo em um escopo, ou nomeia as skills.

Depois, atualize

npx skills update                      # pergunta: projeto, global ou ambos
npx skills update -g                   # todos os skills globais
npx skills update -p                   # todos os skills do projeto
npx skills update brainstorming writing-plans -g   # apenas estes
npx skills update -y                   # sem perguntas: projeto se você estiver em um, senão global

Leia as mudanças antes de atualizar qualquer coisa importante. Abra o histórico de commits do repositório no GitHub e veja o que mudou nas pastas de skills: uma atualização são novas instruções que seu agente vai seguir com as suas permissões.

Se você o instalou como plugin, atualize-o como plugin

Muitos pacotes de skills agora são distribuídos como plugins, e o Superpowers é um bom exemplo. O README dele lista uma rota de instalação diferente para quase todo agente:

Agente Instalação do Superpowers, conforme o README dele Como ele se atualiza
Claude Code /plugin install superpowers@claude-plugins-official Automaticamente, pelo marketplace oficial da Anthropic
Codex CLI /plugins, procure por “superpowers”, Instalar plugin Pelo gerenciador de plugins
Cursor /add-plugin superpowers no chat do agente Pelo gerenciador de plugins
Gemini CLI gemini extensions install https://github.com/obra/superpowers gemini extensions update superpowers
GitHub Copilot CLI copilot plugin marketplace add obra/superpowers-marketplace, depois copilot plugin install superpowers@superpowers-marketplace Pelo gerenciador de plugins
Hermes Agent hermes plugins install obra/superpowers --enable Pelo gerenciador de plugins
OpenCode Adicione "superpowers@git+https://github.com/obra/superpowers.git" à lista de plugins em opencode.json, como descreve o guia de instalação do OpenCode Ao reiniciar; limpe o cache de pacotes do OpenCode se uma versão nova não aparecer, ou adicione #v5.0.3-style tags para fixar a versão

Do README do Superpowers e do seu guia de instalação do OpenCode, verificado em 15 de novembro de 2026.

Instalei o Superpowers no meu Mac com npx skills -g, então o meu se atualiza pela CLI de skills. Isso não é problema. O que é problema é instalar o mesmo pacote por dois canais: você acaba com duas cópias de cada skill com nomes idênticos, e sem jeito de saber qual delas o agente vai escolher.

Como funciona o npx skills check: o arquivo de lock guarda uma impressão digital de cada pasta de skill, o check a compara com a mesma pasta no upstream e relata atualizações, e o update as instala
check compara impressões digitais, não números de versão. Desde a 1.7.5 ele só relata; update é o comando que muda alguma coisa.

Parte 6 — Cinco problemas reais do meu Mac e do Raspberry Pi, e como resolvê-los

Tudo nesta parte aconteceu comigo no verão de 2026, na versão 1.5 da CLI. Cada problema foi verificado desde então contra o código-fonte da versão atual, a 1.8.1, para você saber quais já foram corrigidos e quais ainda incomodam. A saída do terminal é real; eu a encurtei e removi os nomes das máquinas.

Problema 1: “Todas as skills globais estão atualizadas”, quando nada foi verificado

No meu Mac, npx skills check produziu isto:

graham@mac my-app % npx skills check
◇  Update scope
│  Both
Checking for skill updates…
Global Skills
Checking skills from source: anthropics/skills
│  GitHub API request limit reached; checking existing gh authentication…
  ✗ Failed to fetch tree for anthropics/skills
Checking skills from source: vercel-labs/skills
  ✗ Failed to fetch tree for vercel-labs/skills
…                                  (six more sources, every one ✗)
Checking skills from source: obra/superpowers
  ✗ Failed to fetch tree for obra/superpowers
✓ All global skills are up to date

O que aconteceu. Para verificar um repositório, a CLI pede à API do GitHub a lista de arquivos do repositório. O GitHub permite 60 requisições anônimas por hora por endereço de internet, e a minha cota daquela hora já tinha acabado (a ferramenta diz isso na primeira linha), então toda consulta falhou. A linha final conta apenas as atualizações que a ferramenta encontrou, e não tinha encontrado nenhuma, então imprimiu um visto verde. A versão antiga também tentava pegar emprestado um login da GitHub CLI nos bastidores (é a linha “checking existing gh authentication”); como toda requisição continuava falhando, evidentemente não havia login para emprestar.

Já foi corrigido? Em parte. A versão 1.8.1 tenta mais antes de desistir: primeiro anônimo, depois um token do seu ambiente, depois o login da própria GitHub CLI via gh api, e, para verificações de atualização, um download Git simples como último recurso. Mas o código-fonte da 1.8.1 mostra que, quando uma fonte ainda não pode ser verificada, a linha de resumo continua contando apenas as atualizações que encontrou. Um visto verde sob cruzes vermelhas ainda é possível, então leia as linhas ✗.

A solução. Dê um login à CLI, o que eleva o limite para 5.000 requisições por hora:

  1. O mais fácil: instale o GitHub CLI e execute gh auth login. As versões atuais da CLI de skills pedem gh para fazer a chamada à API e nunca veem suas credenciais.
  2. Ou use um token: crie um token de acesso pessoal refinado com acesso somente leitura aos repositórios públicos e depois adicione-o ao perfil do seu shell (~/.zshrc no Mac, ~/.bashrc no Raspberry Pi):

bash export GITHUB_TOKEN="github_pat_…" # read-only, public repositories

Abra um novo terminal depois. Trate o token como uma senha: nunca cole em um chat, em uma skill ou em um arquivo que você vai comitar. 3. Atualize e verifique de novo: npx skills@latest check -g.

Problema 2: sudo me deixou com dois armazenamentos de skills e um erro do npm

No meu Raspberry Pi eu tinha criado o hábito de digitar sudo su primeiro. Foi isto que ele produziu:

graham@pi:~ $ sudo su
root@pi:/home/graham# npx skills update
npm error config prefix cannot be changed from project config: /home/graham/.npmrc.
◇  Update scope
│  Both
Checking for skill updates…
Global Skills
…
Found 6 global update(s)
…
Project Skills
Updating for: Universal, Claude Code, Hermes Agent
Refreshing 7 skill(s)…

E, um instante depois, de volta ao meu usuário normal:

graham@pi:~ $ ls ~/.agents/skills | wc -l
7
graham@pi:~ $ sudo ls /root/.agents/skills | wc -l
37

O que aconteceu. sudo su transforma você em root, e o root tem a própria pasta home, /root. As skills são armazenadas por usuário, então as skills globais do root ficam em /root/.agents/skills e as minhas em /home/graham/.agents/skills. Toda instalação global que eu já tinha feito como root tinha ido para o armazenamento do root: 37 skills lá, 7 no meu. Se seus agentes rodam com o seu usuário normal, que é a configuração habitual, tudo o que está no armazenamento do root fica invisível para eles.

O erro do npm tem a mesma causa. Como root, o arquivo de configurações pessoais do npm é /root/.npmrc, então o /home/graham/.npmrc que está na pasta em que eu estava é lido como um projeto arquivo de configurações. O próprio código do npm se recusa a deixar um arquivo de projeto mudar a prefix configuração, e registra exatamente esse erro. Há um terceiro risco que você não vê de imediato: tudo o que o root escreve dentro da sua pasta home acaba pertencendo ao root, e seu usuário normal não consegue atualizar depois.

A solução.

  1. Saia do root: type exit. De agora em diante, rode a CLI e seus agentes como você mesmo.
  2. Descubra qual usuário seus agentes usam. A pasta home que contém as configurações deles é a que importa:

bash ls -d ~/.claude ~/.config/opencode ~/.hermes 2>/dev/null sudo ls -d /root/.claude /root/.config/opencode /root/.hermes 2>/dev/null

  1. Reinstale as skills do root como você mesmo, a partir das fontes originais. Copiar os arquivos levaria junto a propriedade do root e registros desatualizados. Reinstalar grava um arquivo de lock limpo. Primeiro liste as fontes que o root usou:

bash sudo grep '"source"' /root/.agents/.skill-lock.json | sort -u

Depois, de uma pasta de projeto ou /tmp, execute npx skills add <owner/repo> -g -a <your agents> para cada uma que você ainda quiser. 4. Devolva suas próprias pastas para você, caso o root tenha escrito nelas:

bash sudo chown -R "$(id -un)":"$(id -gn)" ~/.agents ~/.claude ~/.hermes ~/.config/opencode 2>/dev/null

  1. Só quando tudo funcionar como você, exclua a cópia do root com sudo rm -rf /root/.agents.

Se você usa sudo porque instalações globais do npm falham sem ele, resolva isso de outra forma: aponte o prefixo do npm para uma pasta sua (npm config set prefix ~/.npm-global, depois adicione ~/.npm-global/bin ao seu PATH). É quase certamente o que a prefix linha no meu próprio .npmrc estava fazendo.

Problema 3: rode a partir da sua pasta home, e ela vira um “projeto”

De volta como eu mesmo, na minha pasta home:

graham@pi:~ $ npx skills check
Need to install the following packages:
[email protected]
Ok to proceed? (y) y
…
Global Skills
No global skills tracked in lock file.
Install skills with npx skills add <package> -g
Project Skills
Updating for: Universal, Claude Code, Hermes Agent
Refreshing 7 skill(s)…

O que aconteceu. A CLI decide que uma pasta é um projeto se ela contém um skills-lock.json arquivo ou uma .agents/skills pasta com uma skill dentro. Sua pasta home contém ~/.agents/skills, porque é onde ficam as skills globais, então a partir de ~ a CLI vê um projeto. E se você alguma vez rodou npx skills add na sua pasta home sem -g, você criou ali uma instalação de projeto de verdade, com seu próprio ~/skills-lock.json, cuja pasta de skills é exatamente a mesma que a instalação global usa. Era o que tinha acontecido no meu Pi: sete skills registradas como um “projeto” na minha pasta home, e absolutamente nada no meu próprio arquivo de lock global.

“No global skills tracked in lock file” tem três causas comuns: você nunca instalou com -g, você instalou com -g como outro usuário (root, via sudo), ou o arquivo de lock foi apagado. Se você leu em outro lugar que um generate-lock comando reconstrói esse arquivo, isso não existe: não há esse comando na versão 1.5 nem na 1.8.

A solução.

  • Rode a CLI a partir de uma pasta de projeto ou /tmp, nunca a partir de ~, e passe -g ou -p para que ela não possa adivinhar.
  • Para desembaraçar um “projeto” de pasta home, reinstale as skills que você quer com -g de outra pasta (elas vão para o mesmo lugar, agora registradas no seu arquivo de lock global), depois exclua ~/skills-lock.json. Não rode npx skills remove de ~ para isso: na sua pasta home, a pasta de projeto e a pasta global são a mesma pasta.

Problema 4: “No matching skills found” por causa de dois-pontos

graham@pi:~ $ npx skills remove ckm:banner-design ckm:brand ckm:design \
  ckm:design-system ckm:slides ckm:ui-styling
◇  Found 7 unique installed skill(s)
■  No matching skills found for: ckm:banner-design, ckm:brand, ckm:design, ckm:design-system, ckm:slides, ckm:ui-styling

O que aconteceu. Essas skills aparecem como ckm:banner-design, mas dois-pontos são um caractere arriscado em um nome de pasta, então a CLI salvou como ckm-banner-design: ela converte o nome para minúsculas e transforma qualquer coisa que não seja letras, dígitos, pontos e sublinhados em hífen. A versão 1.5.18 comparava o que eu digitei com os nomes das pastas exatamente, então nada correspondia.

Já foi corrigido? Sim. As versões atuais convertem sua entrada da mesma forma antes de comparar, então ckm:brand e ckm-brand as duas funcionam, e quando nada corresponde, a 1.8.1 imprime os nomes que são estão instalados.

A solução. Executar npx skills ls (ou ls ~/.agents/skills) para ver os nomes reais, ou execute npx skills remove sem argumentos e escolha na lista. Verifique o escopo também: de uma pasta de projeto, remover uma skill que está registrada no seu lock global agora avisa para adicionar -g.

Problema 5: seis skills falham, uma do mesmo repositório funciona

Refreshing 7 skill(s)…
✗ Failed to check for deleted skills from nextlevelbuilder/ui-ux-pro-max-skill
Updating ckm:banner-design…
  ✗ Failed to update ckm:banner-design
…                                  (five more ✗)
Updating ui-ux-pro-max…
  ✓ Updated ui-ux-pro-max

O que aconteceu. Para atualizar uma skill, a CLI procura por ela de novo no repositório de origem. Seis das minhas sete skills daquele repositório não foram encontradas, enquanto a sétima foi atualizada sem problema. Quando a maioria das skills de uma fonte falha e uma funciona, as que faltam normalmente foram renomeadas, movidas ou removidas no upstream. O README daquele repositório hoje descreve uma única skill, ui-ux-pro-max, e menciona banners, identidade de marca e slides apenas como recursos de um plano pago, o que combina com as seis terem saído do repositório gratuito.

A solução. Veja o que a fonte oferece agora e depois remova o que sumiu:

npx skills add nextlevelbuilder/ui-ux-pro-max-skill --list
npx skills remove ckm-banner-design ckm-brand ckm-design ckm-design-system ckm-slides ckm-ui-styling

As versões atuais da CLI percebem skills que foram excluídas no upstream e oferecem limpá-las durante uma atualização, e elas removem do arquivo de lock as skills que faltam quando você desinstala. Enquanto estiver nisso, procure duplicatas: se você também tem uma brand skill ao lado de ckm-brand, fique com uma. Duas skills com descrições quase idênticas confundem a escolha do agente e desperdiçam o orçamento de listagem dele.

Bônus: o Claude Code não vê uma skill que a CLI instalou

  • Verifique o link. O Claude Code lê apenas as pastas próprias, então ls -la ~/.claude/skills (ou .claude/skills no projeto) deve mostrar a skill, geralmente como um link para .agents/skills. Várias versões 1.5 corrigiram bugs nos links do Claude Code (1.5.16 e 1.5.20), então se ela estiver faltando, reinstale com npx skills@latest add … -a claude-code.
  • Verifique se o arquivo começa corretamente. A abertura --- do front matter deve ser a primeira linha de SKILL.md, ou o Claude Code trata o arquivo inteiro como texto simples.
  • Recarregue. O Claude Code capta skills editadas em tempo real, mas uma pasta de skills criada depois que a sessão começou precisa de /reload-skills. Então /skills lista o que está carregado.
Solução de problemas do npx skills: cinco erros reais e suas correções, de um falso tudo atualizado depois de um limite de taxa do GitHub ao sudo criando um segundo armazenamento de skills, uma pasta home tratada como projeto e skills excluídas no upstream
Cinco erros, cinco correções. A maioria se resume às mesmas duas regras: leia as linhas ✗ e nunca execute a CLI como root nem a partir da sua pasta pessoal.

Parte 7 — Servidores MCP sem jargão

O que acontece quando você conecta um servidor

  1. Você adiciona o servidor às configurações do seu agente: um comando para um servidor local, um endereço web para um servidor remoto.
  2. Quando uma sessão começa, o agente inicia o servidor local ou se conecta ao remoto, e faz login se o servidor exigir.
  3. O servidor lista suas ferramentas, e o agente repassa as descrições delas ao modelo.
  4. Quando uma tarefa precisa de uma ferramenta, o modelo a solicita, seu agente confere suas regras de permissão (e pode pedir sua confirmação), o servidor faz o trabalho e o resultado volta para a conversa.

Local ou remoto?

Servidor local (stdio) Servidor remoto (Streamable HTTP)
Executa No seu computador, iniciado pelo agente Nos computadores do provedor
Você adiciona Um comando, como npx @playwright/mcp@latest Um endereço, como https://mcp.context7.com/mcp
Login Geralmente uma chave de API em uma variável de ambiente Geralmente OAuth no seu navegador, ou uma chave em um cabeçalho
Precisa de Node.js, Python ou Docker, dependendo do servidor Uma conexão com a internet
Melhor para Coisas na sua máquina: um navegador, arquivos, um banco de dados local Serviços de nuvem: GitHub, Sentry, documentação, ferramentas de projeto
Fique atento a Ele roda com as permissões totais do seu usuário Seus dados vão para esse provedor

Você ainda pode encontrar um terceiro tipo, SSE, em guias mais antigos. A documentação do Claude Code o marca como obsoleto; use o endereço HTTP quando um servidor oferecer os dois.

Uma nota sobre versões

A especificação atual do MCP, lançada em 28 de julho de 2026, é a maior revisão desde o lançamento do protocolo: seu núcleo agora é sem estado, o que permite que servidores remotos rodem atrás de balanceadores de carga comuns. Raramente você precisa se preocupar, porque clientes e servidores entram em acordo sobre qual revisão usar e servidores mais antigos continuam funcionando. O OpenCode é o único lugar onde você pode ver isso: cada servidor tem uma configuração de protocolo (legacy por padrão, auto, ou 2026-07-28), e o pooling de conexões só funciona com a revisão mais recente.

A conta do contexto, e como mantê-la pequena

Toda ferramenta que um servidor oferece vem com uma descrição escrita para o modelo. Nas palavras do próprio OpenCode, “As ferramentas MCP consomem contexto do modelo, então adicione apenas os servidores de que você precisa.” Dois agentes agora suavizam o custo por padrão:

  • O Claude Code usa a busca de ferramentas. No início de uma sessão, ele carrega apenas os nomes das ferramentas e as instruções de cada servidor, e puxa a definição completa de uma ferramenta quando o Claude realmente a procura.
  • O OpenCode usa o Code Mode, que agrupa as ferramentas de cada servidor atrás de uma única entrada em vez de listar cada ferramenta separadamente. Fica ativado a menos que você defina "codemode": false para um servidor.

Em todos os outros lugares, e além desses padrões, estes são seus controles:

Agente Desative um servidor Oculte ferramentas que você não quer
OpenCode "disabled": true, ou /mcps para uma sessão A deny regra sobre <server>_<tool> em permissões
Claude Code claude mcp remove <name> (/mcp mostra o status) A deny regra de permissão em mcp__<server>__<tool>; ENABLE_TOOL_SEARCH decide quanto carrega antecipadamente
Codex enabled = false enabled_tools e disabled_tools
Gemini CLI gemini mcp disable <name> (adicione --session para uma sessão) includeTools e excludeTools
Cursor O botão do servidor em Personalizar (Administradores podem definir listas de ferramentas permitidas)
Hermes Agent enabled: false tools.include e tools.exclude

Minha regra: de dois a cinco servidores que você usa toda semana valem mais do que vinte que você talvez use um dia. Remova o resto; você pode adicioná-los de volta em um minuto.

Quatro servidores que vale a pena testar primeiro

Servidor O que ele dá ao seu agente Tipo Endereço ou comando Login
Context7 Documentação atual e específica de cada versão para bibliotecas e frameworks populares Remoto https://mcp.context7.com/mcp Nenhuma; uma chave de API gratuita aumenta os limites
GitHub (oficiais) Issues, pull requests, busca de código, Actions Remoto https://api.githubcopilot.com/mcp/ OAuth onde seu agente oferece suporte, ou um token de acesso pessoal
Playwright Um navegador de verdade que o agente pode abrir, percorrer clicando e capturar em tela Local npx @playwright/mcp@latest Nenhum
Sentry Seus erros e travamentos reais Remoto https://mcp.sentry.dev/mcp OAuth

Onde encontrar mais:

  • O MCP Registry, mantido pelos colaboradores do protocolo, lista os servidores publicados.
  • A própria documentação das suas ferramentas. A maioria dos serviços agora publica um servidor oficial; procure “MCP” na documentação deles.
  • O catálogo do seu agente. O Hermes Agent tem hermes mcp catalog, e muitos plugins do Claude Code trazem os próprios servidores.

Prefira servidores publicados pela empresa que opera o serviço. Um servidor aleatório chamado “github-mcp-pro” merece a mesma desconfiança que uma extensão de navegador aleatória.

A opção mais leve: uma ferramenta de linha de comando mais uma skill

Antes de adicionar um servidor, verifique se uma ferramenta de linha de comando já resolve o problema. O próprio Context7 oferece os dois caminhos: o servidor MCP acima, ou uma CLI pequena com uma skill (npx ctx7 setup --opencode, que exige Node.js 22.13 ou mais recente). A própria gh gh do GitHub, mais uma skill curta, cobre a maior parte do que o servidor dela faz.

Um servidor faz sentido quando seu agente não consegue executar comandos (um app de chat para desktop, por exemplo), o serviço não tem uma boa CLI, ou a tarefa é interativa, como pilotar um navegador. Uma CLI mais uma skill faz sentido quando a ferramenta já existe: não custa nada até ser usada, e sua saída pode ser enxugada antes de chegar ao modelo. Meu guia do OpenCode defende o mesmo argumento para o desenvolvimento de aplicativos.


Parte 8 — Adicionar um servidor MCP em seis agentes: receitas para copiar e colar

Cada receita adiciona os mesmos dois servidores: Context7 (remoto) e Playwright (local). Troque por qualquer outro servidor da mesma forma. Quando um agente tem tanto um comando quanto um arquivo de configurações, o comando simplesmente escreve o arquivo para você.

OpenCode

opencode mcp add context7 --url https://mcp.context7.com/mcp
opencode mcp add playwright -- npx @playwright/mcp@latest
opencode mcp list

Adicione --global para deixar um servidor disponível em todos os projetos. No opencode.jsonc a mesma configuração fica assim:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "oauth": false
        // With a free API key, add:
        // "headers": { "Authorization": "Bearer {env:CONTEXT7_API_KEY}" }
      },
      "playwright": {
        "type": "local",
        "command": ["npx", "@playwright/mcp@latest"]
      }
    }
  }
}
  • Segredos entram como {env:NAME}; o OpenCode não expande um simples $NAME.
  • Servidores remotos tentam OAuth automaticamente; oauth: false é para servidores que usam uma chave ou nenhuma. Faça login com opencode mcp auth <name>, e por SSH, cole a URL de callback da página de erro do navegador no prompt.
  • Dentro de uma sessão, /mcps conecta, desconecta ou faz login nos servidores.
  • Cada ferramenta se torna uma ação de permissão chamada <server>_<tool>, então { "action": "playwright_*", "resource": "*", "effect": "ask" } faz com que toda ação do navegador peça permissão primeiro.

Claude Code

claude mcp add --transport http context7 https://mcp.context7.com/mcp
claude mcp add playwright -- npx @playwright/mcp@latest
claude mcp list

O -- separa as opções do Claude Code do comando do próprio servidor. Os servidores usam por padrão escopo local (você, neste projeto). Adicione --scope user para todos os seus projetos, ou --scope project para escrever um .mcp.json arquivo que você pode commitar para sua equipe:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
  • .mcp.json expande ${VAR} e ${VAR:-default}, para que as chaves fiquem no seu ambiente, não no Git.
  • /mcp dentro de uma sessão mostra o status de cada servidor e cuida do login OAuth.
  • O Claude Code pergunta antes de usar servidores do .mcp.json, para que um repositório clonado não adicione os seus sem avisar.

Codex

O Codex mantém os servidores em ~/.codex/config.toml, ou em .codex/config.toml dentro de um projeto que você marcou como confiável:

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
  • Servidores remotos também podem ser adicionados com codex mcp add context7 --url https://mcp.context7.com/mcp, e codex mcp login <name> executa um login OAuth.
  • Para uma chave, bearer_token_env_var = "CONTEXT7_API_KEY" lê a chave do seu ambiente.
  • Ajuste um servidor com enabled_tools e disabled_tools; startup_timeout_sec (10 segundos por padrão) ajuda servidores lentos a iniciar.

Gemini CLI

gemini mcp add -t http context7 https://mcp.context7.com/mcp
gemini mcp add playwright npx @playwright/mcp@latest
gemini mcp list

gemini mcp add grava nas configurações do projeto por padrão; adicione -s user para todos os projetos. Em settings.json:

{
  "mcpServers": {
    "context7": { "httpUrl": "https://mcp.context7.com/mcp" },
    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }
  }
}
  • httpUrl é para Streamable HTTP; url significa o tipo SSE mais antigo.
  • Deixe trust desligado. Defina como true, ele ignora toda confirmação para esse servidor.
  • O Gemini CLI remove variáveis que parecem segredos (nomes que contêm TOKEN, SECRET, PASSWORD ou KEY) do ambiente de um servidor, a menos que você as liste no seu env bloco.
  • O OAuth precisa de um navegador na mesma máquina. Em uma pasta não confiável, servidores locais ficam desconectados até você executar gemini trust.

Cursor

O Cursor lê .cursor/mcp.json num projeto e ~/.cursor/mcp.json para tudo:

{
  "mcpServers": {
    "context7": { "url": "https://mcp.context7.com/mcp" },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
  • Servidores locais precisam de "type": "stdio".
  • Segredos entram como ${env:NAME}.
  • Ative e desative servidores com os botões em Personalizar.

Hermes Agent

O Hermes lê mcp_servers em ~/.hermes/config.yaml:

mcp_servers:
  context7:
    url: "https://mcp.context7.com/mcp"
  playwright:
    command: "npx"
    args: ["@playwright/mcp@latest"]
  • Executar /reload-mcp depois de editar, e hermes mcp test context7 para ver exatamente o que um servidor respondeu.
  • Para serviços OAuth, adicione auth: oauth a uma entrada HTTP. Em uma máquina headless, o Hermes oferece colagem de volta, encaminhamento de porta SSH ou um fluxo de login por dispositivo.
  • O Hermes passa aos servidores locais apenas as variáveis que você listar em env além de uma base segura, e não todo o ambiente do seu shell.
  • As ferramentas aparecem como mcp_<server>_<tool>; filtre-as com tools.include ou tools.exclude.

Confira se funciona, em qualquer agente

Faça uma pergunta que só o servidor pode responder: “Use o Context7 para ver como definir uma rota na versão atual do Next.js e me diga qual ferramenta você chamou.” Depois peça algo visível: “Abra example.com com o Playwright e descreva a página.” Se o agente disser que não tem essas ferramentas, liste os servidores (opencode mcp list, claude mcp list, gemini mcp list, hermes mcp test) e procure uma conexão que falhou ou um login que nunca terminou.

Como adicionar um servidor MCP no OpenCode, Claude Code, Codex, Gemini CLI, Cursor e Hermes Agent: o mesmo servidor Context7 no formato de comando ou de configuração de cada agente, mais um comando de servidor local
Um servidor, seis dialetos. As ideias são idênticas; só mudam os nomes de arquivo e os colchetes.

Parte 9 — Plugins: habilidades e servidores MCP em uma só caixa

Instalar dez skills e três servidores um por um cansa. Os plugins agrupam tudo, e a maioria dos agentes hoje tem algum tipo de sistema de plugins.

Plugins no Claude Code

Um plugin do Claude Code pode conter skills, subagentes, hooks, servidores MCP e servidores de linguagem. Os plugins vêm de marketplaces, que são simplesmente catálogos hospedados em um repositório Git:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

Em uma sessão, /plugin install primeiro abre os detalhes do plugin para você ver exatamente o que ele adiciona antes de escolher um escopo: você (todos os projetos), este repositório para todos ou este repositório só para você. No seu shell, claude plugin install <name>@<marketplace> faz o mesmo sem uma sessão.

Três recursos que vale conhecer:

  • O custo de contexto é visível. Para plugins do marketplace oficial da Anthropic, o painel de detalhes estima o que o plugin adiciona a cada mensagem e o que ele adiciona quando é usado. claude plugin details <name> mostra o número por sessão de tudo o que está instalado.
  • Atualizações. O marketplace oficial da Anthropic atualiza os plugins automaticamente; os marketplaces de terceiros não, a menos que você ative. claude plugin update <name>@<marketplace> atualiza um plugin manualmente.
  • Plugins sem uso são sinalizados. A aba Instalados agrupa os plugins que você não usa há um tempo, o que facilita a limpeza.

Plugins em outros agentes

  • Codex distribui skills reutilizáveis por meio de plugins (/plugins na CLI), e um plugin também pode trazer conexões com servidores MCP.
  • Gemini CLI chama isso de extensões: gemini extensions install <git-url> e gemini extensions update <name>.
  • GitHub Copilot CLI (copilot plugin install) e Hermes Agent (hermes plugins install) têm comandos de plugin, e Cursor tem /add-plugin no Agent chat.
  • OpenCode plugins são pacotes JavaScript ou TypeScript listados na lista de plugins configuração do arquivo de config, que pode registrar skills e ferramentas. É assim que o Superpowers se instala.

As duas regras que mantêm uma configuração de plugins sensata

  1. Um canal por pacote. Se um pacote de skills existe como plugin e como skills simples, escolha um. Duas cópias significam nomes duplicados e um agente que escolhe a primeira que encontrar.
  2. Atualize onde você instalou. A CLI skills não conhece plugins, e os gerenciadores de plugins não conhecem ~/.agents/skills.

Parte 10 — Escreva sua primeira habilidade em dez minutos

A melhor primeira skill resolve uma tarefa que você repete. Aqui está uma criada a partir da Parte 6: uma skill que permite a qualquer agente verificar se suas skills têm atualizações com segurança, sem nunca usar sudo ou confiar cegamente em um visto verde.

Passo 1 — Crie a pasta

mkdir -p ~/skills-drafts && cd ~/skills-drafts
npx skills init skills-housekeeping

Isso cria skills-housekeeping/SKILL.md a partir de um modelo. Substitua o conteúdo por este:

---
name: skills-housekeeping
description: Verifica se as skills de agente instaladas têm atualizações e problemas com a CLI npx skills, e explica os resultados em linguagem simples. Use quando perguntarem se as skills estão atualizadas, para atualizar skills, ou quando uma skill instalada parecer estar faltando.
metadata:
  author: graham-miranda
  version: "1.0"
---

# Manutenção de skills

## Regras
- Nunca execute nenhum comando com sudo.
- Nunca execute `npx skills update` ou `npx skills remove` sem perguntar antes.
- Execute comandos a partir de /tmp ou de uma pasta de projeto, nunca da pasta home.

## Verificação
1. Execute `cd /tmp && npx skills@latest check -g` para as skills globais.
2. Se o projeto atual tiver um arquivo skills-lock.json, execute também `npx skills@latest check -p` na pasta do projeto.
3. Trate toda linha que começa com ✗ como "não verificado", mesmo que uma linha posterior diga que tudo está atualizado.

## Relatório
- Liste as skills com atualizações, as skills com alterações locais e tudo o que não pôde ser verificado.
- Se alguma verificação falhou, sugira `gh auth login`, ou um GITHUB_TOKEN com acesso somente leitura a repositórios públicos.
- Pergunte antes de atualizar. Depois execute `npx skills update -g` (ou `-p`) e informe o que mudou.

Passo 2 — Verifique conforme o padrão

  • Nome: skills-housekeeping usa apenas letras minúsculas e hifens, tem menos de 64 caracteres e corresponde ao nome da pasta. Os três são obrigatórios.
  • Descrição: ela diz o que o que a skill faz e quando para usá-la, e contém as palavras que as pessoas realmente digitam (“up to date”, “update skills”, “missing”). A descrição é a única parte que o agente vê antes de decidir, então ela faz a maior parte do trabalho. O padrão permite até 1.024 caracteres; mire em uma ou duas frases.
  • Comprimento: bem abaixo das 500 linhas recomendadas. Quando uma skill cresce, mova os detalhes para references/ e aponte para ele a partir das instruções.

O projeto Agent Skills publica um validador de referência, skills-ref, que verifica o front matter e as regras de nomenclatura: skills-ref validate ./skills-housekeeping.

Passo 3 — Instale para todos os agentes de uma vez

A CLI skills também instala a partir de uma pasta local:

npx skills add ./skills-housekeeping -g -a opencode -a claude-code -a codex

Isso coloca a cópia real em ~/.agents/skills/skills-housekeeping (lida diretamente pelo OpenCode e pelo Codex) e adiciona um link em ~/.claude/skills para o Claude Code.

Passo 4 — Teste

Pergunte com palavras simples: “Minhas skills estão atualizadas?” Uma skill com uma boa descrição é carregada automaticamente. Se não for, chame-a pelo nome para descartar um problema de carregamento: @skills-housekeeping no OpenCode, /skills-housekeeping no Claude Code, $skills-housekeeping no Codex. Se ela carrega pelo nome mas nunca sozinha, o problema é a descrição: adicione as frases que você realmente usa.

Passo 5 — Compartilhe

Envie a pasta para um repositório do GitHub, de preferência dentro de uma skills/ pasta (skills/skills-housekeeping/SKILL.md). Qualquer pessoa pode então instalá-la com npx skills add your-name/your-repo. A CLI encontra skills em skills/ e em pastas comuns de agentes, até três níveis de profundidade.

Extras específicos de cada agente, e quando evitá-los

Vários agentes entendem campos extras no front matter. O Claude Code tem disable-model-invocation (só você pode acionar a skill) e context: fork (execute-a em um subagente); o Cursor tem caminhos (apenas para arquivos correspondentes); o OpenCode pode esconder uma skill do modelo com metadata definido como opencode/autoinvoke: false. Eles são úteis, mas o que viaja são os campos padrão. A documentação do próprio Claude Code observa que fora do Claude Code, em uploads no claude.ai ou na Skills API, só os campos padrão são aceitos e qualquer outra coisa é erro. Para skills que você compartilha, fique com nomear, descrição, license, compatibility, metadata e o experimental allowed-tools.

Anatomia de uma skill de agente: o front matter do SKILL.md lido na inicialização por cerca de 100 tokens, as instruções lidas quando uma tarefa corresponde, e referências, scripts e recursos lidos apenas quando necessário
Três camadas: o rótulo, a receita e o apêndice. Só a primeira é sempre carregada, por isso boas descrições importam mais do que instruções longas.

Parte 11 — Ficando seguro: habilidades e servidores são software

É fácil pensar numa skill como “apenas um arquivo Markdown”. Não é bem isso. São instruções que seu agente vai seguir com as suas permissões, muitas vezes com scripts que ele vai executar na sua máquina. E um servidor MCP local é um programa rodando como você.

Os números deste ano são preocupantes. O estudo ToxicSkills da Snyk, publicado em fevereiro de 2026, analisou 3.984 skills públicas de agentes: 36,82% tinham pelo menos uma falha de segurança, 13,4% tinham uma falha crítica, e 76 continham payloads maliciosos confirmados. O problema se concentrou no ClawHub, o marketplace da comunidade do OpenClaw, onde uma auditoria anterior de 2.857 skills, também divulgada pela Snyk, havia encontrado 341 maliciosas, cerca de 12% do registro na época. Em contrapartida, as 100 skills mais populares no skills.sh não acionaram nenhuma das verificações de injeção de prompt ou de código malicioso da Snyk. Popularidade não é prova, mas ajuda.

MCP tem sua própria versão do risco. A documentação do Claude Code avisa que servidores que buscam conteúdo externo podem expor você a injeção de prompt: uma página web, um comentário de issue ou um relatório de falha contendo texto destinado ao seu agente, não a você.

Dez hábitos que mantêm você seguro

  1. Leia antes de instalar. Uso npx skills add owner/repo --list, gh skill preview, ou simplesmente abra o SKILL.md e seus scripts no GitHub.
  2. Prefira os criadores e autores conhecidos. As skills da Expo para a Expo, as da Vercel para o Next.js, o servidor MCP oficial de um fornecedor para o próprio serviço dele.
  3. Confira as auditorias. Cada skill no skills.sh mostra resultados de três scanners: Gen Agent Trust Hub, Socket e Snyk. “Pendente” significa que ninguém olhou ainda.
  4. Fixe a versão de tudo que for importante. npx skills add owner/[email protected], ou gh skill install … --pin v1.2.3, para que as atualizações aconteçam quando você quiser.
  5. Revise atualizações como código. npx skills check, depois leia as mudanças no GitHub, depois npx skills update.
  6. Exija aprovação para skills de terceiros. No OpenCode, as regras usam a skill ação e a última correspondência vence:

jsonc "permissions": [ { "action": "skill", "resource": "*", "effect": "ask" }, { "action": "skill", "resource": "skills-housekeeping", "effect": "allow" }, { "action": "playwright_*", "resource": "*", "effect": "ask" } ]

O Hermes Agent verifica toda instalação vinda do hub, e --force não consegue anular um veredito “perigoso”. O Gemini CLI pede seu consentimento antes de ativar uma skill. 7. Dê aos servidores o menor acesso que funcione. Tokens somente leitura e granulares; tokens separados por servidor; ferramentas de escrita e exclusão em “perguntar” ou filtradas. 8. Mantenha segredos fora das skills e da configuração versionada. Use variáveis de ambiente ({env:NAME} no OpenCode, ${VAR} no .mcp.json, ${env:NAME} do Claude Code, no Cursor), nunca chaves coladas. 9. Cuidado com as configurações de projeto de outras pessoas. Um repositório clonado pode trazer seu próprio .mcp.json ou skills. O Claude Code pergunta antes de usar servidores do projeto, o Gemini CLI mantém servidores locais desconectados em pastas não confiáveis, e o Hermes Agent só carrega skills do projeto depois de hermes skills trust. Não avance por esses avisos no automático. 10. Desinstale o que você não usa. Toda skill e todo servidor sem uso é superfície de ataque que você paga em contexto.

Checklist de segurança de skills de agente e MCP: os números do ToxicSkills da Snyk para 3.984 skills públicas e dez hábitos seguros, de ler antes de instalar e fixar versões a tokens com privilégio mínimo
Uma skill é um conjunto de instruções que seu agente segue com as suas permissões. Instale com o mesmo cuidado que daria a qualquer outro software.

Parte 12 — Uma rotina semanal de dois minutos

Skills e servidores se desatualizam. Uma rotina curta mantém tudo em dia:

# Skills globais, de uma pasta neutra
cd /tmp && npx skills@latest check -g

# Cada projeto em que você está trabalhando ativamente
cd ~/code/my-app && npx skills@latest check -p

# Depois de ler o que mudou upstream:
npx skills update -g

Uma vez por mês, tire mais cinco minutos:

  • Faça uma limpeza. npx skills ls -g e remova o que você não usou. No Claude Code, o painel de plugins lista os plugins que você não usou recentemente.
  • Liste seus servidores. opencode mcp list, claude mcp list, gemini mcp list ou hermes mcp test para cada um. Remova o que você esqueceu de adicionar.
  • Renove os tokens que você deu aos servidores, especialmente os que podem gravar.

Duas máquinas, uma configuração

Eu rodo agentes num Mac e num Raspberry Pi, e três hábitos os mantêm em sincronia:

  1. A mesma abordagem nos dois: seu usuário normal, nunca sudo, e a CLI rodada de uma pasta de projeto ou /tmp.
  2. As skills de projeto viajam com o Git. Commit .agents/skills e skills-lock.json, na outra máquina, npx skills install restaura exatamente as mesmas versões.
  3. As skills globais vêm de um script. Mantenha seu npx skills add … -g os comandos num pequeno arquivo shell e execute-o em cada máquina. Ele também serve como documentação do que você usa.

Numa máquina headless como um Pi, defina GITHUB_TOKEN em ~/.bashrc para que as verificações de atualização não atinjam o limite anônimo. Logins pelo navegador exigem cuidado: o OpenCode permite colar a URL de callback no prompt, o Hermes Agent oferece colar de volta, encaminhamento de porta SSH ou um device flow, enquanto o fluxo OAuth do Gemini CLI precisa de um navegador na mesma máquina.


Parte 13 — Qual configuração você deve escolher? Cinco cenários

1. “Acabei de começar com o OpenCode.”

Instale no máximo três skills e um servidor MCP. O Context7 é um bom primeiro servidor, e uma skill de release ou de revisão que combine com seu jeito de trabalhar é uma boa primeira skill. Mantenha as skills de terceiros em perguntar nas permissões do OpenCode até você confiar nelas. Meu guia do OpenCode cobre o resto da configuração.

2. “Uso o OpenCode e o Claude Code lado a lado, talvez o Hermes Agent também.”

Instale as skills globalmente com a CLI e nomeie cada agente: npx skills add owner/repo -g -a opencode -a claude-code -a hermes-agent. Uma cópia, três agentes. Os servidores MCP não compartilham um arquivo de configuração comum, então adicione cada um a cada agente e guarde a lista num lugar que você encontre. Meu comparativo do OpenCode, Hermes Agent e OpenClaw explica onde cada agente se destaca, e meu comparativo de harness de codificação com IA cobre 28 deles lado a lado.

3. “Minha equipe compartilha um repositório.”

Uso escopo de projeto: faça commit .agents/skills, skills-lock.json, e as configurações de MCP (opencode.jsonc, .mcp.json ou .cursor/mcp.json) sem segredos nelas. Cada pessoa mantém as chaves no próprio ambiente. Na CI, npx skills install --frozen-lockfile falha se as skills de alguém divergirem, e npx skills check -p falha quando há atualizações esperando.

4. “Meus agentes rodam num Raspberry Pi ou num servidor.”

Um usuário normal, sem sudo, nunca. Defina GITHUB_TOKEN, prefira servidores remotos que aceitam um token em um cabeçalho (ou oferecem login pelo dispositivo) e execute a verificação semanal a partir de /tmp. A Parte 6 é a sua lista de verificação.

5. “Meu código não pode sair da minha máquina.”

Uso apenas servidores MCP locais, e dispense os servidores remotos de documentação e de busca de código. Desative a telemetria da CLI (DISABLE_TELEMETRY=1), leia cada skill que instalar e lembre-se de que o modelo em si ainda pode ser um modelo na nuvem: a privacidade depende de onde ele modelo roda também. Meu guia para rodar LLMs em um MacBook mostra quanto custa de verdade a rota totalmente local.


Perguntas frequentes

O que são agent skills?

Skills de agente são pastas que ensinam a um agente de IA como fazer um trabalho específico. Cada uma contém um SKILL.md arquivo com um nome, uma descrição e instruções passo a passo, além de scripts e arquivos de referência opcionais. O agente lê apenas as descrições no início de uma sessão e carrega as instruções completas de uma skill quando a tarefa corresponde. As skills seguem um padrão aberto, então a maioria funciona igualmente no OpenCode, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot e Hermes Agent.

O que é um servidor MCP?

Um servidor MCP é um pequeno programa que dá novas ferramentas a um agente de IA por meio do Model Context Protocol, um padrão aberto hoje hospedado pela Agentic AI Foundation, da Linux Foundation. Servidores locais rodam no seu computador e são iniciados pelo agente; servidores remotos rodam nos computadores de um provedor e são acessados por um endereço web, geralmente com login pelo navegador. Exemplos incluem o servidor oficial do GitHub, o Context7 para documentação atualizada e o Playwright para controlar um navegador.

Qual é a diferença entre skills de agente e servidores MCP?

Uma skill dá know-how ao agente: instruções escritas de como fazer um trabalho, carregadas apenas quando necessário. Um servidor MCP dá habilidades ao agente: ferramentas que alcançam sistemas fora do terminal, como o GitHub, um navegador ou um rastreador de falhas. Use uma skill para procedimentos e convenções, um servidor MCP para acesso ao vivo a um sistema, e AGENTS.md para regras que valem para toda tarefa. Se já existe uma boa ferramenta de linha de comando, uma skill que a ensina costuma sair mais barata que um servidor.

As skills funcionam do mesmo jeito no OpenCode, Claude Code e Codex?

Em grande parte, porque os três seguem o padrão Agent Skills. A diferença está em onde eles procuram. Codex e OpenCode leem as .agents/skills e ~/.agents/skills pastas compartilhadas; o OpenCode também lê .opencode/skills e as pastas do Claude Code. O Claude Code lê apenas .claude/skills e ~/.claude/skills. Alguns campos extras de front matter, como os do Claude Code context: fork, funcionam em apenas um agente, então skills compartilhadas devem ficar nos campos padrão.

Como instalo uma skill com o npx skills?

Executar npx skills add owner/repo --list para ver as skills que um repositório oferece, depois npx skills add owner/repo --skill skill-name -a opencode -a claude-code para instalar uma para os agentes que você usa. Adicione -g para deixá-la disponível em todos os projetos. Você precisa do Node.js 22.20 ou mais recente. Sem flags, a CLI pergunta quais skills e agentes você quer e se deve vincular ou copiar os arquivos.

Onde o npx skills instala as skills?

Instalações no projeto colocam a cópia real em .agents/skills/<name> dentro do seu projeto e a registram em skills-lock.json. Instalações globais (-g) a colocam em ~/.agents/skills/<name> e a registram em ~/.agents/.skill-lock.json. Agentes que leem .agents/skills usam essa cópia diretamente; para agentes com pasta própria, como o Claude Code (.claude/skills) ou o Hermes Agent (~/.hermes/skills), a CLI cria um link para ela.

Como sei se minhas skills estão atualizadas?

Executar npx skills@latest check -g para skills globais, ou npx skills@latest check -p dentro de um projeto. A CLI compara a impressão digital de cada pasta de skill no seu arquivo de lock com a mesma pasta no upstream e lista toda skill que tem atualização, sem instalar nada. Desde a versão 1.7.5 (2 de novembro de 2026), check apenas informa; npx skills update instala. Execute a partir de uma pasta de projeto ou /tmp, não da sua pasta home.

Por que o npx skills diz que todas as skills estão atualizadas quando a verificação falhou?

Porque o resumo só conta as atualizações que ele encontrou. Se o limite do GitHub de 60 requisições anônimas à API por hora bloquear todas as consultas, a CLI imprime uma linha ✗ para cada fonte e ainda pode terminar com “All global skills are up to date”. Entre com gh auth login ou defina um GITHUB_TOKEN para elevar o limite para 5.000 requisições por hora, faça upgrade com npx skills@latest, e sempre leia as linhas ✗.

Devo usar sudo com o npx skills?

Não. As skills são armazenadas por usuário, e o root tem sua própria pasta home, então sudo instala skills em /root/.agents/skills, onde agentes executados com o seu usuário normal nunca as veem. Também pode deixar arquivos de propriedade do root nas suas próprias pastas e disparar erros do npm como “o prefixo não pode ser alterado a partir da configuração do projeto”. Execute a CLI e seus agentes com o seu usuário normal.

Como adiciono um servidor MCP ao OpenCode?

Executar opencode mcp add <name> --url <address> para um servidor remoto, ou opencode mcp add <name> -- <command> para um local, depois verifique com opencode mcp list. Adicione --global para usá-lo em todos os projetos. As mesmas configurações podem ficar em mcp.servers em opencode.jsonc, com segredos escritos como {env:NAME}. Use opencode mcp auth <name> para fazer login, e /mcps dentro de uma sessão para conectar ou desconectar servidores.

Quantos servidores MCP devo instalar?

O mínimo que você realmente usa, normalmente de dois a cinco. As ferramentas de cada servidor vêm com descrições que o modelo precisa ler, o que consome contexto e pode deixar as respostas mais lentas e menos focadas. O Claude Code adia as definições de ferramentas até que sejam necessárias, e o OpenCode as agrupa por servidor, o que ajuda, mas servidores sem uso ainda somam risco e desordem. Remova tudo que você não usou em um mês.

É seguro instalar agent skills?

Só tão seguras quanto a sua fonte. Uma skill é um conjunto de instruções que seu agente segue com as suas permissões, muitas vezes com scripts que ele executa. O estudo da Snyk de fevereiro de 2026 com 3.984 skills públicas encontrou falhas de segurança em 36,82% e confirmou cargas maliciosas em 76. Leia uma skill e seus scripts antes de instalar, prefira skills dos próprios criadores da ferramenta, confira os resultados de auditoria em skills.sh, fixe as versões e mantenha skills de terceiros em “ask” nas permissões do seu agente.

O que é skills-lock.json?

É o arquivo de lock do projeto que a CLI de skills grava quando você instala skills em um projeto. Ele registra de onde cada skill veio e uma impressão digital dos seus arquivos. Faça commit dele no Git: em outro computador, npx skills install restaura exatamente as mesmas skills, e --frozen-lockfile falha se algo estiver diferente. As skills globais têm um arquivo de lock separado em ~/.agents/.skill-lock.json, um por conta de usuário.

O que é skills.sh?

skills.sh é o diretório público de skills de agentes da Vercel. Ele classifica as skills por instalações, agrupa por tema e mostra os resultados da auditoria de segurança do Gen Agent Trust Hub, do Socket e da Snyk para cada uma. Você instala skills a partir dele com o npx skills add owner/repo O comando npx skills find da mesma CLI pesquisa o diretório a partir do seu terminal.

A conclusão

Agent skills e servidores MCP respondem a duas perguntas diferentes. As skills respondem “como fazemos isso aqui?”: são cartões de receita baratos e portáteis que só carregam quando necessário. Os servidores MCP respondem “você consegue alcançar esse sistema?”: são chaves poderosas que custam contexto e merecem o mesmo cuidado de qualquer software que você instala. AGENTS.md guarda as poucas regras que valem para tudo, e as permissões impõem o que nunca pode acontecer.

Se você levar cinco coisas deste guia, leve estas:

  1. Coloque as skills compartilhadas em .agents/skills e deixe npx skills criar links delas nos agentes que procuram em outro lugar.
  2. Executar npx skills@latest check a partir de uma pasta de projeto ou /tmp, leia as linhas ✗ e atualize de forma deliberada.
  3. Faça login no GitHub (gh auth login) em toda máquina que verifica atualizações.
  4. Nunca use sudo com skills ou agentes.
  5. Comece com três skills e um servidor, e adicione mais apenas quando uma tarefa real pedir por elas.

Skills e servidores transformam um generalista esperto em um colega que conhece o seu jeito de trabalhar e consegue acessar as suas ferramentas. O truque é dar a ele exatamente o que precisa, e nada que ele não precise.


Usa skills ou servidores MCP que eu não mencionei? Gostaria de saber quais conquistaram um lugar permanente na sua configuração, e quais mensagens de erro fizeram você sair procurando. Correções são bem-vindas: este artigo é atualizado quando as ferramentas mudam, o que, a julgar por este ano, será com frequência.

Divulgação: Nenhuma empresa citada neste artigo patrocinou, revisou ou aprovou o conteúdo, e ele não contém links de afiliados. Os produtos são nomeados apenas no texto; as imagens usam meus próprios logos.

Última atualização: 15 de novembro de 2026.

Adicione seu sinal.

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *

pt_BRPortuguês do Brasil