Agent Skills

Todas as skills

mcp-builder (anthropics/skills)

Orienta a criação de servidores MCP em Python ou TypeScript que expõem serviços externos como ferramentas bem projetadas.

mcp-builder: eleva servidores MCP de 3.6 para 4.6/5 ao adicionar nomenclatura, anotações e async, mas um checklist de uma frase tira 4.9 com 68% dos tokens

SituacionalSeguro

Codex CLI · gpt-6-astra

21.6 / 30

Ganho sobre sem skill: +1.04 · Situacional · 18 execuções

Situacional: o total 21.6/30 está abaixo de 22. Para ser recomendado, é preciso total de 22/30, qualidade da saída de 3.5 e ganho de +1.0.

SOTA

Aprovado

Testado com Codex.

Cobre Codex, Claude Code

Codex CLI 0.166 (nível SOTA): 18 execuções avaliadas. Uma aprovação aqui também vale para o Claude Code pela nossa regra de níveis; ela não diz nada sobre o segundo nível.

Notas

Cada dimensão vai de 0 a 5, e as seis somam o total de 30. 5 é melhor em todas as dimensões. Custo 5 significa barato e rápido. Instalação 5 significa fácil.

Confiabilidade do acionamento
5.0
Ganho sobre sem skill
3.0
Qualidade da saída
4.6
Custo de tokens e tempo
3.0
Instalação e portabilidade
3.0
Segurança
3.0

Revisão de segurança

Seguro

Varredura estática: 8 CRÍTICO / 13 ALTO / 7 MÉDIO. Revisão manual: seguro para executar em sandbox sem rede (achados do scanner explicados; scripts incluídos nunca executados). Uma varredura limpa não prova que a skill é segura.

Instalar

npx skills@latest add anthropics/skills --skill mcp-builder

Fonte

Commit fixado: ca45fc496a3436251f191354091d557da31c15b5

Testado: 2026-11-02

O que testamos

  • Servidor MCP em Python para uma API de livraria — Escreva server.py: um servidor MCP em Python para uma API REST de inventário de livraria (URL base vinda do ambiente, bearer token vindo do ambiente). Ferramentas: buscar livros, obter um livro, atualizar o estoque de um livro, excluir um livro. Use o SDK oficial mcp para Python (FastMCP)…
  • Servidor MCP em TypeScript para uma API de clima — Escreva src/index.ts e package.json: um servidor MCP em TypeScript para uma API REST de clima (URL base e chave de API vindas do ambiente). Ferramentas: obter o clima atual de uma cidade, obter uma previsão de 5 dias, listar locais salvos, excluir um local salvo. Use o SDK oficial do MCP…
  • Consertar um servidor MCP escrito às pressas — server.py é um servidor MCP para a nossa API de armazém que funciona, mas foi escrito às pressas. Corrija-o para seguir boas práticas de servidor MCP. Edite server.py no próprio arquivo e mantenha-o falando com a mesma API. Não há rede nem instalação de pacotes aqui; apenas escreva…

Prós

  • Eleva a nota média de 3.57 para 4.61 em relação ao grupo sem skill (+1.04).
  • A skill foi acionada sem ser nomeada: o arquivo da skill foi lido em 6/6 execuções de tratamento.
  • Qualidade absoluta alta com a skill: 4.61 de 5.

Contras

  • Um prompt de uma frase tirou 4.88, contra 4.61 com a skill (-0.27).
  • Usa 1.51x os tokens do grupo sem skill.
  • n=2 por tarefa por braço; diferenças abaixo de cerca de 1 ponto são ruído.

Avaliação

Codex CLI 0.166 (gpt-6-astra, raciocínio baixo) em um PC Windows dedicado a testes, um projeto temporário novo e HOME/TMPDIR/caches temporários por execução, skill instalada (tratamento), ausente (controle) ou ausente com o requisito central da skill condensado em uma frase anexada ao prompt (grupo de uma frase), 2 execuções por grupo por tarefa, rede desligada, gravações em /tmp bloqueadas. Os prompts nunca mencionam a skill (exceto o texto indicado abaixo). Três tarefas: escrever um servidor MCP em Python para uma API REST de livraria, escrever um servidor MCP em TypeScript para uma API de clima e corrigir um server.py existente feito às pressas para seguir boas práticas. Nada precisa de rede (o agente não consegue instalar o SDK do MCP; ele só escreve código). O prompt do grupo com skill é o mesmo do controle.

Comparação entre os braços

BraçoNota média (0-5)Tokens por execução
Sem a skill3.5773k
Prompt de uma frase4.8875k
Com a skill4.61110k

Medido com Codex CLI em 18 execuções, com pontuação por verificações baseadas em regras e sem juiz LLM. Total 21.6 / 30, veredito Situacional.

Veredito: Situacional (21.6 / 30). Fonte: anthropics/skills, skills/mcp-builder, fixado no commit ca45fc4. Instalação: npx skills@latest add anthropics/skills --skill mcp-builder. Licença: Proprietária: anthropics/skills LICENSE.txt (código disponível; apenas para avaliação, não redistribuído).

O que é

A skill mcp-builder de anthropics/skills: um guia para construir servidores Model Context Protocol (pesquisar e planejar, implementar, revisar e testar, escrever avaliações). Ela inclui guias de linguagem para Python (FastMCP) e TypeScript, notas de boas práticas de MCP e dois scripts auxiliares para executar avaliações contra um servidor. Licença proprietária (código disponível).

Como testamos

Codex CLI 0.166 (gpt-6-astra, raciocínio baixo) em um PC de testes Windows dedicado, com um projeto temporário novo e HOME/TMPDIR/caches temporários a cada execução, skill instalada (com a skill), ausente (controle) ou ausente com o requisito central da skill comprimido em uma frase anexada ao prompt (grupo do prompt de uma frase), 2 execuções por grupo por tarefa, rede desativada, gravações em /tmp bloqueadas. Os prompts nunca mencionam a skill (exceto pelo texto indicado abaixo).

