Communitygithub.com

CartoDB/agent-skills

Guía al usuario en la creación de flujos de trabajo de puntuación compuesta cuando pregunta sobre puntuaciones compuestas, índices, puntuaciones multivariable, clasificación de áreas, puntuación de sitios, potencial de mercado, índices de resiliencia, índices de riesgo, puntuaciones ponderadas, PCA o puntuación supervisada/no supervisada.

¿Qué es agent-skills?

Este skill está diseñado para asistentes de IA (como Claude Code, Cursor o Codex) que trabajan con la plataforma de análisis espacial CARTO. Su propósito principal es guiar al agente paso a paso en la construcción de flujos de trabajo (workflows) de puntuación compuesta, permitiendo al usuario crear índices como riesgo de inundación, potencial de mercado, resiliencia o desarrollo humano. El skill cubre tres enfoques: supervisado (cuando se dispone de una variable objetivo como ingresos o tasa de criminalidad), no supervisado con pesos personalizados (cuando el usuario tiene conocimiento experto) y no supervisado basado en datos (usando entropía o el primer componente principal). Soporta tanto el servidor MCP de CARTO como la CLI 'carto workflows'. Incluye instrucciones detalladas sobre cómo construir los pipelines, manejar columnas categóricas, revertir direcciones de variables y evitar errores comunes como el uso incorrecto de mayúsculas en Snowflake o la interpretación errónea del tipo de datos 'weights'.

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

Preguntar en tu IA favorita

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

Documentación

Usa este skill cada vez que el usuario quiera crear una puntuación compuesta, un índice o una clasificación multivariable en un flujo de trabajo de CARTO.

Requisitos previos: Carga carto-create-workflow para el proceso de desarrollo. Cubre ambas rutas de acceso — las herramientas de flujo de trabajo del servidor MCP (create_workflow, validate_workflow, run_workflow) cuando está conectado, o la CLI carto workflows en caso contrario. Señales de enrutamiento: carto-basics/references/access-paths.md.

Instrucciones

Paso 1: Determinar el enfoque de puntuación

Pregunta al usuario el siguiente árbol de decisión:

  1. "¿Tienes una variable objetivo/resultado?" (por ejemplo, ingresos, ventas, tasa de criminalidad)
    • Sí → Método Supervisado usando native.spatialcompositesupervised
  2. "¿Sin objetivo, pero tienes conocimiento experto de la importancia de las variables?" (es decir, pesos personalizados)
    • 2a. La transparencia importa más que el número de nodos → native.normalize por variable + native.selectexpression con la suma ponderada literalmente en SQL (a_norm * 0.5 + b_norm * 0.2 + c_norm * 0.3). Las entradas y los pesos se pueden inspeccionar en línea en los flujos de trabajo; cada columna normalizada se materializa; no hay dependencia de Analytics Toolbox. Úsalo cuando las partes interesadas necesiten ver o auditar la fórmula, o cuando no estés ejecutando en AT.
    • 2b. ¿Quieres que el pipeline de AT (escalado, agregación, agrupación) se maneje por ti? → native.spatialcompositeunsupervised con scoring_method: CUSTOM_WEIGHTS. Un solo nodo, pero la fórmula está oculta dentro del componente.
  3. "¿Sin objetivo, sin pesos?"
    • → Método No supervisado con ENTROPY o FIRST_PC usando native.spatialcompositeunsupervised

Éxito: Has identificado qué componente y método de puntuación usar antes de diseñar el pipeline.

Paso 2: Construir el pipeline

Pipeline supervisado (native.spatialcompositesupervised)

  1. Carga el conjunto de datos de características espaciales (pre-indexado en H3 o Quadbin)
  2. Carga el conjunto de datos objetivo/resultado
  3. Une ambos conjuntos de datos por la columna de índice espacial
  4. Selecciona solo las columnas de características relevantes (elimina la columna de índice espacial y la geometría de la selección de características — pasa solo las variables de características reales)
  5. Ejecuta native.spatialcompositesupervised con parámetros:
    • model_type: LINEAR_REG
    • bucketize: EQUAL_INTERVALS_ZERO_CENTERED
    • n_buckets: 5
    • outlier_removal: true
    • r_squared_threshold: 0.4
  6. Resultado: puntuación compuesta basada en los residuos de la regresión (identifica áreas que tienen un rendimiento superior o inferior en relación con el modelo)

Éxito: El flujo de trabajo une las características con la variable objetivo, selecciona solo columnas de características numéricas y produce una puntuación basada en residuos por celda espacial.

