Samin12/skills

treg — o catálogo de ferramentas para seu agente

Peça pela tarefa, não pela ferramenta. Quando um trabalho precisar de dados externos ou ao vivo — backlinks, volume de palavras-chave, um perfil no TikTok, um e-mail profissional, criativo de anúncio concorrente — pesquise no catálogo, leia o preço e faça a chamada.

Dois tipos de ferramenta respondem ao mesmo token, pelo mesmo proxy, que injeta a credencial no lado do servidor para que você nunca a armazene:

• O catálogo — endpoints externos selecionados que o treg pode chamar para você.
• Suas próprias ferramentas — o que um colega de equipe registrou e compartilhou com esta organização: contas de API, conexões OAuth, skills. Nota: uma conexão X (Twitter) feita pelo aplicativo do treg é cobrada por chamada (o X cobra o dono do aplicativo por uso); a resposta informa o preço. O próprio aplicativo de desenvolvimento X da equipe não é cobrado.

A mecânica:

• Endpoint: https://treg.to · CLI: treg · a CLI é um cliente leve sobre a API.
• Autenticação: toda chamada envia X-Treg-Token: <seu token>.
• Uma ferramenta = uma URL base upstream + vínculos de credencial. Um skill/pacote = uma receita (SKILL.md) + seus segredos + sua(s) ferramenta(s). O proxy retransmite, nunca modela o upstream.

Primeiro: instale + faça login

curl -fsSL https://treg.to/install.sh | sh     # instala a CLI e a aponta para cá
treg login                            # login pelo navegador (GitHub / Google / código de e-mail) — o primeiro login registra você
treg login --email [email protected]    # alternativa apenas no terminal (código de 6 dígitos enviado por e-mail)
treg login --token <token-por-organizacao>    # não interativo (agentes/CI)

Tudo roda na sua organização ativa (o primeiro login cria uma pessoal). Convites de equipe chegam por e-mail — veja-os com treg invites, aceite com treg accept (ou treg org join <code>). Troque de equipe: treg org switch <slug>.

Já conectado via MCP? Então você tem as ferramentas, não a CLI

Se você acessou o treg através de https://treg.to/mcp/ — ChatGPT, Claude Code, Cursor — as etapas da CLI acima não se aplicam a você. Você tem cinco ferramentas: catalog_search, catalog_get, call, balance, my_tools. Tudo neste documento se mapeia para elas:

• "pesquisar no catálogo" → catalog_search, depois catalog_get para o preço e parâmetros exatos
• "chamar" → call com o id do endpoint, ou <nome-da-ferramenta>/<caminho> para uma das ferramentas da própria equipe
• "verificar o saldo" → balance

As regras abaixo são as mesmas de qualquer forma. A que mais importa — digam o preço antes de gastá-lo — importa mais aqui, porque call retorna cost_usd e você pode relatar quanto uma chamada realmente custou em vez de estimar.

Uma call em um endpoint do catálogo gasta o saldo da equipe. Uma call em uma das ferramentas da própria equipe não gasta nada: aquela chave pertence a eles.

Tarefa — o catálogo: o que o treg pode fazer por você (comece aqui)

~2.800 endpoints catalogados em ~56 provedores, agrupados pelo que FAZEM: rastreamento de palavras-chave e rank, backlinks e autoridade, visibilidade em IA, tendências e descoberta, publicação nas próprias contas sociais da equipe, enriquecimento de pessoas e empresas, gerenciamento e criativo de anúncios, medição.

treg catalog search "postagens de subreddit"            # encontre endpoints pelo que fazem
treg catalog get scrapecreators.reddit.subreddit.posts   # parâmetros, PREÇO, como você seria atendido
treg call scrapecreators.reddit.subreddit.posts --query subreddit=noticias
treg balance                                     # o saldo pré-pago + cobranças recentes
treg catalog request "<o que você precisa>"           # pesquisou e não encontrou? registre — orienta o que será adicionado em seguida

Notas:

