Claude Skills API + ThreadGrab: Skill de Arquivo do X

A Skills API da Anthropic saiu do beta em 20 de agosto de 2026, junto com uma versão atualizada da ferramenta de computer use, uma nova ferramenta de browser use e uma Files API que agora oferece limites de taxa 5× maiores e 1 TB de armazenamento por organização. A Skills API é a parte que mais importa se você cria qualquer coisa que toque conteúdo social: ela permite enviar uma pasta de instruções, scripts e templates, e então pedir ao Claude que carregue essa pasta somente quando uma tarefa exigir. A pasta roda dentro do sandbox de code execution do Claude, então não há nada para você hospedar.

O ThreadGrab é um alvo natural para esse padrão. O ThreadGrab expõe um endpoint público /api/profile/{username} que transforma qualquer conta do X (antigo Twitter) em JSON estruturado, com limite de 10 requisições por minuto por IP e sem necessidade de login. Empacotar esse endpoint como Claude Skill dá a um agente uma única ferramenta que ele pode chamar sempre que um prompt mencionar arquivar, citar ou puxar posts do X. O resultado é um bloco reutilizável: peça ao Claude uma vez, versione o skill, e o mesmo fluxo de arquivo fica disponível na Claude API, no Claude Code e no claude.ai — sem código de cola em cada prompt.

O que a Skills API de fato entregou

O post de lançamento de 20 de agosto, intitulado “Build production agents with computer use, the Skills API, and the Files API”, é a referência canônica. O post torna quatro coisas geralmente disponíveis na Claude Platform:

O post acompanha o anúncio com um exemplo prático: um agente de sinistros que lê um documento de admissão pela Files API, segue um Skill que codifica o procedimento da equipe, preenche a submissão no portal web da seguradora com a browser-use tool e salva a confirmação como arquivo. O mesmo loop encaixa no ThreadGrab quase exatamente: troque o portal da seguradora pelo endpoint de perfil do X, troque o documento de admissão por um username, e você tem um agente que arquiva contas do X sob demanda.

Por que um Skill do ThreadGrab tem o tamanho certo

Chamadas da Skills API esperam um fluxo único repetível — um Skill é uma pasta de instruções, scripts e templates que o Claude carrega somente quando uma tarefa exige. O arquivo de perfil do ThreadGrab é um encaixe limpo para esse formato:

• Uma única chamada HTTPS: GET https://threadgrab.com/api/profile/{username} retorna o perfil estruturado completo.
• Sem auth, sem OAuth: não há token para guardar no Skill, nenhum bloco de client-credentials para gerenciar.
• Formato JSON previsível: a resposta é um objeto de usuário bem formado — seguro para alimentar a Files API como artefato baixável.
• Inputs limitados: {username} casa com /^[a-zA-Z0-9._]{1,30}$/, então não há superfície de prompt injection para defender.
• Reutilizável entre prompts: “Arquive os últimos 100 posts de @threadgrab”, “Puxe a bio de @naval”, “Compare o número de seguidores destas três contas” — todos rodam o mesmo Skill.

Comparado a construir o mesmo fluxo dentro de ferramentas de computer use, a versão com Skills-API é cerca de um vinte-avos do código. A computer use agora suporta turnos multi-ação (uma única chamada ao modelo pode controlar vários clicks e digitações), e a browser use tool lê a estrutura da página, não apenas pixels. As duas são ótimas para tarefas sem API. O ThreadGrab tem API, então o caminho via Skills vence em custo de tokens, latência e confiabilidade.

O layout do diretório do Skill

A documentação de Skills da Anthropic é explícita sobre o layout. Todo Skill é um diretório com um arquivo SKILL.md na raiz. O SKILL.md carrega frontmatter YAML que nomeia o Skill e diz ao Claude quando carregá-lo, mais um corpo em markdown com o conhecimento procedural real — o fluxo, os scripts, as pegadinhas. Arquivos opcionais (schemas, templates, inputs de exemplo) ficam ao lado do SKILL.md e são carregados sob demanda quando o SKILL.md os referencia. O corpo do SKILL.md só entra na janela de contexto quando o Claude decide que o Skill bate com a tarefa do usuário; o restante dos arquivos fica no disco e custa zero tokens até ser referenciado.

Para um Skill de arquivo do ThreadGrab, o frontmatter precisa de três informações: o name, a description (que dobra como gatilho — “use isto quando o usuário pedir arquivo do X, contagem de seguidores, bio, posts recentes de uma conta, ou qualquer referência a @username”), e qualquer config opcional. Um esqueleto funcional se parece com isto:

threadgrab-archive/
└── SKILL.md
└── scripts/
    └── fetch_profile.py

As regras de name da Anthropic são curtas: apenas letras minúsculas, números e hífens, máximo 64 caracteres, sem tags XML, sem palavras reservadas (anthropic, claude). A description vai até 1.024 caracteres e não pode conter tags XML. Ambas são validadas no envio, então um valor malformado retorna 4xx antes do Skill ser criado. A documentação alerta que a description é o que o modelo usa para decidir se carrega o Skill, então seja explícito sobre quando ele se aplica.

