Communitygithub.com

CartoDB/agent-skills

Orienta o usuário na criação de workflows de pontuação composta quando ele pergunta sobre scores compostos, índices, pontuações multivariáveis, classificação de áreas, scoring de locais, potencial de mercado, índices de resiliência, índices de risco, scores ponderados, PCA ou scoring supervisionado/não supervisionado.

O que é agent-skills?

Esta skill do agente foi projetada especificamente para orientar usuários na criação de workflows de pontuação composta na plataforma CARTO. Ela entra em ação sempre que o usuário deseja construir um score composto, índice ou classificação multivariável, por exemplo, para avaliar potencial de mercado, resiliência, risco ou identificar áreas com desempenho superior/inferior. A skill cobre ambos os caminhos de acesso: as ferramentas de workflow do servidor MCP (`create_workflow`, `validate_workflow`, `run_workflow`) e a CLI `carto workflows`. O processo é dividido em duas etapas principais: primeiro, um questionário determina a abordagem de score (supervisionado, não supervisionado ou com pesos personalizados). Em segundo lugar, a skill fornece instruções detalhadas para construir o pipeline no CARTO Workflows, incluindo parâmetros específicos para os componentes `native.spatialcompositesupervised` e `native.spatialcompositeunsupervised`. A skill também documenta armadilhas comuns, como diferenças de maiúsculas/minúsculas entre provedores de banco de dados (especialmente Snowflake), a necessidade de ter todas as variáveis de entrada numéricas e com direção alinhada, e que o tipo do parâmetro `weights` é um JSON string, não um mapa de objetos. Inclui templates de referência e variações comuns para diferentes casos de uso.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CartoDB/agent-skills/tree/HEAD/skills/carto-composite-scoring

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Use esta skill sempre que o usuário quiser criar um score composto, índice ou classificação multivariável em um Workflow do CARTO.

Pré-requisitos: Carregue carto-create-workflow para o processo de desenvolvimento. Ela cobre ambos os caminhos de acesso — as ferramentas de workflow do servidor MCP (create_workflow, validate_workflow, run_workflow) quando anexado, ou a CLI carto workflows caso contrário. Sinais de roteamento: carto-basics/references/access-paths.md.

Instruções

Etapa 1: Determinar a abordagem de pontuação

Pergunte ao usuário a seguinte árvore de decisão:

  1. "Você tem uma variável alvo/resultado?" (ex.: receita, vendas, taxa de criminalidade)
    • Sim → Método Supervisionado usando native.spatialcompositesupervised
  2. "Sem alvo, mas você tem conhecimento especializado sobre a importância das variáveis?" (ou seja, pesos personalizados)
    • 2a. Transparência é mais importante que a contagem de nós → native.normalize por variável + native.selectexpression com a soma ponderada literalmente em SQL (a_norm * 0.5 + b_norm * 0.2 + c_norm * 0.3). As entradas e os pesos são inspecionáveis inline nos Workflows; cada coluna normalizada é materializada; sem dependência do Analytics Toolbox. Use quando as partes interessadas precisam ver/auditar a fórmula, ou quando você não está executando no AT.
    • 2b. Quer o pipeline do AT (escalonamento, agregação, agrupamento) tratado para você → native.spatialcompositeunsupervised com scoring_method: CUSTOM_WEIGHTS. Um nó, mas a fórmula fica oculta dentro do componente.
  3. "Sem alvo, sem pesos?"
    • → Método Não supervisionado com ENTROPY ou FIRST_PC usando native.spatialcompositeunsupervised

Sucesso: Você identificou qual componente e método de pontuação usar antes de projetar o pipeline.

Etapa 2: Construir o pipeline

Pipeline supervisionado (native.spatialcompositesupervised)

  1. Carregue o conjunto de dados de features espaciais (pré-indexado em H3 ou Quadbin)
  2. Carregue o conjunto de dados alvo/resultado
  3. Junte ambos os conjuntos na coluna do índice espacial
  4. Selecione apenas as colunas de features relevantes (descarte a coluna do índice espacial e a geometria da seleção de features — passe apenas as variáveis de features reais)
  5. Execute native.spatialcompositesupervised com parâmetros:
    • model_type: LINEAR_REG
    • bucketize: EQUAL_INTERVALS_ZERO_CENTERED
    • n_buckets: 5
    • outlier_removal: true
    • r_squared_threshold: 0.4
  6. Saída: score composto baseado nos resíduos da regressão (identifica áreas que têm desempenho superior/inferior em relação ao modelo)

Sucesso: O workflow junta as features com a variável alvo, seleciona apenas colunas de features numéricas e produz um score baseado em resíduos por célula espacial.

