Agent Skills vs MCP: escolhendo a interface certa

A decisão entre agent skills vs MCP costuma ser apresentada como uma disputa entre duas formas de “dar ferramentas a uma IA”. Essa perspectiva é incompleta. Um skill e um servidor do Model Context Protocol resolvem camadas diferentes do problema: um ensina o agente a operar em um domínio, enquanto o outro expõe capacidades e contexto por meio de uma conexão padronizada.

O Dockup usa um SKILL.md porque sua interface principal é uma ferramenta de linha de comando existente. O skill ensina o Claude Code e o Codex a usar essa CLI com segurança: sempre solicitar JSON, autenticar de forma não interativa, resolver destinos exatos, aguardar estados finais de deployment e parar antes de executar ações destrutivas.

O que é um agent skill e por que o SKILL.md é importante?

Um agent skill é um diretório de instruções operacionais e referências de apoio que um agente pode carregar quando uma tarefa corresponde ao objetivo do skill. SKILL.md é o ponto de entrada: seu frontmatter descreve a capacidade, e o corpo explica workflows, restrições, exemplos e regras de decisão.

Um skill é especialmente útil quando a interface executável já existe. O agente não precisa de um novo adaptador de protocolo apenas para executar uma CLI bem projetada. Ele precisa de conhecimento preciso sobre:

• Quais comandos são a fonte de verdade.
• Quais flags são obrigatórias para uso por máquinas.
• Como a autenticação funciona em um sandbox.
• Quais saídas comprovam o sucesso.
• Quais ações exigem intervenção humana.
• Onde os secrets podem aparecer.
• Como diagnosticar falhas comuns.

A instalação do Dockup é intencionalmente simples:

npm install -g dockup-cli
dockup skill install
dockup skill status --json

Uma única cópia canônica é gravada em ~/.agents/skills/dockup/ e vinculada ao Claude Code e ao Codex. O skill é distribuído dentro do pacote da CLI, e dockup update atualiza ambos em conjunto. Essa decisão de empacotamento evita um problema comum: instruções que descrevem comandos inexistentes no binário instalado.

O skill não é o mecanismo de deployment. A CLI executa as operações, emite JSON e retorna exit codes. O skill é o manual operacional que o agente segue.

O que é o Model Context Protocol?

O Model Context Protocol, normalmente chamado de MCP, é um protocolo aberto para conectar uma aplicação de IA a ferramentas, recursos e prompts externos por meio de uma arquitetura cliente-servidor. Um servidor MCP pode expor ferramentas invocáveis, recursos legíveis e prompts reutilizáveis. Um cliente MCP dentro do host do agente descobre e invoca essas capacidades.

O MCP é valioso quando um sistema precisa de um limite de protocolo durável, em vez de uma execução local via shell. Alguns exemplos incluem:

• Uma API SaaS remota que deve expor operações cuidadosamente tipadas.
• Uma fonte de dados que fornece recursos navegáveis.
• Uma aplicação desktop que deseja descoberta de ferramentas sem distribuir uma CLI.
• Um serviço central usado por vários hosts de agentes e sistemas operacionais.
• Uma integração na qual o servidor deve mediar credenciais e políticas.

O servidor controla a implementação por trás de cada ferramenta. O host do agente vê o nome declarado, a descrição, o input schema e a saída. O transporte, o ciclo de vida e a autorização dependem da configuração de MCP escolhida.

O MCP não fornece julgamento de domínio automaticamente. Um servidor pode expor delete_service, mas o agente ainda precisa de uma política que determine quando a exclusão é apropriada. Da mesma forma, um skill pode explicar um workflow, mas não pode criar capacidades ausentes da CLI ou API subjacente.

Como agent skills vs MCP diferem na prática?

A comparação mais clara é por responsabilidade:

Dimensão	Agent skill / SKILL.md	Servidor MCP
Objetivo principal	Ensinar workflows e restrições	Expor ferramentas, recursos e prompts
Execução	Usa CLIs, arquivos, APIs ou aplicações existentes	O servidor implementa capacidades invocáveis
Descoberta	O agente carrega as instruções do skill correspondente	O cliente descobre as capacidades do servidor
Distribuição	Normalmente uma pasta instalada com um pacote	Um processo de servidor local ou remoto
Risco de versão	As instruções podem divergir da ferramenta	O schema do servidor pode divergir do comportamento do backend
Melhor aplicação	Uma interface existente precisa de orientação operacional especializada	Uma capacidade precisa de um limite de protocolo padronizado
Foco de segurança	Regras comportamentais e segurança dos comandos	Conexão, confiança no servidor, scopes e autorização das ferramentas
Uso offline/local	Excelente com CLIs locais	Possível com um servidor MCP local
Reutilização entre clientes	Copiar ou empacotar o skill para cada host	Um servidor pode atender vários clientes compatíveis

Nenhuma das colunas é inerentemente mais “agentic”. A confiabilidade vem de combinar a interface com o sistema adequado.

No caso do Dockup, a CLI já tem 135 comandos, JSON estruturado, exit codes reais, um timeout padrão de deployment de 900 segundos, mascaramento de secrets e gates de confirmação. Envolver todos os comandos em outro servidor local adicionaria uma camada de tradução sem alterar a fonte de verdade do deployment. Um skill é uma escolha direta porque ensina o agente a usar o contrato executável que já existe.

Uma plataforma remota sem CLI pode chegar à conclusão oposta. Um servidor MCP pode fornecer a superfície de ferramentas tipadas que falta e manter as credenciais da API fora do ambiente shell do agente.

Quando usar um skill, MCP ou ambos?

Use apenas um skill quando todas as condições a seguir forem verdadeiras:

1. Uma CLI madura ou aplicação local já expõe a capacidade necessária.
2. O host do agente tem permissão para executá-la.
3. A saída legível por máquina e a semântica dos exit codes são adequadas.
4. A principal lacuna é conhecimento procedural, não conectividade.
5. O empacotamento consegue manter as instruções alinhadas ao executável.

Use apenas MCP quando o agente precisa de uma conexão nativa de protocolo e o próprio servidor consegue fornecer contexto suficiente para uma operação segura. Isso é comum em acesso a dados com predominância de leitura, serviços remotos e aplicações que desejam uma interface de ferramentas estável entre diferentes clientes.

Use ambos quando as ferramentas do protocolo precisam de um playbook operacional mais completo. Um servidor MCP pode expor primitivas seguras e tipadas, enquanto um skill explica o workflow de negócio com várias etapas, as regras de escalonamento e os critérios de validação. O skill pode informar ao agente quando e por que chamar cada ferramenta MCP.

Uma arquitetura combinada pode ter esta aparência:

Solicitação do usuário
    ↓
Skill: workflow, política, regras de validação
    ↓
Cliente MCP: descobre capacidades tipadas
    ↓
Servidor MCP: autentica e executa
    ↓
Sistema externo

Uma arquitetura centrada em CLI é mais simples:

Solicitação do usuário
    ↓
Skill: workflow, política, regras de validação
    ↓
CLI: saída JSON + exit code + semântica de espera
    ↓
API da plataforma

A complexidade deve ser justificada por um limite que ela melhora. Adicionar MCP apenas porque está na moda pode criar outro processo para distribuir, autenticar, monitorar e versionar.

Exemplos de decisão

Situação	Melhor ponto de partida	Motivo
CLI local de deployment com saída JSON	Skill	A conectividade já existe
Base de conhecimento corporativa com recursos estruturados	MCP	A descoberta de recursos é central
API de administração de banco de dados sem CLI	MCP	Operações remotas tipadas são úteis
Runbook complexo de release entre ferramentas existentes	Skill	O procedimento entre ferramentas é a principal necessidade
Operações remotas regulamentadas com política detalhada	Ambos	O servidor aplica o scope; o skill orienta o comportamento
Automação pessoal pontual	Skill ou CLI direta	Menor overhead operacional

