croct-tech/agent-skills

Escrever e depurar CQL

CQL é a linguagem de consulta semelhante ao inglês do Croct. A mesma sintaxe de expressão alimenta audiências, avaliação em tempo real de SDKs e da API HTTP, e valores de conteúdo dinâmico. Tudo aqui é dos docs.croct.com; quando algo não estiver coberto, verifique a documentação ao vivo (no final deste arquivo) em vez de adivinhar.

Fluxo de trabalho

1. Identifique onde a consulta é executada: audiência (deve ser booleano), evaluate/API (qualquer valor JSON, máximo de 500 caracteres) ou valor dinâmico (o resultado deve caber no tipo de atributo, caso contrário default).
2. Escolha a fonte de dados: contexto atual (page, cart, location, campaign, device), perfil armazenado (user's ..., user's stats), sessão (session's ...) ou histórico (user has ... expressões de evento, plano Scale).
3. Verifique se os dados são coletados: qualquer coisa sinalizada como integração necessária (atributos de perfil, carrinho, interesses, metas, estado de login) nunca corresponde a menos que o aplicativo os envie.
4. Escreva com a folha de consulta rápida abaixo; procure propriedades exatas em context-and-data-types.md.
5. Execute a lista de verificação de armadilhas e teste com croct.evaluate() ou o estimador do painel.

Folha de consulta rápida

// Estilos natural, técnico e misto são intercambiáveis
user's score is greater than 90
user.score > 90
user's score > 90

Necessidade	Sintaxe
Propriedade	user's address's city, user's stats' orders, property city of user's address, user.address.city
Chave/índice incomum	page.query['coupon-code'], list[0], (user's interests)[0]
Seletores	cart.items[1st], [:first], [:last(2)], items[*].price, data[...].price
Literais	null, true, 42, 3.14 (decimal), 3.14f, 51%, "str", 'raw', ~/re/i, [1, 2], ["k": "v"]
Datas	Sem literal: "2026-01-01" as date, "2026-01-01T12:00" as datetime; today + 1 day
Lógica	and or not (&& `
Comparação	== != > >= < <=; 1 < x < 3; is equal to X ignoring case
Abreviação literal	X is "value", X is not 0 (o lado direito deve ser um literal)
Strings	starts with, ends with, matches "sub" / matches ~/re/i (sensível a maiúsculas), is like "sub" (insensível a maiúsculas)
Coleções	contains X, X is in [..], contains all of [..], contains either [..], contains neither [..]
Presença	is defined / is known, is empty
Usuário/sessão	user is returning, user is anonymous, user is identified, session is starting
Datas	is before, is after, is at "12:00", is between A and B [exclusive], today's weekday is "monday"
Quantificadores	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"
Variáveis	let orders = user's stats' orders; orders >= 5
Eventos (Scale)	user has <event> [with prop value] [at least N times] [in last 7 days]
Comentários	// line, # line, /* block */

Palavras-chave e identificadores são insensíveis a maiúsculas e minúsculas; literais de string são sensíveis a maiúsculas e minúsculas.

Contexto de relance

Variável	Propriedades comuns
user	id, firstName, email, age, company, jobTitle, interests, activities, stats' sessions, stats' orders, qualquer 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 passados na avaliação
now, today, yesterday, tomorrow	weekday, day, month, year, hour...

Padrões mais úteis

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"

Mais por caso de uso (campanha, localização, tecnologia, sessão, perfil, carrinho, pedidos, consultas de valor): references/recipes.md.

Avaliar a partir do 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']}}, // lido como `context's countries`
);

Servidor Next.js: await evaluate(query) ou await cql`user's persona is in ${roles}` do @croct/plug-next/server. React: useEvaluation(query). HTTP: POST https://api.croct.io/client/web/evaluate com {"query": "..."}. Detalhes, limites de atributos, valores dinâmicos e estimativa: references/evaluation.md.

Armadilhas e depuração

Sintoma	Causa provável	Correção
Erro de sintaxe em x is y	A abreviação is precisa de um literal à direita	x is equal to y ou x == y
Erro de sintaxe em location city is "Berlin"	Acessor ausente: palavras soltas entre uma variável e sua propriedade	location's cityName, property cityName of location ou location.cityName
Erro ao comparar "1" > 0 ou session's start > "2026-01-01"	Operadores relacionais nunca convertem tipos	Cast: "1" as number > 0, ... > "2026-01-01" as datetime ou use is after
Localização/código nunca corresponde	Maiúsculas erradas: códigos são maiúsculos ("US", "NA", "CA") e strings são sensíveis a maiúsculas	Use maiúsculas, is like, is equal to ... ignoring case ou ~/.../i
matches "Sale" perde "sale"	matches, starts with, ends with são sensíveis a maiúsculas	is like "sale" ou matches ~/sale/i
Quantificador engole condição seguinte	O predicado do quantificador se estende até o final	Coloque todo o quantificador entre parênteses
a or b and c se comporta estranhamente	and liga mais forte que or	Adicione parênteses
Resultado condicional multiplicado erradamente	Condicionais são gananciosas	(A if c otherwise B) * price
Condição de perfil/carrinho/interesse nunca é verdadeira	Dados que exigem integração não foram enviados	Rastreie o evento ou defina o atributo (veja a skill croct-track-events)
Tanto X is greater than 30 quanto X is not greater than 30 são falsos	Valor indefinido: tolerância a erro booleano resulta em falso	Use X is defined and ... ou X or else 0
user is identified sempre falso	Eventos de login/logout não rastreados	Rastreie-os; caso contrário, os usuários são sempre anônimos
Erros em cart.items[2nd], first of, average of, min of	Elemento ausente ou coleção vazia	Anexe or else null / or else 0
contains none of [] vs contains neither []	Lado direito vazio: none falso, neither verdadeiro	Use contains neither para "nenhuma sobreposição"
Erro ao misturar 's com colchetes	Posse mais colchetes precisam de parênteses	(cart's items)[1st] ou notação de ponto cart.items[*]
Expressões de evento indisponíveis	Elas são um recurso do plano Scale	Use estatísticas de perfil/sessão quando possível (user's stats' orders)
"Estimativa indisponível"	Usa page, contexto atual ou now/today/yesterday	Esperado; a audiência ainda funciona em tempo de execução
Erro de intervalo	Intervalos .. têm no máximo 30 itens	Reduza o intervalo
Erro de nome de variável/parâmetro	Variáveis não podem ser redefinidas; nomes devem ser identificadores	Renomeie; evite palavras reservadas (user, page) e palavras genéricas

Faça:

• Prefira is equal to, is greater than explícitos em audiências compartilhadas com não desenvolvedores; use estilo técnico quando ficar melhor.
• Proteja dados opcionais com is defined ou or else.
• Coloque condições baratas primeiro em cadeias and (curto-circuito pula o resto).
• Use contains either / contains neither em vez de negar contains all / contains none.

Não faça:

• Não invente testes, variáveis ou frases de evento. Exemplos como user is new ou user has made purchase aparecem na prosa da documentação, mas não são construções documentadas; use user is not returning e user's stats' orders is not 0 (ou user has placed an order).
• Não compare location's countryName com um código; use countryCode para "US".
• Não confie em conversão implícita de data em aritmética: "2021-01-01" as date + 1 day.

Referências

Arquivo	Leia quando
references/syntax.md	Regras lexicais, let, funções, literais, acessores e seletores, tabela de precedência, condicionais, durações
references/context-and-data-types.md	Todas as variáveis e propriedades, sinalizadores de disponibilidade, enumerações (categoria de dispositivo, estágio do carrinho, continente, tags de localização), conversões
references/expressions.md	Todos os testes, operadores, tolerância a erro, quantificadores, macros, modificadores
references/events.md	Expressões de evento, operadores de critério, quantificadores de contagem, janelas de tempo, requisitos de rastreamento
references/evaluation.md	SDK evaluate / cql / hooks, API de Avaliação, atributos de contexto, valores dinâmicos, estimativa de audiência
references/recipes.md	Audiências e consultas de valor prontas para uso por caso de uso

Skills relacionadas: croct-integrate-sdk (configuração do SDK), croct-track-events (envio de eventos e atributos que as consultas leem), croct-use-api (APIs HTTP), croct-model-content (valores dinâmicos em definições de conteúdo), croct-personalize-and-test (experiências e experimentos que usam audiências), croct-use-croct (conceitos e orientação).

Documentação ao vivo

• Índice: https://docs.croct.com/llms.txt
• Referência CQL: https://docs.croct.com/reference/cql/introduction.md (adicione .md a qualquer página)
• Pesquisar: https://docs.croct.com/api/search.md?term=