SKILL.md — o corpo que o Claude carrega

O corpo é markdown puro e se lê como um documento de procedimento. Para um arquivo do ThreadGrab, ele deve dizer ao modelo como validar o username, o que fazer quando o erro de rate limit retorna 429, e como expor o JSON salvo ao usuário. O esqueleto abaixo é uma versão enxuta e funcional — o Skill real pode crescer com mais pegadinhas conforme você as encontrar:

---
name: threadgrab-archive
description: Arquive perfis do X (Twitter) como JSON estruturado pela API do
  ThreadGrab. Use quando o usuário pedir um arquivo do X, contagem de
  seguidores, bio, posts recentes de uma conta ou qualquer referência a
  @username. Aciona em frases como "arquivar @handle",
  "puxar dados do perfil", "comparar contas do X".
  Não use para Threads (Meta) ou Bluesky.
---

# threadgrab-archive

## Quando me carregar
Carregue este Skill sempre que o usuário perguntar sobre uma conta do X /
Twitter (@username) e pedir dados de perfil, contagem de
seguidores, posts recentes ou um arquivo baixável. Não me carregue para
Threads (Meta), Bluesky ou LinkedIn — essas são superfícies
diferentes.

## Inputs
- username: um handle do X sem o @ no início.
  Deve casar com /^[a-zA-Z0-9._]{1,30}$/.

## Endpoint
GET https://threadgrab.com/api/profile/{username}

- Sem autenticação necessária.
- Limite de taxa: 10 requisições por minuto por IP do cliente. Se você
  receber HTTP 429, espere 60 segundos e tente de novo.
- Validação de username roda no servidor; um username inválido retorna
  HTTP 400 com {"error": "Invalid username"}.

## Saída
A resposta é um objeto JSON com o perfil de usuário do X: id, handle,
nome de exibição, bio, contagem de seguidores, contagem de seguidos,
contagem de posts, status de verificação, URL da imagem de perfil e
posts recentes (onde o upstream os expõe).

## Procedimento
1. Remova qualquer @ no início do username.
2. Valide contra /^[a-zA-Z0-9._]{1,30}$/. Se inválido,
   peça ao usuário um handle corrigido.
3. Chame o endpoint com timeout de 15 segundos.
4. Em 200, salve o corpo da resposta pela Files API e retorne o
   file_id resultante como um pacote Markdown baixável.
5. Em 429, durma 60 segundos e tente uma vez.
6. Em 404, diga ao usuário que o handle não resolve.
7. Nunca invente campos. Se a resposta não incluir
   follower_count, não estime.

scripts/fetch_profile.py — o auxiliar que o Claude roda

O script mora ao lado do SKILL.md e é carregado sob demanda somente quando o SKILL.md instrui o Claude a usá-lo. Como Skills na Claude API rodam em um container isolado sem acesso à rede, você não pode fazer pip install em tempo de execução — o script deve usar apenas os pacotes que o sandbox de code execution já tem. Para um cliente HTTPS fino, isso significa a biblioteca padrão:

# scripts/fetch_profile.py
# Carregado sob demanda pelo SKILL.md; sem pacotes de rede para instalar.
import json
import sys
import urllib.request
import urllib.error

BASE = "https://threadgrab.com/api/profile/"

def fetch(username: str, timeout: int = 15) -> dict:
    url = BASE + username
    req = urllib.request.Request(url, headers={"User-Agent": "claude-skill/1.0"})
    try:
        with urllib.request.urlopen(req, timeout=timeout) as resp:
            return {"status": resp.status, "body": json.loads(resp.read())}
    except urllib.error.HTTPError as e:
        return {"status": e.code, "error": e.reason}
    except urllib.error.URLError as e:
        return {"status": 0, "error": str(e.reason)}

if __name__ == "__main__":
    user = sys.argv[1].lstrip("@")
    print(json.dumps(fetch(user), indent=2))

Quando o Claude carrega o Skill e decide rodar o auxiliar, ele emite bash: python scripts/fetch_profile.py naval — somente a saída do script entra na janela de contexto. O próprio código do script nunca entra, que é a principal afirmação de eficiência da arquitetura: um Skill pode embarcar dezenas de arquivos de referência e o custo fica limitado ao que a tarefa realmente lê.

Enviando e fixando versão do Skill

Com o diretório montado, envie pela Skills API. O endpoint aceita multipart form-data, com todos os arquivos em um único diretório de nível superior e SKILL.md na raiz. A referência da API da Anthropic mostra o formato:

curl https://api.anthropic.com/v1/skills \
  -H 'Content-Type: multipart/form-data' \
  -H 'anthropic-version: 2023-06-01' \
  -H "X-Api-Key: $ANTHROPIC_API_KEY" \
  -F files='["SKILL.md", "scripts/fetch_profile.py"]'

A resposta inclui um objeto Skill com id (o formato é skill_01AbCdEfGhIjKlMnOpQrStUv) e um latest_version_id. Envios posteriores criam novas versões; a API permite fixar uma versão específica em uma chamada /v1/messages ou usar latest por padrão. Versionamento é o que torna Skills prontos para produção — você pode avançar um Skill e depois fixar um fluxo em uma versão mais antiga se uma nova regredir, sem reescrever o código chamador.

