Samin12/skills

treg — el catálogo de herramientas para tu agente

Pide la tarea, no la herramienta. Cuando un trabajo necesita datos externos o en vivo — backlinks, volumen de palabras clave, un perfil de TikTok, un correo laboral, publicidad de la competencia — busca en el catálogo, lee el precio, ejecuta la llamada.

Dos tipos de herramienta responden al mismo token, a través del mismo proxy, que inyecta la credencial del lado del servidor para que nunca la tengas:

• El catálogo — endpoints externos seleccionados que treg puede llamar por ti.
• Tus propias herramientas — lo que un compañero registró y compartió con esta organización: cuentas API, conexiones OAuth, skills. Nota: una conexión X (Twitter) realizada a través de la app de treg se cobra por llamada (X factura al propietario de la app por uso); la respuesta informa el precio. Una app propia de desarrollador X del equipo no está sujeta a medición.

Los mecanismos:

• Endpoint: https://treg.to · CLI: treg · el CLI es un cliente ligero sobre la API.
• Autenticación: cada llamada envía X-Treg-Token: <tu token>.
• Una herramienta = una URL base upstream + enlaces de credenciales. Un skill/paquete = una receta (SKILL.md) + sus secretos + su(s) herramienta(s). El proxy retransmite, nunca modela el upstream.

Primero: instala e inicia sesión

curl -fsSL https://treg.to/install.sh | sh     # instala el CLI y lo apunta aquí
treg login                            # inicio de sesión en el navegador (GitHub / Google / código de correo) — el primer inicio te registra
treg login --email [email protected]     # alternativa solo en terminal (código de 6 dígitos enviado por correo)
treg login --token <token-por-organización>    # no interactivo (agentes/CI)

Todo se ejecuta en tu organización activa (el primer inicio de sesión crea una personal). Las invitaciones a equipos llegan por correo — véalas con treg invites, acéptelas con treg accept (o treg org join <código>). Cambie de equipo: treg org switch <slug>.

¿Ya estás conectado mediante MCP? Entonces tienes las herramientas, no el CLI

Si llegaste a treg a través de https://treg.to/mcp/ — ChatGPT, Claude Code, Cursor — los pasos del CLI anteriores no aplican para ti. Tienes cinco herramientas: catalog_search, catalog_get, call, balance, my_tools. Todo en este documento se asigna a ellas:

• "buscar en el catálogo" → catalog_search, luego catalog_get para el precio y parámetros exactos
• "ejecutar la llamada" → call con el id del endpoint, o <nombre-herramienta>/<ruta> para una de las herramientas propias del equipo
• "revisar el saldo" → balance

Las reglas a continuación son las mismas de cualquier manera. La que más importa — di el precio antes de gastarlo — importa aún más aquí, porque call devuelve cost_usd y puedes informar cuánto costó realmente una llamada en lugar de estimarlo.

Una call en un endpoint del catálogo gasta el saldo del equipo. Una call en una herramienta propia del equipo no gasta nada: esa clave les pertenece.

Tarea — el catálogo: lo que treg puede hacer por ti (empieza aquí)

~2800 endpoints catalogados en ~56 proveedores, agrupados por lo que HACEN: seguimiento de palabras clave y rankings, backlinks y autoridad, visibilidad en IA, tendencias y descubrimiento, publicación en las cuentas sociales del equipo, enriquecimiento de personas y empresas, gestión de anuncios y creatividades, medición.

treg catalog search "publicaciones de subreddit"            # encuentra endpoints por lo que hacen
treg catalog get scrapecreators.reddit.subreddit.posts   # params, PRECIO, cómo se te entregaría
treg call scrapecreators.reddit.subreddit.posts --query subreddit=noticias
treg balance                                     # el saldo prepagado + cargos recientes
treg catalog request "<lo que necesitas>"           # ¿buscaste y no está? repórtalo — guía lo que se añade después

Notas:

• El precio de cada endpoint está en treg catalog get, antes de llamarlo.
• HTTP 402 = saldo insuficiente, con un cuerpo procesable por máquina (balance_micro, estimated_cost_micro, topup_url). Recuperación: treg balance → recarga en el panel (Equipo → Facturación) → o almacena la clave propia de la org para ese proveedor (las claves propias nunca se facturan al saldo — tienen prioridad automática).
• Una herramienta o secreto de organización para el proveedor siempre gana sobre la clave de treg, automáticamente — el catálogo es la alternativa, no un reemplazo para las claves que el equipo ya tiene.
• Elección entre proveedores de una misma capacidad — el procedimiento. treg catalog get <id> lista cada proveedor que ofrece el mismo trabajo con COSTO, FUNCIONA (tasa de éxito que treg ha observado, con el tamaño de muestra), VELOCIDAD (mediana) y ÚLTIMO OK. Sigue este orden:
  1. Coincide con las entradas que REALMENTE TIENES. Un endpoint que requiere profile_url no es un sustituto cuando tienes un nombre y un dominio, sin importar su costo. Esta regla está por encima del precio en todo momento.
  2. Luego confiabilidad: un FUNCIONA alto con una muestra real supera a un número redondo con una pequeña — 99% (121) es evidencia más sólida que 100% (8).
  3. Luego precio. Los rangos dentro de una misma capacidad alcanzan 200×, así que aquí suele estar el dinero.
  4. ÚLTIMO OK rompe empates. Una edad sin más significa que una llamada real regresó; una ✓ edad es el sello de verificación propio del catálogo, no tráfico en vivo; — significa que nadie lo ha verificado ni llamado — prefiere casi cualquier otra cosa.
  • Si una llamada falla con 429 / 5xx / timeout, prueba el siguiente proveedor. Conoces sus parámetros, así que puedes construir su solicitud. Di a cuál cambiaste.
  • Nunca reintentes un 4xx en otro lugar. Un 4xx suele ser por tus parámetros; corregirlos es la solución, y reintentar quema el dinero del equipo en N proveedores por un solo error.
  • treg no elige ni hace failover por ti. Es deliberado: solo tú sabes qué entradas tienes, y treg retransmite sin reescribir tu solicitud.
• Un endpoint sin precio publicado es rechazado, no servido gratis; conecta tu propia clave.

Reintentar una llamada sin pagar dos veces

Si una llamada agota el tiempo de espera o nunca ves su respuesta, repítela con el mismo idempotency_key (sobre MCP) o el encabezado Idempotency-Key (sobre HTTP). treg devuelve la respuesta almacenada, no llama al proveedor nuevamente y no cobra nada. El resultado dice replayed: true.

Solo para un reintento genuino. Preguntar lo mismo para ver qué cambió es TRABAJO NUEVO: usa una clave nueva o ninguna, o recibirás la respuesta anterior. Reutilizar una misma clave para una solicitud diferente es rechazado.

La mayoría de los reintentos no necesitan esto — una llamada fallida nunca fue facturada.

Tarea — tus propias herramientas: llama a una que el equipo haya registrado

Empieza por lo que está registrado, luego usa la API exactamente como dice su documentación. Sin vocabulario de treg, sin parámetros especiales:

treg tool ls                                  # qué ha registrado este equipo
treg call intercom conversations?per_page=5   # <nombre-herramienta> + la ruta upstream

Sobre HTTP eso es GET https://treg.to/call/<nombre-herramienta>/<ruta> con X-Treg-Token: <tu token>. treg busca la herramienta nombrada, inyecta la credencial del equipo del lado del servidor y retransmite todo fielmente (método, parámetros de consulta, tus encabezados, cuerpo). Tu X-Treg-Token es eliminado antes de que el upstream lo vea. Funciona para GET/POST/PUT/PATCH/DELETE.

Solo se resuelven las herramientas que esta organización ha registrado. Descúbrelas con treg tool ls · treg skill ls.

Tarea — comparte tus claves y skills para que los agentes de tus compañeros puedan usarlas

En lote (la vía rápida): ejecútalo en el directorio que la persona nombre. Lista las claves de proveedores que reconoce en ese .env y los skills en sus subdirectorios, y registra solo aquellos que marquen:

treg upload                       # ambos lados del directorio actual; `treg upload env|skills --dir <d>` para restringir

Por defecto: envuelve las claves nuevas en un skill. Al registrar una nueva clave/endpoint/CLI, combínala con un skill para que la credencial, la herramienta y la receta lleguen juntas (y obtenga una página compartible). Si no existe ningún skill, crea uno básico — un SKILL.md adecuado (el frontmatter importa: los agentes descubren skills por él) + una llamada de ejemplo:

mkdir -p ./posthog && cat > ./posthog/SKILL.md <<'MD'
---
name: posthog
---
Consulta la API de PostHog a través de treg — la clave se inyecta del lado del servidor. Úsalo para eventos, insights y consultas de proyectos.
Llámalo: `treg call posthog api/projects/@current` (upstream: https://us.posthog.com)
MD
treg skill init --dir ./posthog   # crea un borrador de treg.json: base_url del catálogo (nombre de la carpeta) o URLs en SKILL.md; revísalo y añade la clave
treg skill add --dir ./posthog    # registra receta + secreto + herramienta atómicamente

Nunca dejes un secreto huérfano: una clave almacenada que nada vincula es peso muerto — si usas secret add directamente, vincúlala a una herramienta (endpoint/CLI) en el mismo paso. Endpoint simple, sin receta (solo cuando un skill no aporta nada):

treg secret add posthog-key --value "$POSTHOG_API_KEY"          # o --file ./.secret/token.json
treg tool add posthog --base-url https://us.posthog.com --secret posthog-key
# API basada en parámetro de consulta en lugar de encabezado bearer:
treg tool add serpapi --base-url https://serpapi.com --secret <nombre-o-id> \
  --auth-in query --auth-name api_key --auth-format '{secret}'

Un skill completo (receta + secretos + herramienta, posiblemente multi-credencial):

treg skill scaffold ~/.claude/skills/google-ads --out gads.json
#   -> recorre el directorio: captura SKILL.md como la receta + cada .secret/* como un secreto.
#   -> LUEGO editas gads.json: estableces base_url y completas cada enlace (ubicación/nombre/formato).
#      ej. google-ads necesita DOS enlaces en una misma solicitud:
#        Authorization: Bearer {access_token}  (inyector: oauth)
#        developer-token: {secret}             (inyector: env)
treg skill push gads.json                                        # registra el paquete atómicamente

Compártelo dentro de la organización: dale a un compañero el endpoint + el nombre de la herramienta y su agente puede llamarla sin recibir la credencial — tú concediste el acceso, treg inyecta el secreto y la llamada se registra contra su token.

Formas de autenticación (por enlace injector, = el kind del secreto): env (cadena simple) · secret_file (archivo JSON de token, extraer secret_field) · oauth (token JSON, auto-refrescado) · cli_auth (un token que la persona copió de un CLI en el que ya inició sesión y proporcionó a treg por sí misma). Varios enlaces se aplican a cada solicitud.

OAuth, dos modos (treg lo mantiene fresco): si el secreto OAuth incluye refresh_token + client_id + client_secret, treg lo auto-refresca antes de que expire (nunca vuelves a subirlo). Si es solo un token simple, ese es el modo manual, treg lo inyecta tal cual y lo vuelves a subir cuando expire. Mismo almacenamiento; una credencial puede pasar de manual a automático sin migración.

Obtener el primer token OAuth, dos formas (tú eliges):

• Manual: haz tu propio OAuth localmente, luego treg secret add gsc --file token.json --kind oauth.
• Conexión alojada: treg oauth connect gsc --client-secret client_secret.json --scopes <ámbito> → imprime una URL de consentimiento; la apruebas en el navegador; treg captura el token directamente. Configuración única: añade https://treg.to/oauth/callback a las URIs de redirección de tu app OAuth.

Tarea — gestiona el equipo y supervisa

treg tool ls / secret ls / skill ls / calls          # inventario + registro de auditoría — limitado a la org activa
treg tool rm <id> / secret rm <id> / skill rm <id>   # secret rm está bloqueado mientras una herramienta lo vincule
treg health            # estado de cada credencial en esta org (ok | invalid | unknown)
treg health --run      # volver a comprobar ahora: refrescar tokens OAuth, probar cada herramienta, alertar a propietarios

Equipos / organizaciones (propietario > admin > miembro > visor; un miembro gestiona solo lo que creó):

treg org create "Equipo A"                       # te conviertes en propietario (auto-activo)
treg org invite [email protected] --role member  # admin+; envía la invitación por correo (un código de un solo uso es la alternativa)
treg org members                               # admin+; quién está en la org activa
treg org ls / treg org switch <slug>           # tus orgs / cambiar de activa

Dale a un agente su propia identidad (admin+). Un agente no tiene que tomar prestado el token del humano — créale uno, y cada llamada que haga estará limitada, acotada y registrada como él mismo:

treg org agent-new ci-bot                        # imprime el token UNA VEZ (ejecutar de nuevo para rotarlo)
treg org agent-new ci-bot --tools stripe,gh --cap 500   # solo estas herramientas, 500 llamadas/día
treg org agents                                  # quiénes son los agentes del equipo + uso de hoy
treg org agent-rm <user_id>                      # revocar inmediatamente

Coloca ese token en la variable de entorno TREG_TOKEN del agente. Un token de agente puede llamar a las herramientas de este equipo y leer — nunca puede iniciar sesión, crear un equipo ni ser propietario. Si eres un agente y te dieron tu propio token, úsalo en lugar del del propietario de la máquina: tu trabajo aparecerá con tu propio nombre en treg calls.

El invitado inicia sesión con el correo invitado y ejecuta treg accept — sin necesidad de manejar códigos (la ruta de código aún funciona: treg org join <código>). Un invitado nuevo también obtiene su propia org personal (sin estado vacío), por lo que eliminarlo de un equipo nunca lo bloquea. Dale a una herramienta una sonda para que treg pueda validarla: health_check: {method, path, expect_status} (ej. intercom {"path":"me"}).

Reglas

• Los secretos son solo de escritura — la API nunca devuelve un valor almacenado, ni a ti ni a nadie.
• Una herramienta puede vincular un secreto que un compañero compartió con esta org (usar-sin-tener) — ese es el objetivo: ellos eligieron compartirlo, permanece limitado a la org, puedes gastarlo sin verlo y cada llamada se atribuye al token que la hizo. Es acceso delegado dentro de un equipo, nunca acceso a una credencial que nadie te concedió.
• Todo está limitado a tu organización activa. Un token alcanza las herramientas de ese equipo y de nadie más.
• El proxy no entiende el upstream; si una llamada falla, el estado que ves es la verdad del upstream.
• Más: https://treg.to/llms.txt (incorporación de agentes) · https://treg.to/tutorial (tutorial interactivo).