Communitygithub.com

HybridAIOne/hybridclaw

Ejecuta informes de producción de la API de datos de Google Analytics 4 con autenticación bearer inyectada por gateway, revisión segura de solicitudes, informes de fuente de tráfico, página de destino, series temporales, ingresos, sesiones y eventos clave.

¿Qué es hybridclaw?

Esta habilidad permite a un agente de IA (como Claude Code, Cursor o Codex) ejecutar informes de producción de Google Analytics 4 a través de la API de Datos de Google Analytics. El agente puede traducir solicitudes en lenguaje natural en payloads JSON de la API, revisarlos antes de la ejecución para garantizar su corrección y luego ejecutar informes sobre sesiones, eventos clave, ingresos, desgloses por fuente de tráfico y página de aterrizaje, y consultas de series temporales. Es útil para analistas, equipos de datos y desarrolladores que necesitan automatizar informes de GA4, integrar datos en dashboards o pipelines ETL, y realizar monitoreo sin exponer tokens o claves privadas al modelo de IA. La habilidad soporta dos modos de autenticación: OAuth de usuario delegado y cuenta de servicio, ambos gestionados a través de un gateway que inyecta el token bearer, y mide su costo de ejecución mediante el sistema de uso de HybridClaw.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/HybridAIOne/hybridclaw/tree/HEAD/skills/ga4
Ver original→Ver todas las habilidades

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentación

GA4

Usa esta habilidad para informes de Google Analytics 4 a través de la API de Datos de Google Analytics: sesiones, eventos clave, ingresos, desgloses por fuente de tráfico, desgloses por página de aterrizaje, consultas de series temporales, lecturas de analista ad-hoc, dashboards, informes programados, ETL y monitoreo.

Alcance

  • ejecutar solicitudes runReport de GA4 para una propiedad configurada
  • traducir solicitudes comunes de analista en inglés a payloads de la API de Datos revisables
  • revisar el JSON de la solicitud GA4 antes de la ejecución
  • construir informes de fuente de tráfico, grupo de canales, página de aterrizaje, tendencia diaria, ingresos, sesiones, usuarios y eventos clave
  • soportar OAuth de usuario delegado y autenticación de cuenta de servicio a través del mismo contrato de manejador bearer del gateway
  • mantener la selección del modo de autenticación en la configuración del inquilino/tiempo de ejecución, no en la lógica del prompt
  • medir el costo de ejecución de la habilidad a través de los UsageTotals normales de HybridClaw

Flujo de Trabajo por Defecto

  1. Comienza con report-plan para solicitudes en lenguaje natural a menos que el usuario ya haya proporcionado un JSON de solicitud de la API de Datos de GA4.
  2. Revisa el JSON de solicitud generado o proporcionado por el usuario con review-request antes de una llamada en vivo.
  3. Para llamadas en vivo a la API de GA4 dentro de HybridClaw, usa http_request directamente cuando esté disponible. Pasa el objeto httpRequest emitido por el helper a la herramienta.
  4. Usa el helper para planificación/revisión offline y para ejecución proxyada por el gateway cuando http_request no esté disponible: 
    python3 skills/ga4/scripts/ga4.py ...
  5. Trata todas las operaciones de GA4 en esta habilidad como de solo lectura. No intentes mutaciones de la API de Admin, cambios de acceso a propiedades, cambios de eventos clave o cambios de etiquetas.

Contrato de Autenticación

La habilidad soporta dos modos de autenticación sin exponer tokens o claves privadas al modelo:

  • OAuth de usuario delegado a través de un manejador secreto bearer
  • Intercambio JWT bearer de cuenta de servicio de Google a través del gateway

La configuración del inquilino decide qué modo usar.

Manejador OAuth de usuario delegado por defecto:

hybridclaw auth login google \
  --client-id "<google-oauth-client-id>" \
  --client-secret "<google-oauth-client-secret>" \
  --account [email protected] \
  --scopes "https://www.googleapis.com/auth/analytics.readonly"

hybridclaw auth status google

Para OAuth delegado, usa el bearerSecretName por defecto: "GOOGLE_WORKSPACE_CLI_TOKEN" o una ruta de autenticación URL google-oauth.

Para automatización con cuenta de servicio, almacena el client_email de la cuenta de servicio y la private_key PEM como secretos cifrados en tiempo de ejecución. El gateway lee esos secretos nombrados, firma la aserción JWT del lado del servidor, la intercambia por un token de acceso de Google de corta duración e inyecta ese token en la solicitud GA4.

Establece o actualiza esos secretos en este orden:

  1. Admin del navegador: abre la URL de admin activa de HybridClaw que termina en /admin/secrets.
  2. /chat del navegador o fallback TUI: /secret set GA4_SERVICE_ACCOUNT_EMAIL "<client-email>" y /secret set GA4_SERVICE_ACCOUNT_PRIVATE_KEY "<pem-private-key>".
  3. Fallback de consola local:
hybridclaw secret set GA4_SERVICE_ACCOUNT_EMAIL "<client-email>"
hybridclaw secret set GA4_SERVICE_ACCOUNT_PRIVATE_KEY '<pem-private-key>'

No pegues tokens de acceso OAuth, tokens de actualización, claves privadas de cuenta de servicio o archivos JSON de clave descargados en el prompt. Las credenciales reales permanecen en el tiempo de ejecución de secretos de HybridClaw y son usadas del lado del servidor por el gateway.

Los valores predeterminados almacenados opcionales usan el mismo orden de configuración: admin del navegador en /admin/secrets, luego /secret set en /chat del navegador o TUI, luego fallback de consola local.

hybridclaw secret set GA4_PROPERTY_ID "<numeric-property-id>"
hybridclaw secret set GA4_BEARER_SECRET_NAME "GOOGLE_WORKSPACE_CLI_TOKEN"

Para trabajos de cuenta de servicio sin supervisión, establece los valores predeterminados de entorno en el tiempo de ejecución del inquilino:

GA4_SERVICE_ACCOUNT_EMAIL_SECRET=GA4_SERVICE_ACCOUNT_EMAIL
GA4_SERVICE_ACCOUNT_PRIVATE_KEY_SECRET=GA4_SERVICE_ACCOUNT_PRIVATE_KEY

Contrato de Comandos

Planificar un informe a partir de lenguaje natural:

python3 skills/ga4/scripts/ga4.py --format json report-plan \
  "Muéstrame las conversiones orgánicas de la semana pasada en comparación con la semana anterior"

Construir un payload http_request para una solicitud planificada o escrita a mano:

python3 skills/ga4/scripts/ga4.py --format json http-request 123456789 \
  --request-json '{"dateRanges":[{"startDate":"7daysAgo","endDate":"yesterday"}],"dimensions":[{"name":"date"}],"metrics":[{"name":"sessions"}],"limit":25}'

Ejecutar un informe a través de la ruta del helper del gateway:

python3 skills/ga4/scripts/ga4.py --format json run-report 123456789 \
  --request-json '{"dateRanges":[{"startDate":"7daysAgo","endDate":"yesterday"}],"metrics":[{"name":"sessions"}]}'

Usar autenticación de cuenta de servicio eligiendo los nombres de secretos de cuenta de servicio almacenados:

python3 skills/ga4/scripts/ga4.py --format json http-request 123456789 \
  --google-service-account-email-secret GA4_SERVICE_ACCOUNT_EMAIL \
  --google-service-account-private-key-secret GA4_SERVICE_ACCOUNT_PRIVATE_KEY \
  --request-json '{"dateRanges":[{"startDate":"7daysAgo","endDate":"yesterday"}],"metrics":[{"name":"sessions"}]}'

Revisar el JSON de solicitud offline:

python3 skills/ga4/scripts/ga4.py --format json review-request \
  '{"dateRanges":[{"startDate":"30daysAgo","endDate":"yesterday"}],"dimensions":[{"name":"landingPagePlusQueryString"}],"metrics":[{"name":"sessions"},{"name":"totalRevenue"}],"limit":25}'

Emitir el payload de plantilla de prompt para consulta de analista:

python3 skills/ga4/scripts/ga4.py --format json prompt-template \
  "Sesiones diarias e ingresos de los últimos 30 días"

Ejecutar el conjunto de evaluación incluido:

python3 skills/ga4/scripts/ga4.py --format json eval-scenarios

Reglas de Trabajo

  • Usa identificadores de propiedad GA4 numéricos. Acepta entrada properties/<id>, pero normalízala antes de las llamadas a la API.
  • Usa keyEvents para informes de tipo conversión a menos que el usuario solicite explícitamente una métrica de evento personalizada.
  • Usa sessionDefaultChannelGroup, sessionSourceMedium, landingPagePlusQueryString y date para los desgloses de producción comunes antes de recurrir a dimensiones personalizadas.
  • Incluye un límite de filas. Por defecto, 25 para informes ad-hoc y aumenta solo cuando el usuario solicite un resultado de exportación o de tamaño ETL.
  • Pide aclaración cuando la solicitud mencione un trimestre sin año.
  • No agregues escrituras de la API de Admin a esta habilidad. Una habilidad de administración separada necesitaría niveles de aprobación explícitos y pruebas de límites.

Conjunto de Evaluación

Los escenarios incluidos cubren 25 solicitudes de analista representativas en sesiones, eventos clave, ingresos, fuente de tráfico, página de aterrizaje, series temporales, comparaciones, comercio electrónico, geográfico, dispositivo y casos de seguridad/aclaración.

Skills relacionados

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community