Três tarefas: escrever um servidor MCP em Python para uma API REST de livraria, escrever um servidor MCP em TypeScript para uma API de clima e corrigir um server.py existente e improvisado para seguir boas práticas. Nada precisa de rede (o agente não consegue instalar o SDK do MCP; ele apenas escreve código). O prompt do grupo com a skill é o mesmo do controle.

  1. Servidor MCP em Python para uma API de livraria — Escreva server.py: um servidor MCP em Python para uma API REST de inventário de livraria (URL base do ambiente, token bearer do ambiente). Ferramentas: buscar livros, obter um livro, atualizar o estoque de um livro, excluir um livro. Use o SDK oficial mcp para Python (FastMC…
  2. Servidor MCP em TypeScript para uma API de clima — Escreva src/index.ts e package.json: um servidor MCP em TypeScript para uma API REST de clima (URL base e chave de API do ambiente). Ferramentas: obter o clima atual de uma cidade, obter uma previsão de 5 dias, listar locais salvos, excluir um local salvo. Use o SDK oficial MC…
  3. Consertar um servidor MCP escrito às pressas — server.py é um servidor MCP para nossa API de armazém que funciona, mas foi escrito às pressas. Corrija-o para seguir boas práticas de servidor MCP. Edite server.py no lugar e mantenha-o falando com a mesma API. Não há rede nem instalação de pacotes aqui; apenas escreva…

A pontuação é programática (testes ocultos / recuperação de problemas plantados / verificações de restrições / renderização+OCR quando relevante), 0–5 por execução. Nenhum juiz LLM decidiu qualquer pontuação.

Resultados

A frase única dada ao terceiro grupo: "Projete o servidor MCP como um especialista: nomes de ferramentas consistentes com prefixo de serviço e orientados à ação (por exemplo, bookstore_search_books), esquemas de entrada tipados (Pydantic ou Zod) com campos descritos, anotações (readOnlyHint, destructiveHint, idempotentHint), resultados paginados e com limite de tamanho, mensagens de erro acionáveis, segredos apenas de variáveis de ambiente, I/O assíncrono e nada impresso em stdout no transporte stdio."

TarefaPontuação do controlePrompt de uma fraseCom a skillTokens do controleTokens do prompt de uma fraseTokens com a skillSkill lida
t1-python1.434.644.260k64k97k2/2
t2-typescript4.295.04.6460k55k100k2/2
t3-fix5.05.05.097k106k133k2/2

Pontuação média: 3.57 sem a skill vs 4.61 com a skill (delta +1.04). Tokens por execução: 73k vs 110k (1.51x); tempo 80s vs 89s. Grupo prompt de uma frase: 4.88 (ganho da skill sobre o prompt de uma frase: -0.27; ganho do próprio prompt de uma frase sobre nenhuma skill: +1.31); tokens do prompt de uma frase: 75k por execução, então a skill custa 1.47x o prompt de uma frase.

O que aconteceu

  • Onde importa, a skill ajuda: nos dois servidores do zero, o controle perdeu o básico (nomes de ferramentas com prefixo de serviço compartilhado em 2/4 execuções, anotações de ferramentas como readOnlyHint em 2/2 execuções Python, ferramentas assíncronas em 2/2 execuções Python, mensagens de erro acionáveis em 2/2 execuções Python). Pontuação média 3.57 no controle, 4.61 com a skill.
  • O grupo de uma frase saiu melhor que a skill: 4.88, com uma verificação perdida em 18 execuções, enquanto o grupo com a skill perdeu 5. A frase lista as mesmas propriedades que as verificações procuram, então é um limite superior para um prompt curto, mas custa 75k tokens por execução, contra 110k da skill e 73k do controle.
  • Um defeito real no grupo com a skill: as duas execuções TypeScript com a skill produziram um createServer() para o novo pacote @modelcontextprotocol/server, mas nunca iniciaram um transporte (sem stdio nem Streamable HTTP), então o arquivo do servidor não pode ser iniciado como está; as execuções de controle e do prompt de uma frase incluíram um transporte.
  • Na tarefa de correção, os três grupos pontuaram igual (todas as 9/9 verificações nas seis execuções): diante de um servidor existente, o Codex sem skill já aplicava as práticas.
  • A skill é pesada de carregar: SKILL.md mais guias de referência; as execuções com a skill deixaram cerca de 12 arquivos da skill na pasta .agents do projeto e leram os guias, e é aí que vão os 1.5x tokens. Seus scripts auxiliares (harness de avaliação) não foram executados no sandbox offline.

Pontuações por dimensão

DimensãoPontuaçãoPor quê
1_output_quality4.61

Pontuação média de 4.61/5 com a skill (verificações programáticas, veja a tabela por tarefa).

2_lift_vs_no_skill3.04

+1.04 pontos vs 3.57 sem a skill (n=2 por tarefa; abaixo de ~1 ponto é ruído).

3_trigger5.0Arquivo da skill lido em 6/6 execuções com a skill.
4_instructions_portability3

Conjunto de referência grande, dividido em guias por linguagem; os scripts auxiliares precisam de pacotes Python e de um servidor em execução.

5_efficiency31.51x tokens (110k vs 73k por execução) e 1.11x tempo (89s vs 80s).
6_safety_hygiene3

Scanner sinaliza 8 CRITICAL / 13 HIGH, todos lidos em contexto: código de servidor de exemplo e passagem de variáveis de ambiente em scripts auxiliares; licença proprietária.

Limites deste teste

  • Verificações baseadas em regras sobre o texto do código; nenhum dos servidores gerados foi realmente iniciado ou conectado a um cliente.
  • Sem rede: o agente não pôde instalar nem importar o SDK do MCP, então detalhes da API (por exemplo, o novo pacote TypeScript v2) não foram validados.
  • A etapa de avaliação da skill (geração de perguntas e execução delas contra o servidor) não foi exercitada.
  • n = 2 por grupo por tarefa: diferenças abaixo de ~1 ponto são ruído.
  • A pontuação baseada em regras mede o que as verificações conseguem ver; ela não julga bom gosto nem se o resultado é o melhor possível.

Segurança

Consulte security.md. Varredura: 8 CRITICAL / 13 HIGH / 7 MEDIUM. Veredito: seguro para executar (sandbox sem rede). Uma varredura limpa não prova que uma skill é segura.

Conclusão

Para um servidor do zero, a skill claramente supera um agente sem orientação em nomenclatura, anotações, assincronismo e tratamento de erros, com 1.5x tokens. Uma frase de checklist obteve as mesmas propriedades com menos tokens e sem o defeito do transporte ausente, então instale-a pelos guias de referência e pela consistência, não por um salto de qualidade sobre um bom prompt.

Transcrição

Log de execuções: mcp-builder (Codex CLI, network off, per-run temp HOME/TMPDIR, one row per graded run.)
Colunas: tarefa, grupo-execução, nota (0-5), tokens, segundos, verificações aprovadas, arquivos da skill abertos pelo agente.

t1-python control-1: nota 1.79, tokens 51610, s 53.2, verificações 4/9, nada aberto
t1-python control-2: nota 1.07, tokens 69259, s 98.6, verificações 3/9, nada aberto
t1-python oneliner-1: nota 5.0, tokens 74072, s 101.3, verificações 9/9, nada aberto
t1-python oneliner-2: nota 4.29, tokens 54692, s 126.2, verificações 8/9, nada aberto
t1-python treatment-1: nota 3.39, tokens 101809, s 72.0, verificações 6/9, abriu mcp-builder
t1-python treatment-2: nota 5.0, tokens 93275, s 66.9, verificações 9/9, abriu mcp-builder
t2-typescript control-1: nota 4.29, tokens 52126, s 59.1, verificações 8/9, nada aberto
t2-typescript control-2: nota 4.29, tokens 69042, s 61.5, verificações 8/9, nada aberto
t2-typescript oneliner-1: nota 5.0, tokens 55412, s 104.3, verificações 9/9, nada aberto

18 execuções, 3 artefatos

Resultado de exemplo

SOTA · With the skill: server.py (t1-python, run 1, Codex)

"""Bookstore MCP server (Python 3.10+, official mcp SDK, httpx, Pydantic 2). Required environment variables: BOOKSTORE_BASE_URL: API root, e.g. https://inventory.example.com/api/v1 BOOKSTORE_API_TOKEN: bearer token (without the 'Bearer ' prefix) Assumed REST contract (adjust paths/fields here to match your API): GET /books?q=...&limit=...&offset=... -> JSON search results GET /books/{book_id} -> JSON book PATCH /books/{book_id}/stock body: {"stock": nonnegative integer} DELETE /books/{book_id} Updates and deletes may return JSON or an empty success response. Search pagination and response shape are supplied by the upstream API. Run with `python server.py` in an environment with the dependencies installed. Transport is stdio; stdout is reserved for MCP protocol messages. """ import os from contextlib import asynccontextmanager from dataclasses import dataclass from typing import Annotated, Any, AsyncIterator from urllib.parse import quote, urlsplit import httpx from mcp.server.fastmcp import Context, FastMCP from mcp.server.fastmcp.exceptions import ToolError from pydantic import Field @dataclass class AppState: client: httpx.AsyncClient @asynccontextmanager async def lifespan(server: FastMCP) -> AsyncIterator[AppState]: base_url = os.environ.get("BOOKSTORE_BASE_URL", "").strip() token = os.environ.get("BOOKSTORE_API_TOKEN", "").strip() if not base_url or not token: raise RuntimeError("Set BOOKSTORE_BASE_URL and BOOKSTORE_API_TOKEN.") try: parsed = urlsplit(base_url) valid = ( parsed.scheme in {"http", "https"} and bool(parsed.hostname) and parsed.username is None and parsed.password is None and not parsed.query and not parsed.fragment ) parsed.port # Validate a supplied port without exposing the URL. except ValueError: valid = False if not valid: raise RuntimeError("BOOKSTORE_BASE_URL must be an HTTP(S) API root without credentials, query, or fragment.") if any(ord(char) < 33 or ord(char) > 126 for char in token): raise RuntimeError("BOOKSTORE_API_TOKEN must contain printable ASCII without whitespace.") async with httpx.AsyncClient( base_url=base_url.rstrip("/") + "/", headers={"Authorization": f"Bearer {token}", "Accept": "application/json"}, timeout=httpx.Timeout(30.0, connect=10.0), follow_redirects=False, trust_env=False, ) as client: yield AppState(client=client) mcp = FastMCP("bookstore_mcp", lifespan=lifespan) BookId = Annotated[str, Field(min_length=1, max_length=256, description="Book identifier, e.g. 'book-123'.")] def book_path(book_id: str) -> str: if not book_id.strip() or book_id in {".", ".."}: raise ToolError("Provide a nonblank book identifier other than '.' or '..'.") return "books/" + quote(book_id, safe="") async def api_request( ctx: Context, method: str, path: str, *, params: dict[str, Any] | None = None, payload: dict[str, Any] | None = None, ) -> dict[str, Any]: state: AppState = ctx.r [... excerpt: first 3200 of 7129 characters]

Ver o Pro