A resposta certa pode mudar com o tempo. Uma equipe pode começar com um skill em torno de uma CLI e depois adicionar um servidor MCP quando o acesso remoto por vários clientes ou a mediação centralizada de credenciais se tornar importante.

Como os limites de segurança e confiança se comparam?

Skills são instruções, portanto seu risco de confiança se assemelha ao de uma documentação de código com influência operacional. Um skill malicioso ou descuidado pode instruir um agente a expor secrets, desativar salvaguardas ou executar comandos destrutivos. Revise o diretório completo, não apenas o título.

Perguntas para revisar um skill incluem:

• Quem o publicou?
• Ele invoca comandos fora do objetivo declarado?
• Instrui o agente a imprimir tokens ou credenciais?
• Ignora confirmações?
• Os exemplos de comandos vêm da versão instalada?
• As atualizações podem substituir o skill sem revisão?
• O skill define um processo limitado de descoberta de destinos?

O MCP introduz um limite de confiança no servidor. O cliente precisa saber a qual servidor está se conectando, quais ferramentas ele expõe, quais dados saem da máquina e como a autorização é delimitada. Um servidor pode alterar o comportamento por trás de um nome de ferramenta estável, portanto a procedência do deployment e o versionamento do servidor são importantes.

Perguntas para revisar um MCP incluem:

• O servidor é local ou remoto?
• Quem o opera?
• Como as credenciais são armazenadas e rotacionadas?
• Quais chamadas de ferramentas podem alterar ou excluir dados?
• Os inputs das ferramentas são validados no servidor?
• As saídas são tratadas como conteúdo não confiável?
• Todas as chamadas podem ser auditadas?
• O cliente pode restringir as ferramentas disponíveis?

O host do agente não deve interpretar “descoberto por meio do MCP” como sinônimo de “seguro”. A padronização do protocolo melhora a interoperabilidade, não a confiabilidade de todos os servidores.

O skill do Dockup codifica várias regras de segurança: usar DOCKUP_TOKEN em vez de login interativo, nunca imprimir credenciais, descobrir destinos com dockup services --json, usar --wait e parar diante de needs_confirm. A CLI reforça essas instruções mascarando secrets e recusando operações destrutivas sem aprovação explícita. Esse modelo de defesa em profundidade é descrito em guardrails de produção para agentes de IA.

Como devem funcionar o versionamento e a recuperação de falhas?

Pode haver version drift nas duas abordagens, mas ele se manifesta de maneiras diferentes.

Um skill pode ficar desatualizado quando o comando documentado muda. A mitigação mais forte é empacotar o skill com o executável e atualizar ambos por meio de um único processo de release. O Dockup segue esse modelo. O agente pode verificar o skill instalado:

dockup skill status --json

Uma atualização atualiza a CLI e o skill incluído em conjunto:

dockup update

Um cliente MCP pode descobrir os tool schemas atuais do servidor, mas a compatibilidade do schema não garante compatibilidade semântica. Uma ferramenta pode manter os mesmos inputs e ainda assim alterar autorização, efeitos colaterais, latência ou interpretação da saída. O servidor deve publicar versões, preservar a compatibilidade retroativa sempre que possível e retornar erros estruturados.

O tratamento de falhas também é diferente. Uma CLI oferece exit codes de processo naturalmente. Uma chamada de ferramenta MCP precisa de um resultado igualmente claro no nível da aplicação. Em ambos os casos, o agente não deve inferir sucesso a partir de uma confirmação no nível do transporte.

Uma checklist útil de confiabilidade é:

Requisito	Implementação com skill + CLI	Implementação com MCP
Descoberta de capacidades	Schema da CLI	Lista de ferramentas do servidor
Saída estruturada	JSON/NDJSON	Resultado de ferramenta tipado
Sinal de falha	Exit code diferente de zero + código	Resultado de erro explícito
Operação longa	--wait / stream documentado	Protocolo de progresso ou conclusão
Proteção de secrets	Mascaramento e disciplina de stderr	Redação no servidor
Aprovação destrutiva	Gate de confirmação da CLI	Política do servidor ou confirmação do cliente
Auditoria	Log de auditoria da plataforma	Logs de auditoria do servidor e do backend
Verificação de versão	Status do skill/binário	Metadados e schemas do servidor

A interface deve tornar mais difícil relatar uma falha incorretamente do que relatar um sucesso.

Que arquitetura uma equipe de produção deve escolher?

Comece identificando a lacuna real.

Escolha uma arquitetura skill-first quando a equipe já confia em uma CLI e a opera. Invista no contrato de máquina: JSON, exit codes reais, códigos de erro estáveis, instruções alinhadas à versão e confirmação. Em seguida, empacote o skill com essa ferramenta. Esse é o caminho mais curto para deployment com Claude Code e deployment com Codex usando o Dockup.

Escolha MCP-first quando a capacidade for naturalmente remota, orientada a recursos ou compartilhada entre vários clientes. Trate o servidor como software de produção: autentique-o, delimite seus scopes, monitore-o e revise cada mutação.

Escolha ambos quando a política e a conectividade forem complexas de forma independente. Mantenha as responsabilidades claras. O skill não deve duplicar a implementação do servidor, e a descrição do servidor não deve se transformar em um manual operacional extenso.

Um workshop prático de avaliação

Faça uma prova pequena com uma operação de leitura, uma escrita reversível, uma operação de longa duração e uma operação destrutiva que precise ser bloqueada. Avalie cada design com base em:

1. Como o agente descobre a operação.
2. Como as credenciais são fornecidas.
3. Como o sucesso é comprovado.
4. Como a falha é categorizada.
5. Como uma pessoa aprova ações perigosas.
6. Como logs e evidências de auditoria são obtidos.
7. Como as versões permanecem alinhadas.
8. Como a integração é removida de forma limpa.

Não tome a decisão apenas com base em um diagrama. Observe os caminhos de falha. Um design que parece elegante no caminho feliz pode se tornar ambíguo quando um deployment excede o tempo limite, um servidor se desconecta ou um arquivo de instruções fica uma release atrás.

A referência da CLI do Dockup fornece um exemplo concreto de um contrato de CLI apoiado por um skill. O artigo mais amplo sobre desenvolvimento com IA explica por que essas interfaces são importantes à medida que os agentes assumem uma parte maior do ciclo de desenvolvimento.

Considere a responsabilidade operacional

A pessoa ou equipe responsável pela integração importa tanto quanto sua arquitetura. Um skill associado a uma CLI normalmente herda o processo de instalação, release e suporte dessa CLI. A equipe que publica o binário pode distribuir as instruções correspondentes e testá-las em conjunto.

Um servidor MCP cria um componente de produção separado. Alguém precisa ser responsável por hospedagem, certificados ou inicialização do processo local, autenticação, monitoramento, resposta a incidentes, compatibilidade de schemas e atualizações de dependências. Esse investimento pode valer a pena quando o servidor representa um limite compartilhado relevante. É overhead desnecessário quando ele apenas encaminha chamadas locais para um executável que já é suficiente.

Durante a avaliação, registre quem é responsável por cada camada:

Camada	Responsável em uma abordagem skill-first	Responsável em uma abordagem MCP-first
Instruções de domínio	Publicador do skill	Prompt do cliente ou skill complementar
Comportamento executável	Publicador da CLI	Equipe do servidor MCP
Gestão de credenciais	CLI e ambiente de runtime	Servidor e conexão do cliente
Disponibilidade	Executável local e API da plataforma	Processo do servidor, transporte e backend
Compatibilidade de schemas	Processo de release da CLI	Processo de release do servidor MCP
Evidências de incidentes	Saída da CLI e auditoria da plataforma	Logs do cliente, logs do servidor e auditoria do backend

