croct-tech/agent-skills

Escribe y depura CQL

CQL es el lenguaje de consulta similar al inglés de Croct. La misma sintaxis de expresiones impulsa audiencias, evaluación en tiempo real desde SDKs y la API HTTP, y valores de contenido dinámico. Todo aquí proviene de docs.croct.com; cuando algo no esté cubierto, consulta la documentación en vivo (al final de este archivo) en lugar de adivinar.

Flujo de trabajo

1. Identifica dónde se ejecuta la consulta: audiencia (debe ser booleana), evaluate/API (cualquier valor JSON, máximo 500 caracteres) o valor dinámico (el resultado debe ajustarse al tipo de atributo, si no, default).
2. Elige la fuente de datos: contexto actual (page, cart, location, campaign, device), perfil almacenado (user's ..., user's stats), sesión (session's ...) o historial (user has ... expresiones de evento, plan Scale).
3. Verifica que los datos se recopilan: cualquier cosa marcada como integración requerida (atributos de perfil, carrito, intereses, objetivos, estado de inicio de sesión) nunca coincidirá a menos que la aplicación lo envíe.
4. Escríbelo con la hoja de referencia a continuación; busca propiedades exactas en context-and-data-types.md.
5. Ejecuta la lista de verificación de errores comunes y luego prueba con croct.evaluate() o el estimador del panel.

Hoja de referencia

// Los estilos natural, técnico y mixto son intercambiables
user's score is greater than 90
user.score > 90
user's score > 90

Necesidad	Sintaxis
Propiedad	user's address's city, user's stats' orders, property city of user's address, user.address.city
Clave extraña / índice	page.query['coupon-code'], list[0], (user's interests)[0]
Selectores	cart.items[1st], [:first], [:last(2)], items[*].price, data[...].price
Literales	null, true, 42, 3.14 (decimal), 3.14f, 51%, "str", 'raw', ~/re/i, [1, 2], ["k": "v"]
Fechas	Sin literal: "2026-01-01" as date, "2026-01-01T12:00" as datetime; today + 1 day
Lógica	and or not (&& || !); and une más fuerte que or
Comparar	== != > >= < <=; 1 < x < 3; is equal to X ignoring case
Abreviatura literal	X is "value", X is not 0 (el lado derecho debe ser un literal)
Cadenas	starts with, ends with, matches "sub" / matches ~/re/i (distingue mayúsculas), is like "sub" (no distingue mayúsculas)
Colecciones	contains X, X is in [..], contains all of [..], contains either [..], contains neither [..]
Presencia	is defined / is known, is empty
Usuario/sesión	user is returning, user is anonymous, user is identified, session is starting
Fechas	is before, is after, is at "12:00", is between A and B [exclusive], today's weekday is "monday"
Cuantificadores	some x in C satisfies P, every, no, not every, at least 2 of any [distinct] x in C satisfies P
Macros	count of, sum of, average of, min of, max of, first of, last of, keys of, length of, number of days between A and B, this month
Modificadores	as number, rounded [down], in title case, sorted descending, without duplicates, replacing "a" with "b", today at "12:00"
Fallback	user's name or else "Anonymous" (??)
Condicional	"A" if cond otherwise "B", cond ? "A" : "B"
Variables	let orders = user's stats' orders; orders >= 5
Eventos (Scale)	user has <event> [with prop value] [at least N times] [in last 7 days]
Comentarios	// line, # line, /* block */

Las palabras clave y los identificadores no distinguen mayúsculas de minúsculas; los literales de cadena distinguen mayúsculas.

Contexto de un vistazo

Variable	Propiedades comunes
user	id, firstName, email, age, company, jobTitle, interests, activities, stats' sessions, stats' orders, cualquier atributo personalizado
session	start, duration, landingPage, referrer, stats' pageviews, stats' orders, audiences, experiences, experiments, atributos personalizados
page (web)	title, url, path, query, anchor, referrer
location	continentCode, countryCode, countryName, stateCode/regionCode (alias de state's code), stateName, cityName, timeZone, tags
device / browser	category (desktop, tablet, mobile, bot, ...), vendor, name, os; browser's name, type
campaign	name, source, medium, content, term (UTM)
cart	stage (browsing, shopping, checkout), items, total, subtotal, coupon, discount
context	timeZone, atributos pasados en la evaluación
now, today, yesterday, tomorrow	weekday, day, month, year, hour...

Patrones más útiles

user is returning
user is not returning
session is starting
device's category is "mobile"
device's category is not "bot"
location's countryCode is "US"
location's state's code is in ["NY", "CA"]
location's cityName is "New York" and today's weekday is "monday"
campaign's source is "google" and campaign's medium is "cpc"
campaign's name matches "sale"
page's path is in ["/pricing", "/plans"]
page's query's newsletter is "daily-news"
page.query['coupon-code'] is defined
session's referrer matches "google"
session's landingPage starts with "https://example.com/promo"
session's duration > 5 minutes and session's stats' orders is 0
user's interests contains either ["marketing", "sales"]
user's age is between 18 and 30
user's stats' orders is 0
user's plan is "premium"
cart's stage is "checkout" and cart's total is greater than 100
some item in cart's items satisfies item's brand is "Apple"
(no item in cart's items satisfies item's name is like "smartphone") and user is returning
user has abandoned a cart at least 2 times
user has viewed a product with category "Shoes" in last 7 days
user has completed goal "demo-requested" last session
user's firstName or else "there"

Más por caso de uso (campaña, ubicación, tecnología, sesión, perfil, carrito, pedidos, consultas de valor): references/recipes.md.

Evaluar desde código

import croct from '@croct/plug';

const isReturning = await croct.evaluate<boolean>('user is returning').catch(() => false);
const inList = await croct.evaluate<boolean>(
  "context's countries include location's countryName",
  {attributes: {countries: ['United States', 'Canada']}}, // se lee como `context's countries`
);

Servidor Next.js: await evaluate(query) o await cql`user's persona is in ${roles}` desde @croct/plug-next/server. React: useEvaluation(query). HTTP: POST https://api.croct.io/client/web/evaluate con {"query": "..."}. Detalles, límites de atributos, valores dinámicos y estimación: references/evaluation.md.

Errores comunes y depuración

Síntoma	Causa probable	Solución
Error de sintaxis en x is y	La abreviatura is necesita un literal a la derecha	x is equal to y o x == y
Error de sintaxis en location city is "Berlin"	Falta el acceso: palabras sueltas entre una variable y su propiedad	location's cityName, property cityName of location o location.cityName
Error al comparar "1" > 0 o session's start > "2026-01-01"	Los operadores relacionales nunca convierten tipos	Conversión: "1" as number > 0, ... > "2026-01-01" as datetime, o usa is after
La ubicación/código nunca coincide	Mayúsculas incorrectas: los códigos están en mayúsculas ("US", "NA", "CA") y las cadenas distinguen mayúsculas	Usa mayúsculas, is like, is equal to ... ignoring case o ~/.../i
matches "Sale" no encuentra "sale"	matches, starts with, ends with distinguen mayúsculas	is like "sale" o matches ~/sale/i
El cuantificador se traga la condición siguiente	El predicado del cuantificador se extiende hasta el final	Pon paréntesis a todo el cuantificador
a or b and c se comporta extraño	and une más fuerte que or	Agrega paréntesis
El resultado condicional se multiplica incorrectamente	Los condicionales son codiciosos	(A if c otherwise B) * price
La condición de perfil/carrito/interés nunca es verdadera	Datos que requieren integración no enviados	Rastrea el evento o establece el atributo (consulta la skill croct-track-events)
Tanto X is greater than 30 como X is not greater than 30 son falsos	Valor indefinido: la tolerancia a errores booleanos da falso	Usa X is defined and ..., o X or else 0
user is identified siempre es falso	Eventos de inicio/cierre de sesión no rastreados	Rastréalos; de lo contrario, los usuarios siempre son anónimos
Errores con cart.items[2nd], first of, average of, min of	Falta un elemento o la colección está vacía	Agrega or else null / or else 0
contains none of [] vs contains neither []	Lado derecho vacío: none es falso, neither es verdadero	Usa contains neither para "sin superposición"
Error al mezclar 's con corchetes	Posesión más corchetes necesitan paréntesis	(cart's items)[1st] o notación de punto cart.items[*]
Expresiones de evento no disponibles	Son una característica del plan Scale	Usa estadísticas de perfil/sesión cuando sea posible (user's stats' orders)
"Estimación no disponible"	Usa page, contexto actual o now/today/yesterday	Esperado; la audiencia aún funciona en tiempo de ejecución
Error de rango	Los rangos .. tienen un máximo de 30 elementos	Reduce el rango
Error en el nombre de la variable/parámetro	Las variables no se pueden redefinir; los nombres deben ser identificadores	Renombra; evita palabras reservadas (user, page) y palabras genéricas

Haz:

• Prefiere is equal to, is greater than explícitos en audiencias compartidas con no desarrolladores; usa el estilo técnico cuando se lea mejor.
• Protege los datos opcionales con is defined o or else.
• Pon las condiciones baratas primero en cadenas con and (el cortocircuito omite el resto).
• Usa contains either / contains neither en lugar de negar contains all / contains none.

No hagas:

• No inventes pruebas, variables o frases de eventos. Ejemplos como user is new o user has made purchase aparecen en la prosa de la documentación pero no son construcciones documentadas; usa user is not returning y user's stats' orders is not 0 (o user has placed an order).
• No compares location's countryName con un código; usa countryCode para "US".
• No confíes en la conversión implícita de fechas en aritmética: "2021-01-01" as date + 1 day.

Referencias

Archivo	Léelo cuando
references/syntax.md	Reglas léxicas, let, funciones, literales, accesos y selectores, tabla de precedencia, condicionales, duraciones
references/context-and-data-types.md	Cada variable y propiedad, indicadores de disponibilidad, enumeraciones (categoría de dispositivo, etapa del carrito, continente, etiquetas de ubicación), conversiones
references/expressions.md	Todas las pruebas, operadores, tolerancia a errores, cuantificadores, macros, modificadores
references/events.md	Expresiones de evento, operadores de criterio, cuantificadores de recuento, ventanas de tiempo, requisitos de seguimiento
references/evaluation.md	SDK evaluate / cql / hooks, API de Evaluación, atributos de contexto, valores dinámicos, estimación de audiencia
references/recipes.md	Audiencias listas para usar y consultas de valor por caso de uso

Skills relacionadas: croct-integrate-sdk (configuración del SDK), croct-track-events (envío de eventos y atributos que las consultas leen), croct-use-api (APIs HTTP), croct-model-content (valores dinámicos en definiciones de contenido), croct-personalize-and-test (experiencias y experimentos que usan audiencias), croct-use-croct (conceptos y orientación).

Documentación en vivo

• Índice: https://docs.croct.com/llms.txt
• Referencia CQL: https://docs.croct.com/reference/cql/introduction.md (agrega .md a cualquier página)
• Búsqueda: https://docs.croct.com/api/search.md?term=<términos>