• O preço de cada endpoint está em treg catalog get, antes de você chamá-lo.
• HTTP 402 = saldo insuficiente, com um corpo acionável por máquina (balance_micro, estimated_cost_micro, topup_url). Recuperação: treg balance → recarregue no painel (Equipe → Faturamento) → ou armazene a própria chave da organização para aquele provedor (chaves próprias nunca são cobradas do saldo — elas têm prioridade automaticamente).
• Uma ferramenta ou segredo da organização para o provedor sempre vence a chave do treg, automaticamente — o catálogo é o fallback, não um substituto para chaves que a equipe já possui.
• Escolhendo entre provedores de uma mesma capacidade — o procedimento. treg catalog get <id> lista cada provedor que atende ao mesmo trabalho com CUSTO, FUNCIONA (taxa de sucesso que o treg observou, com o tamanho da amostra), VELOCIDADE (mediana) e ÚLTIMO OK. Siga esta ordem:
  1. Corresponda às entradas que você REALMENTE TEM. Um endpoint que quer um profile_url não substitui quando você tem um nome e um domínio, qualquer que seja o custo. Esta regra supera o preço todas as vezes.
  2. Depois confiabilidade: um FUNCIONA alto com uma amostra real vence um número redondo com uma amostra pequena — 99% (121) é evidência mais forte do que 100% (8).
  3. Depois preço. As variações dentro de uma capacidade chegam a 200×, então geralmente é aqui que está o dinheiro.
  4. ÚLTIMO OK desempata. Uma idade simples significa que uma chamada real retornou; uma ✓ idade é o selo de verificação do próprio catálogo, não tráfego ao vivo; — significa que ninguém verificou e ninguém chamou — prefira quase qualquer outra coisa.
  • Se uma chamada falhar com 429 / 5xx / timeout, tente o próximo provedor. Você conhece seus parâmetros, então pode construir sua requisição. Diga para qual você mudou.
  • Nunca repita um 4xx em outro lugar. Um 4xx geralmente são seus parâmetros; corrigi-los é a solução, e repetir queima o dinheiro da equipe em N provedores para um único erro.
  • O treg não escolhe ou faz failover por você. Isso é deliberado: só você sabe quais entradas possui, e o treg retransmite em vez de reescrever sua requisição.
• Um endpoint sem preço publicado é recusado em vez de servido gratuitamente; conecte sua própria chave.

Repetindo uma chamada sem pagar duas vezes

Se uma chamada expirar ou você nunca vir sua resposta, repita-a com o mesmo idempotency_key (via MCP) ou cabeçalho Idempotency-Key (via HTTP). O treg retorna a resposta armazenada, não chama o provedor novamente e não cobra nada. O resultado diz replayed: true.

Somente para uma repetição genuína. Perguntar a mesma coisa novamente para ver o que mudou é TRABALHO NOVO: use uma nova chave ou nenhuma, ou você receberá a resposta antiga. Reutilizar a mesma chave para uma requisição diferente é recusado.

A maioria das repetições não precisa disso — uma chamada com falha nunca foi cobrada.

Tarefa — suas próprias ferramentas: chame uma que a equipe registrou

Comece pelo que está registrado, depois use a API exatamente como sua própria documentação diz. Sem vocabulário do treg, sem parâmetros especiais:

treg tool ls                                  # o que esta equipe registrou
treg call intercom conversations?per_page=5   # <nome-da-ferramenta> + o caminho upstream

Via HTTP isso é GET https://treg.to/call/<nome-da-ferramenta>/<caminho> com X-Treg-Token: <seu token>. O treg procura a ferramenta nomeada, injeta a credencial daquela equipe no lado do servidor, e retransmite tudo fielmente (método, parâmetros de consulta, seus cabeçalhos, corpo). Seu X-Treg-Token é removido antes do upstream vê-lo. Funciona para GET/POST/PUT/PATCH/DELETE.

Apenas ferramentas que esta organização registrou são resolvidas. Descubra-as com treg tool ls · treg skill ls.

Tarefa — compartilhe suas chaves e skills para que os agentes dos colegas possam usá-los

Em massa (o caminho rápido): execute no diretório que o humano nomear. Ele lista as chaves de provedor que reconhece naquele .env e os skills em seus subdiretórios, e registra apenas aqueles que forem marcados:

treg upload                       # ambos os lados do diretório atual; `treg upload env|skills --dir <d>` para restringir

Padrão: envolva novas chaves em um skill. Ao registrar uma nova chave/endpoint/CLI, emparelhe-a com um skill para que credencial, ferramenta e receita cheguem juntos (e ganhe uma página compartilhável). Se nenhum skill existir, crie um básico — um SKILL.md adequado (frontmatter importa: agentes descobrem skills por ele) + uma chamada de exemplo:

mkdir -p ./posthog && cat > ./posthog/SKILL.md <<'MD'
---
name: posthog
description: Consulte a API de análise do PostHog através do treg — a chave é injetada no lado do servidor. Use para eventos, insights e consultas de projeto.
---
Chame: `treg call posthog api/projects/@current` (upstream: https://us.posthog.com)
MD
treg skill init --dir ./posthog   # cria rascunho treg.json: base_url do catálogo (nome da pasta) ou URLs no SKILL.md; revise-o + adicione a chave
treg skill add --dir ./posthog    # registra receita + segredo + ferramenta atomicamente

Nunca orfane um segredo: uma chave armazenada que nada vincula é peso morto — se você usar secret add diretamente, vincule-a a uma ferramenta (endpoint/CLI) no mesmo momento. Endpoint simples, sem receita (apenas quando um skill não adiciona nada):

treg secret add posthog-key --value "$POSTHOG_API_KEY"          # ou --file ./.secret/token.json
treg tool add posthog --base-url https://us.posthog.com --secret posthog-key
# API com chave de consulta em vez de cabeçalho bearer:
treg tool add serpapi --base-url https://serpapi.com --secret <nome-ou-id> \
  --auth-in query --auth-name api_key --auth-format '{secret}'

Um skill completo (receita + segredos + ferramenta, possivelmente multi-credencial):

treg skill scaffold ~/.claude/skills/google-ads --out gads.json
#   -> percorre o diretório: captura SKILL.md como a receita + cada .secret/* como um segredo.
#   -> VOCÊ então edita gads.json: define base_url, e completa cada vínculo (local/nome/formato).
#      ex.: google-ads precisa de DOIS vínculos em uma requisição:
#        Authorization: Bearer {access_token}  (injetor: oauth)
#        developer-token: {secret}             (injetor: env)
treg skill push gads.json                                        # registra o pacote atomicamente

Compartilhe dentro da organização: dê a um colega o endpoint + nome da ferramenta e o agente deles pode chamá-lo sem receber a credencial — você concedeu o acesso, o treg injeta o segredo, e a chamada é registrada contra o token deles.

Formatos de autenticação (por vinculação injector, = o kind do segredo): env (string simples) · secret_file (arquivo JSON de token, extraia secret_field) · oauth (token JSON, renovado automaticamente) · cli_auth (um token que o humano copiou de uma CLI na qual já está logado, e forneceu ao treg pessoalmente). Vários vínculos se aplicam a cada requisição.

OAuth, dois modos (o treg mantém atualizado): se o segredo OAuth carregar refresh_token + client_id + client_secret, o treg o renova automaticamente antes de expirar (você nunca reenvia). Se for apenas um token simples, é modo manual, o treg o injeta como está e você reenvia quando expirar. Mesmo armazenamento; uma credencial pode passar de manual para automático sem migração.

Obtendo o primeiro token OAuth, duas maneiras (sua escolha):

• Manual: faça seu próprio OAuth localmente, depois treg secret add gsc --file token.json --kind oauth.
• Conexão hospedada: treg oauth connect gsc --client-secret client_secret.json --scopes <escopo> → imprime uma URL de consentimento; você aprova no navegador; o treg captura o token diretamente. Configuração única: adicione https://treg.to/oauth/callback às URIs de redirecionamento do seu aplicativo OAuth.

Tarefa — gerencie a equipe + monitore

treg tool ls / secret ls / skill ls / calls          # inventário + log de auditoria — escopo da organização ativa
treg tool rm <id> / secret rm <id> / skill rm <id>   # secret rm é bloqueado enquanto uma ferramenta o vincular
treg health            # status de cada credencial nesta organização (ok | invalid | unknown)
treg health --run      # verifique novamente agora: renove tokens OAuth, teste cada ferramenta, alerte proprietários

Equipes / organizações (owner > admin > member > viewer; um member gerencia apenas o que criou):

treg org create "Equipe A"                       # você se torna owner (ativo automaticamente)
treg org invite [email protected] --role member  # admin+; envia o convite por e-mail (um código de uso único é o fallback)
treg org members                               # admin+; quem está na organização ativa
treg org ls / treg org switch <slug>           # suas organizações / trocar a ativa

Dê a um agente sua própria identidade (admin+). Um agente não precisa pegar emprestado o token do humano — crie um para ele, e cada chamada que fizer será limitada, escopada e registrada como ele mesmo:

treg org agent-new ci-bot                        # imprime o token UMA VEZ (execute novamente para rotacionar)
treg org agent-new ci-bot --tools stripe,gh --cap 500   # apenas estas ferramentas, 500 chamadas/dia
treg org agents                                  # quem são os agentes da equipe + uso de hoje
treg org agent-rm <user_id>                      # revogue instantaneamente

Coloque esse token na variável de ambiente TREG_TOKEN do agente. Um token de agente pode chamar as ferramentas desta equipe e ler — ele nunca pode fazer login, criar uma equipe, ou ser owner. Se você é um agente e recebeu seu próprio token, use-o em vez do do proprietário da máquina: seu trabalho então aparecerá com seu próprio nome em treg calls.

O convidado faz login com o e-mail convidado e executa treg accept — sem necessidade de manipular código (o caminho do código ainda funciona: treg org join <code>). Um convidado novo também ganha sua própria organização pessoal (sem estado vazio), então removê-lo de uma equipe nunca o bloqueia. Dê a uma ferramenta uma sonda para que o treg possa validá-la: health_check: {method, path, expect_status} (ex.: intercom {"path":"me"}).

Regras

• Segredos são somente gravação — a API nunca retorna um valor armazenado, para você ou para qualquer um.
• Uma ferramenta pode vincular um segredo que um colega de equipe compartilhou com esta organização (usar sem reter) — esse é o propósito: eles escolheram compartilhá-lo, ele permanece escopo da organização, você pode gastá-lo sem vê-lo, e cada chamada é atribuída ao token que a fez. É acesso delegado dentro de uma equipe, nunca acesso a uma credencial que ninguém lhe concedeu.
• Tudo tem escopo da sua organização ativa. Um token alcança as ferramentas daquela equipe e de mais ninguém.
• O proxy não entende o upstream; se uma chamada falhar, o status que você vê é a verdade do upstream.
• Mais: https://treg.to/llms.txt (integração de agente) · https://treg.to/tutorial (passo a passo interativo).