Essa tabela de responsabilidades costuma resolver o debate sobre agent skills vs MCP com mais clareza do que uma checklist de funcionalidades.

Avalie a latência e as superfícies de falha

Uma chamada com skill local e CLI percorre um caminho curto: host do agente, processo e API da plataforma. Um caminho MCP pode adicionar inicialização do servidor, negociação de transporte, roteamento remoto e outra camada de autenticação. Essas adições não são inerentemente ruins, mas cada uma cria uma superfície de falha distinta.

Teste desconexões, credenciais expiradas, inputs malformados, operações de longa duração parcialmente concluídas e atualizações do servidor. O agente precisa conseguir dizer se a falha ocorreu no host, na conexão do protocolo, no servidor ou na plataforma externa. Um resultado genérico de “falha na ferramenta” não é suficiente para trabalho de produção.

Em deployments longos, a interface precisa preservar a semântica do estado final. Seja uma operação de CLI com --wait ou uma ferramenta MCP com progresso, o agente não deve transformar uma confirmação em sucesso. A escolha entre agent skills vs MCP não elimina esse requisito.

Planeje a portabilidade sem sacrificar a fonte de verdade

O MCP pode melhorar a portabilidade entre clientes compatíveis porque o mesmo servidor anuncia ferramentas por meio de um protocolo compartilhado. Skills também podem ser portáteis quando vários agentes oferecem suporte ao mesmo diretório e às mesmas convenções de SKILL.md, como Claude Code e Codex fazem no modelo de instalação do Dockup.

A portabilidade só é útil quando a semântica permanece precisa. Uma ferramenta chamada deploy precisa definir se retorna quando a operação é enfileirada ou quando o sistema está saudável. Uma instrução de skill que diz “faça o deploy e verifique” deve apontar para um comando capaz de fornecer essa comprovação.

O design mais forte mantém a verdade do domínio próxima da camada executável e usa a camada superior para explicar a intenção. Na comparação entre agent skills vs MCP, nem um protocolo padronizado nem um arquivo de instruções bem escrito compensam uma operação de backend ambígua.

Coloque o workflow em produção

Use a arquitetura mínima que crie um limite confiável. No caso do Dockup, instale o skill empacotado e mantenha a CLI como fonte executável da verdade sobre o deployment.

npm install -g dockup-cli
dockup skill install

O primeiro comando instala a CLI. O segundo instala o skill correspondente do Dockup para Claude Code e Codex. Comece gratuitamente em app.dockup.ai.

FAQ

Agent skills e MCP são a mesma coisa?

Não. Um skill fornece principalmente instruções e conhecimento operacional. O MCP fornece um protocolo para expor ferramentas, recursos e prompts por meio de uma conexão cliente-servidor.

Um arquivo SKILL.md executa comandos por conta própria?

Não. Ele informa ao agente como usar capacidades subjacentes, como uma CLI, arquivos, APIs ou ferramentas MCP. A interface executável realiza a ação.

Quando um skill é melhor que MCP?

Um skill costuma ser a opção mais simples quando uma CLI local madura já fornece operações seguras e legíveis por máquina, e o que falta é orientação sobre o workflow.

Um agente pode usar um skill e MCP em conjunto?

Sim. Um skill pode descrever um workflow com várias etapas e sua política, enquanto um servidor MCP expõe as ferramentas e os recursos tipados usados nesse workflow.

Por que o Dockup distribui seu skill dentro do pacote da CLI?

Empacotar ambos em conjunto permite que dockup update atualize o executável e suas instruções de uma só vez, reduzindo o risco de o skill descrever uma versão diferente do comando.