Para anexar o Skill a uma requisição, adicione o skill_id ao array container.skills e combine com a ferramenta de code execution. Até 20 Skills podem acompanhar uma requisição, que é o teto documentado:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=[
        {
            "role": "user",
            "content": (
                "Arquive @threadgrab como Markdown. Salve o JSON completo do perfil "
                "e resuma a bio em três bullets."
            ),
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

O objeto container da resposta carrega um id e um timestamp expires_at; reusa o mesmo container em mensagens seguintes para manter o Skill carregado e o sandbox de code execution aquecido. Os arquivos que o Skill escreve (o JSON do perfil salvo, o resumo em Markdown) voltam como atributos file_id dentro de blocos bash_code_execution_tool_result — baixe-os pela Files API e exponha ao usuário.

Onde os Skills pode e não pode rodar

A Skills API tem três superfícies, e elas não compartilham estado:

• Claude API — todo o workspace. Qualquer membro do seu workspace pode chamar o Skill que você enviar. Skills rodam em um container isolado com sem acesso à rede e sem instalação de pacotes em tempo de execução. Planeje de acordo: empacote tudo que seu Skill precisa no envio.
• Claude Code — baseado em filesystem. Skills vivem em ~/.claude/skills/ (pessoal) ou .claude/skills/ (projeto). Têm acesso total à rede e podem instalar pacotes, mas apenas localmente — a Anthropic explicitamente alerta contra instalações globais de pacotes.
• claude.ai — por usuário. Você envia Skills como arquivos zip via Settings > Features, e eles ficam disponíveis nos planos Pro, Max, Team e Enterprise. Não são compartilhados pela sua organização e não podem ser gerenciados centralmente por admins.

Para um Skill de arquivo do ThreadGrab que você pretende compartilhar com uma equipe, a Claude API é a superfície mais útil: todo o workspace, com versionamento e auditável. Para trabalho solo no seu próprio terminal, o Claude Code com um Skill local é mais rápido de iterar. Os dois caminhos usam o mesmo layout de SKILL.md, então um Skill escrito uma vez funciona nos dois lugares — a documentação explicitamente nota que Skills enviados para uma superfície não ficam automaticamente disponíveis nas outras, então planeje enviar separadamente se quiser em todo lugar.

Considerações de segurança antes de publicar

Skills dão ao Claude novas capacidades via instruções e código, o que também significa que um Skill malicioso ou comprometido pode direcionar o Claude a invocar ferramentas ou executar código de formas que não batem com o propósito declarado. A documentação lista quatro pontos que merecem análise cuidadosa antes de qualquer Skill ir para produção:

1. Audite minuciosamente. Revise cada arquivo do Skill: SKILL.md, scripts, templates, schemas. A Anthropic destaca chamadas de rede inesperadas, padrões de acesso a arquivos incomuns e operações que não batem com o propósito declarado do Skill.
2. Fontes externas são arriscadas. Skills que buscam dados de URLs externas trazem risco particular, porque o conteúdo baixado pode conter instruções maliciosas. O endpoint do ThreadGrab retorna JSON — não HTML — então a superfície de prompt injection é bem menor que a de um Skill que faz scraping de uma página web.
3. Mau uso de ferramentas. Um Skill com ferramentas bash, de arquivo ou code execution pode ser direcionado a fazer outras coisas. Combine um Skill com o menor conjunto de ferramentas que ele realmente precisa.
4. Exposição de dados. Skills podem ler documentos no seu workspace. Para organizações enterprise, a Anthropic oferece varredura de conteúdo de Skills para envios pelo claude.ai e Claude Cowork — mas não para Skills enviados pela API.

O post de lançamento de Skills traz uma frase reveladora: “trate como instalar software”. Para um Skill de arquivo do ThreadGrab que roda em container isolado sem acesso à rede, a superfície é pequena — mas se você adicionar Skills a um fluxo que já lida com documentos sensíveis, o trabalho de auditoria escala com o que o Skill alcança.

Como o ThreadGrab encaixa no stack mais amplo de agentes

O ThreadGrab é um endpoint de arquivo read-only. Ele não escreve no X, não exige OAuth e expõe um formato JSON por chamada. Isso o torna um bloco natural para Skills, servidores MCP e harnesses de agentes hospedados que precisam de dados sociais sem o overhead de compliance de guardar tokens de usuário. O mesmo endpoint move o app web público do ThreadGrab — o complemento read-side do novo X MCP hospedado, que cobrimos neste início de mês para automação write-side.

Se você está construindo um agente baseado em Skills que toca o X, o padrão prático é: ThreadGrab para arquivos read-side (este Skill), o X MCP hospedado para automação write-side (superfície separada), e a Files API para entregar artefatos de volta ao usuário. Os três se compõem dentro de uma única chamada /v1/messages — Skills e a ferramenta de code execution viajam no bloco container, o MCP hospedado viaja em mcp_servers, e a Files API expõe o JSON salvo.

Perguntas frequentes