Pipeline no supervisado (native.spatialcompositeunsupervised)

  1. Carga el conjunto de datos de características espaciales
  2. Selecciona solo las columnas de características relevantes
  3. Codifica cualquier variable categórica/u ordinal a numérica usando native.casewhen (por ejemplo, "Low_density_urban" → 4, "High_density_urban" → 2)
  4. Opcionalmente, invierte las variables donde un valor más alto = peor multiplicando por -1 en la consulta SELECT pasada al componente
  5. Ejecuta native.spatialcompositeunsupervised con parámetros:
    • scoring_method: CUSTOM_WEIGHTS / ENTROPY / FIRST_PC
    • weights: requerido si CUSTOM_WEIGHTS. El formato de conexión es una cadena codificada en JSON de tripletes [[<columna>, <peso>, <invertir>], ...] — columna es el nombre de la columna de característica, peso es un peso numérico (normalizado internamente para sumar 1), invertir es un booleano (true invierte la variable para que un valor más alto = peor se convierta en más alto = mejor sin necesidad de un CASE WHEN). Ejemplo: '[["population_density", 0.5, false], ["accident_rate", 0.5, true]]'. No es un mapa de objetos.
    • scaling: RANKING
    • aggregation: LINEAR
    • output: RETURN_RANGE con rango [0, 1]
  6. Resultado: puntuación del índice compuesto por ubicación

Éxito: Todas las variables de entrada son numéricas, las direcciones de las variables están alineadas (más alto = mejor para la puntuación) y la salida es una puntuación normalizada por celda espacial.

Trampas

  • Mayúsculas del proveedor y dialecto SQL. Este skill usa nombres de columna en minúsculas (convención de BigQuery / Databricks / Postgres / Redshift). En Snowflake, los identificadores sin comillas aparecen en MAYÚSCULAS — referencia POPULATION_DENSITY, ACCIDENT_RATE, etc. en pesos, expresiones y SQL posteriores. Consulta carto-create-workflow/references/providers/<proveedor>.md para conocer las reglas de mayúsculas y los equivalentes de dialecto SQL.
  • Todas las variables de entrada deben ser numéricas, con dirección alineada. Codifica cadenas ordinales ("bajo"/"medio"/"alto") mediante CASE WHEN primero, y donde "más alto es peor" multiplica por -1 (o establece el indicador reverse) antes de puntuar — olvidar esto invierte el significado de la puntuación.
  • Umbral de R cuadrado supervisado (por defecto 0.4) es permisivo. Si el ajuste del modelo es pobre, la puntuación basada en residuos es principalmente ruido. Inspecciona los diagnósticos del modelo.
  • Los pesos personalizados se normalizan internamente para sumar 1. Los valores absolutos no importan, solo las proporciones.
  • Las puntuaciones supervisadas son residuos, no valores brutos. La puntuación identifica áreas que SE DESVÍAN del modelo, no áreas con los valores brutos más altos.
  • Elimina la columna de índice espacial y la geometría de la selección de características — solo pasa las variables de características reales al componente de puntuación.
  • La etiqueta de tipo de weights está mal informada. El esquema del componente (a través de read_workflow_components MCP o carto workflows components get native.spatialcompositeunsupervised --json) enumera weights como type: "ColumnNumber", pero la forma real de conexión es una cadena codificada en JSON ColumnAndNumber de tripletes [[<columna>, <peso>, <invertir>], ...] (consulta el Paso 2 arriba). Confía en este skill y en las plantillas de referencia por encima de la etiqueta de tipo informada.
  • indexcol.allowedColumns es una sugerencia de UI, no un validador. El esquema enumera ["geoid", "h3", "quadbin"] para native.spatialcompositeunsupervised.indexcol, pero es una sugerencia del menú desplegable de Workflows: cualquier columna de identificador único funciona en tiempo de ejecución (por ejemplo, store_id, cell_id).

Plantillas de referencia

Ambos ejemplos usan datos de características espaciales de Milán a resolución Quadbin 18.

PlantillaComponenteArchivo
Supervisado — Identificación de barrios resilientesnative.spatialcompositesupervisedcomposite-score-supervised.json
No supervisado — Puntuación de potencial de mercadonative.spatialcompositeunsupervisedcomposite-score-unsupervised.json

Variaciones comunes

VariaciónEnfoque
Índice de riesgo (inundación, crimen, etc.)No supervisado con CUSTOM_WEIGHTS; invierte variables donde más alto = más seguro
Potencial de mercado / puntuación de sitiosNo supervisado con CUSTOM_WEIGHTS o ENTROPY; pondera más las variables del lado de la demanda
Índice de resilienciaSupervisado con variable de resultado (por ejemplo, cambio en ingresos); los residuos revelan rendimiento superior/inferior
Índice basado en datos (sin conocimiento del dominio)No supervisado con FIRST_PC o ENTROPY para dejar que la varianza impulse los pesos
Desarrollo humano / indicador compuestoNo supervisado con CUSTOM_WEIGHTS y escalado RANKING para una agregación segura para ordinales

Individual skills in this repo

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

Skills relacionados