Pipeline não supervisionado (native.spatialcompositeunsupervised)

  1. Carregue o conjunto de dados de features espaciais
  2. Selecione apenas as colunas de features relevantes
  3. Codifique quaisquer variáveis categóricas/ordinais para numérico usando native.casewhen (ex.: "Low_density_urban" → 4, "High_density_urban" → 2)
  4. Opcionalmente, inverta variáveis onde maior = pior multiplicando por -1 na consulta SELECT passada ao componente
  5. Execute native.spatialcompositeunsupervised com parâmetros:
    • scoring_method: CUSTOM_WEIGHTS / ENTROPY / FIRST_PC
    • weights: obrigatório se CUSTOM_WEIGHTS. O formato é uma string JSON de triplas [[<coluna>, <peso>, <inverter>], ...] — coluna é o nome da coluna de feature, peso é um peso numérico (normalizado internamente para somar 1), inverter é um booleano (true inverte a variável para que maior = pior se torne maior = melhor sem necessidade de CASE WHEN). Exemplo: '[["population_density", 0.5, false], ["accident_rate", 0.5, true]]'. Não é um mapa de objetos.
    • scaling: RANKING
    • aggregation: LINEAR
    • output: RETURN_RANGE com intervalo [0, 1]
  6. Saída: índice composto por localização

Sucesso: Todas as variáveis de entrada são numéricas, as direções das variáveis estão alinhadas (maior = melhor para o score) e a saída é um score normalizado por célula espacial.

Armadilhas

  • Maiúsculas/minúsculas do provedor e dialeto SQL. Esta skill usa nomes de colunas em minúsculas (convenção do BigQuery / Databricks / Postgres / Redshift). No Snowflake, identificadores não citados aparecem em MAIÚSCULAS — consulte POPULATION_DENSITY, ACCIDENT_RATE, etc. em pesos, expressões e SQL downstream. Veja carto-create-workflow/references/providers/<provider>.md para regras de maiúsculas/minúsculas e equivalentes de dialeto SQL.
  • Todas as variáveis de entrada devem ser numéricas, com direção alinhada. Codifique strings ordinais ("baixo"/"médio"/"alto") via CASE WHEN primeiro, e onde "maior é pior" multiplique por -1 (ou defina a flag reverse) antes da pontuação — esquecer isso inverte o significado do score.
  • Limiar de R-quadrado supervisionado (padrão 0,4) é permissivo. Se o ajuste do modelo for ruim, o score baseado em resíduos será principalmente ruído. Inspecione os diagnósticos do modelo.
  • Pesos personalizados são normalizados internamente para somar 1. Os valores absolutos não importam, apenas as proporções.
  • Scores supervisionados são resíduos, não valores brutos. O score identifica áreas que SE DESVIAM do modelo, não áreas com os valores brutos mais altos.
  • Descarte a coluna do índice espacial e a geometria da seleção de features — passe apenas variáveis de features reais para o componente de pontuação.
  • O rótulo de tipo de weights é relatado incorretamente. O esquema do componente (via read_workflow_components MCP ou carto workflows components get native.spatialcompositeunsupervised --json) lista weights como type: "ColumnNumber", mas a forma real é uma string JSON codificada de triplas [[<coluna>, <peso>, <inverter>], ...] (veja Etapa 2 acima). Confie nesta skill e nos templates de referência em vez do rótulo de tipo relatado.
  • indexcol.allowedColumns é uma dica de UI, não um validador. O esquema lista ["geoid", "h3", "quadbin"] para native.spatialcompositeunsupervised.indexcol, mas é uma dica de dropdown do Workflows — qualquer coluna de identificador único funciona em tempo de execução (ex.: store_id, cell_id).

Templates de Referência

Ambos os exemplos usam dados de features espaciais de Milão na resolução Quadbin 18.

TemplateComponenteArquivo
Supervisionado — Identificando bairros resilientesnative.spatialcompositesupervisedcomposite-score-supervised.json
Não supervisionado — Scoring de potencial de mercadonative.spatialcompositeunsupervisedcomposite-score-unsupervised.json

Variações Comuns

VariaçãoAbordagem
Índice de risco (inundação, crime, etc.)Não supervisionado com CUSTOM_WEIGHTS; inverta variáveis onde maior = mais seguro
Potencial de mercado / scoring de locaisNão supervisionado com CUSTOM_WEIGHTS ou ENTROPY; pondere variáveis do lado da demanda mais alto
Índice de resiliênciaSupervisionado com variável de resultado (ex.: mudança na receita); resíduos revelam desempenho superior/inferior
Índice orientado por dados (sem conhecimento de domínio)Não supervisionado com FIRST_PC ou ENTROPY para deixar a variância guiar os pesos
Desenvolvimento humano / indicador compostoNão supervisionado com CUSTOM_WEIGHTS e escalonamento RANKING para agregação segura para ordinais

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas