Communitygithub.com

CartoDB/agent-skills

Construye flujos de trabajo de selección de ubicaciones y análisis de canibalización en CARTO. Se activa cuando el usuario menciona selección de ubicaciones, canibalización, nueva ubicación de tienda, dónde abrir, ubicación óptima, colocación de instalaciones, impacto en la red, áreas de influencia superpuestas, áreas gemelas, ubicaciones similares, áreas de apariencia similar, encontrar ubicaciones como las mejores, superposición de tiendas, impacto de ingresos de una nueva tienda, puntos calientes comerciales, puntos calientes de demanda, puntuación de ubicaciones, clasificación de ubicaciones, expandir la red, nueva sucursal, colocación de franquicias, ubicación de estaciones de carga para vehículos eléctricos, o desea evaluar ubicaciones candidatas, cuantificar la superposición entre áreas de influencia, o encontrar áreas que se asemejen a las ubicaciones de mejor rendimiento.

¿Qué es agent-skills?

Esta skill integra flujos de trabajo espaciales en la plataforma CARTO para resolver tres patrones principales: selección de ubicaciones (evaluación y clasificación de candidatos), análisis de canibalización (cuantificación del impacto de nuevas ubicaciones en la red existente) y descubrimiento de áreas gemelas/ubicaciones similares (identificación de zonas con perfiles demográficos y de demanda análogos a las de mejor rendimiento). Utiliza herramientas nativas de CARTO como `native.h3polyfill`, `native.h3enrich`, `native.buildtwinareasmodel` y `native.findsimilarlocations`, además de operaciones de join espacial y agregación. Es ideal para equipos de expansión minorista, planificación de redes, y analistas de ubicaciones que trabajan con BigQuery, Snowflake, Databricks, Redshift o Postgres. La skill detalla desde la carga de datos hasta el guardado de resultados, incluyendo decisiones críticas como la división de tablas mediante umbrales numéricos, la selección entre enriquecimiento poligonal y join espacial, y la medición de distancia usando conteo de hops de H3. También advierte sobre diferencias de proveedor (como mayúsculas en Snowflake) y dependencias de módulos (por ejemplo, `native.commercialhotspots` requiere el módulo Retail de Analytics Toolbox).

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

Preguntar en tu IA favorita

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

Documentación

Análisis de Selección de Ubicaciones y Canibalización

Construye flujos de trabajo en CARTO que identifican ubicaciones óptimas para nuevas instalaciones (tiendas, estaciones, oficinas) combinando criterios espaciales, y que cuantifican el riesgo de canibalización por superposición de áreas de influencia. También cubre el descubrimiento de áreas gemelas y ubicaciones similares.

Prerrequisitos: Cargue carto-create-workflow para el proceso de desarrollo, estructura JSON y validación. Cubre ambas vías de acceso — las herramientas de flujo de trabajo del servidor MCP (create_workflow, validate_workflow, run_workflow) cuando está adjunto, o la CLI carto workflows en caso contrario. Señales de enrutamiento: carto-basics/references/access-paths.md. Cargue carto-trade-area-analysis si el flujo de trabajo involucra isócronas, buffers o enriquecimiento de áreas de captación — cubre el pipeline de áreas de captación en detalle.


Árbol de Decisión

Intención del usuarioPatrón
"¿Dónde debería abrir una nueva tienda?"Selección de ubicación (puntuación + clasificación)
"¿Una nueva tienda perjudicará a las existentes?"Análisis de Canibalización
"Encuentra ubicaciones similares a mis mejores”Áreas gemelas / Ubicaciones similares

Instrucciones

Patrón A: Selección de Ubicaciones (Puntuación + Clasificación)

Ubicaciones existentes + Área objetivo -> Indexación espacial -> Enriquecer con demografía/POIs -> Puntuar/Clasificar -> Filtrar los mejores candidatos -> Guardar

Paso 1: Cargar Datos

Cargue dos conjuntos de datos con native.gettablebyname:

  • Ubicaciones existentes (tiendas/instalaciones actuales)
  • Área objetivo (por ejemplo, límite de ciudad, polígonos de distrito o una cuadrícula que cubra el área de estudio)

División de candidatos de la red existente cuando ambos están en una misma tabla. Si la fuente del usuario es una tabla única donde los "candidatos" se definen mediante un umbral numérico (por ejemplo, revenue ≥ X, size ≥ Y), use un native.where con ese predicado y conecte su salida match al pipeline de candidatos y su salida unmatch al pipeline de la red existente. Dos flujos desde un solo nodo — mucho más limpio que orderby + limit + customsql NOT IN, y evita completamente una consulta SQL personalizada. El umbral aproxima "top N"; si el usuario dice explícitamente "exactamente los 25 mejores", orderby + limit sigue siendo la opción correcta, pero asuma el costo adicional del nodo conscientemente.

Éxito: Ambas tablas cargadas con columnas de geometría e identificadores únicos.

Paso 2: Construir Cuadrícula de Candidatos

Convierta el área objetivo en celdas H3 o Quadbin usando native.h3polyfill o native.quadbinpolyfill. Cada celda es una micro-ubicación candidata.

Éxito: Una cuadrícula continua de celdas que cubre el área de estudio.

Paso 3: Enriquecer Candidatos

Adjunte señales de demanda a cada celda — población, ingresos, tráfico peatonal, densidad de POIs — usando native.h3enrich, native.joinv2 o el Observatorio de Datos.

Si los candidatos son polígonos continuos (áreas de captación / distritos) en lugar de una cuadrícula, la elección entre native.enrichpolygons y native.spatialjoin + native.groupby es importante — consulte carto-spatial-enrichment Paso 4 para el equilibrio (dependencia de AT vs recuento de nodos vs control de predicado/join).

Éxito: Cada celda de la cuadrícula tiene columnas numéricas que representan factores de demanda/idoneidad.

Paso 4: Filtrar por Proximidad a Ubicaciones Existentes

Use native.h3distance para calcular la distancia en saltos desde cada celda candidata hasta la ubicación existente más cercana. Filtre las celdas que están demasiado cerca (riesgo de canibalización) o demasiado lejos (costo logístico). La salida es recuento de saltos, no distancia métrica — convierta usando la longitud del borde de la resolución (consulte Advertencias).

Semántica de distancia — mida la canibalización desde el polígono del área de captación, no desde el punto candidato. Cuando los candidatos son puntos con un área de captación generada (isolínea / búfer — consulte carto-trade-area-analysis), calcule native.distance desde el polígono del área de captación del candidato hasta los puntos competidores existentes, no desde el punto candidato mismo. Razón: ST_DISTANCE(polygon, point) = 0 siempre que el competidor esté dentro del área de influencia — exactamente la señal de canibalización que desea. La distancia punto a punto solo informa "qué tan lejos está el competidor más cercano" y oculta la superposición. Elija el radius coherente con el tamaño del área de captación (por ejemplo, ~5 km para un área de captación a 10 minutos a pie); radios grandes diluyen la señal. Este patrón polígono-a-punto es el punto intermedio entre el filtro de salto H3 del Patrón A y el análisis completo de superposición de cuadrícula del Patrón B — utilícelo siempre que el candidato ya tenga una geometría de área de captación continua.

Éxito: Las celdas candidatas están dentro de una banda de distancia razonable de las ubicaciones existentes, y cualquier señal de canibalización se mide desde el polígono del área de captación cuando existe.

Paso 5: Puntuar y Clasificar

Use el patrón de puntuación de trade-area-analysis:

  1. Normalice cada variable a [0,1] con native.normalize
  2. Puntuación compuesta mediante native.selectexpression con pesos definidos por el usuario
  3. Clasifique con native.orderby (descendente) + native.limit (top N)

Éxito: Una lista breve clasificada de celdas candidatas con puntuaciones compuestas y variables contribuyentes.

Paso 6: Guardar

Use native.saveastable. La columna H3/Quadbin es directamente visualizable en CARTO Builder.

Éxito: Flujo de trabajo validado listo para cargar.


Patrón B: Análisis de Canibalización

Ubicaciones existentes + propuestas -> Áreas de influencia (isolínea/búfer) -> Conversión a cuadrícula -> Intersección/Unión -> Medir superposición -> Guardar

Paso 1: Cargar Datos

Cargue ubicaciones existentes y ubicaciones propuestas (o una tabla única con una columna de bandera que las distinga). Si ambos conjuntos están en una sola tabla y la división se define mediante un umbral numérico (por ejemplo, revenue ≥ X), consulte la división match/unmatch de native.where del Patrón A Paso 1 — produce ambos flujos desde un nodo y evita SQL personalizado.

Éxito: Ambos conjuntos cargados con geometría e identificadores únicos.

Paso 2: Generar Áreas de Influencia

Cree áreas de captación alrededor de las ubicaciones existentes y propuestas usando native.isolines (realistas) o native.buffer (simple). Use los mismos parámetros para ambos conjuntos para garantizar la comparabilidad.

Éxito: Cada ubicación tiene un polígono de área de captación con parámetros consistentes.

Paso 3: Convertir a Índice Espacial

Convierta todos los polígonos de área de captación a celdas H3 o Quadbin con native.h3polyfill. Conserve el identificador de ubicación y una bandera is_proposed.

Éxito: Una fila por celda por ubicación, con ID de ubicación y bandera de tipo.

Paso 4: Encontrar Superposición

Use native.joinv2 (unión interna en la columna de índice espacial) entre las celdas de ubicaciones existentes y las celdas de ubicaciones propuestas. El resultado contiene celdas compartidas por al menos una ubicación existente y una propuesta.

Éxito: La salida contiene solo celdas que caen tanto en un área de captación existente como en una propuesta.

Paso 5: Medir Impacto

Use native.groupby para agregar la superposición:

  • Por ubicación existente: recuento de celdas superpuestas / total de celdas en el área de captación de esa ubicación = porcentaje de superposición
  • Enriquezca las celdas superpuestas con población o ingresos para cuantificar la demanda compartida

Use native.selectexpression para calcular la relación de superposición.

Éxito: Cada ubicación existente tiene una métrica de superposición que muestra cuánto de su área de captación se comparte con las ubicaciones propuestas.

Paso 6: Guardar

Use native.saveastable.

Éxito: Flujo de trabajo validado con métricas de canibalización por ubicación.


Patrón C: Áreas Gemelas / Ubicaciones Similares

Ubicaciones de mejor rendimiento -> Áreas de influencia -> Enriquecer -> Construir modelo de similitud -> Puntuar todas las áreas candidatas -> Clasificar -> Guardar

Paso 1: Identificar Ubicaciones de Referencia

Cargue el conjunto de datos completo de ubicaciones. Filtre las de mejor rendimiento (por ejemplo, cuartil superior por ingresos) usando native.wheresimplified o native.orderby + native.limit.

Éxito: Un subconjunto de ubicaciones de alto rendimiento aislado como conjunto de referencia.

Paso 2: Generar y Enriquecer Áreas de Influencia

Cree áreas de influencia de isócronas o búfer alrededor de las ubicaciones de referencia. Convierta a H3/Quadbin. Enriquezca con datos demográficos, POI y cualquier variable relevante.

Éxito: Cada ubicación de referencia tiene un perfil demográfico completo.

Paso 3: Construir Modelo de Áreas Gemelas

Use native.buildtwinareasmodel (BUILD_TWIN_AREAS_MODEL) para crear un modelo de similitud basado en PCA a partir de las ubicaciones de referencia enriquecidas.

  • Entrada: ubicaciones de referencia enriquecidas con columnas de características numéricas
  • El modelo captura la "firma" multivariante de las ubicaciones exitosas

Éxito: Un artefacto de modelo que codifica el perfil demográfico de los mejores.

Paso 4: Encontrar Ubicaciones Similares

Use native.findsimilarlocations (FIND_SIMILAR_LOCATIONS) para puntuar todas las áreas candidatas contra el modelo de áreas gemelas.

  • Entrada: áreas candidatas enriquecidas con las mismas variables utilizadas para construir el modelo
  • Salida: puntuación de similitud por candidato

Éxito: Cada área candidata tiene una puntuación de similitud relativa al conjunto de referencia.

Paso 5: Clasificar y Guardar

Clasifique por puntuación de similitud descendente. Guarde los mejores candidatos.

Éxito: Una lista clasificada de áreas más similares a las ubicaciones de mejor rendimiento.


Variante de Puntos Calientes Comerciales

Para la selección de ubicaciones impulsada por la demanda (por ejemplo, "¿dónde está la mayor demanda insatisfecha?"), use native.commercialhotspots:

  1. Construya una cuadrícula H3 sobre el área de estudio
  2. Enriquezca con la variable de demanda objetivo (por ejemplo, población de 15 a 34 años)
  3. Ejecute native.commercialhotspots con variablecolumns y weights
  4. Filtre los resultados por significancia (p_value < 0.05)
  5. Opcionalmente, filtre por native.h3distance de las ubicaciones existentes para centrarse en áreas desatendidas

Nota: variablecolumns usa sintaxis de lista estilo Python (['col1', 'col2']), y weights está separado por comas — consulte las advertencias de trade-area-analysis para más detalles.


Advertencias

  • Uso de mayúsculas y dialecto SQL. Esta habilidad usa nombres de columna en minúsculas (h3, is_proposed, population, etc.) — convención de BigQuery / Databricks / Postgres / Redshift. En Snowflake, los identificadores sin comillas aparecen en MAYÚSCULAS — refiérase a ellos como H3, IS_PROPOSED, POPULATION. Consulte carto-create-workflow/references/providers/<provider>.md para reglas de mayúsculas y equivalentes de dialecto SQL.
  • native.commercialhotspots requiere el módulo Retail de Analytics Toolbox. Valide con --connection para confirmar la disponibilidad.
  • Las Áreas Gemelas y Ubicaciones Similares usan PCA internamente — los resultados son sensibles a la selección y escala de variables. Incluya solo variables relevantes y no redundantes. Normalice las entradas si las escalas difieren ampliamente.
  • La superposición de canibalización depende en gran medida de la definición del área de influencia (radio del búfer, tiempo de isolínea). Pequeños cambios en los parámetros pueden invertir los resultados. Documente los parámetros elegidos y la justificación.
  • native.h3distance devuelve recuento de saltos, no distancia física. Multiplique por la longitud aproximada del borde de la celda para la resolución para obtener una distancia métrica aproximada (por ejemplo, res 8 ~ 460 m, res 9 ~ 174 m por salto).
  • Al comparar entre regiones de diferentes tamaños, normalice los datos demográficos a valores per cápita o por área para evitar sesgos de tamaño (por ejemplo, densidad de población en lugar de población total).
  • La "mejor" ubicación depende completamente de los criterios y pesos elegidos — no existe una respuesta objetivamente correcta. Siempre documente los supuestos y permita que el usuario ajuste los pesos.
  • Para el modelo de áreas gemelas, use el mismo conjunto de variables de enriquecimiento tanto para las ubicaciones de referencia como para los candidatos. Las variables no coincidentes harán que el modelo falle o produzca puntuaciones sin sentido.

Plantillas de Referencia

Tutoriales de la Academia

TutorialProveedorURL
Pizza Hut Honolulu — selección de ubicación con puntos calientes comercialesBigQueryEnlace
Pizza Hut Honolulu — selección de ubicación con puntos calientes comercialesSnowflakeEnlace
Canibalización de tiendas — cuantificación del impacto de nuevas tiendasBigQueryEnlace
Canibalización de Starbucks — análisis de superposición de cuadrícula H3BigQueryEnlace
Canibalización de tiendas — superposición de cuadrícula QuadkeySnowflakeEnlace
Encontrar áreas gemelas de tiendas de mejor rendimientoBigQueryEnlace
Encontrar ubicaciones similares basadas en áreas de influenciaBigQueryEnlace
Selección de ubicación para estaciones de carga EVWorkflowsEnlace

Variaciones Comunes

VarianteCómo
Expansión minoristaIsócronas -> enriquecer con demografía + densidad de competidores -> puntuación compuesta -> top N
Planificación de territorios de franquiciaPatrón de canibalización para garantizar áreas de captación sin superposición antes de otorgar territorios
Carga EV / servicios públicosDemanda basada en cuadrícula (población, tráfico) + filtro de distancia de existentes -> clasificar celdas desatendidas
Colocación de vallas publicitarias / OOHBúferes -> enriquecimiento de audiencia -> normalizar + ponderar -> top N (consulte trade-area-analysis)
Optimización de sucursales bancariasÁreas gemelas de las mejores sucursales -> encontrar áreas desatendidas similares -> proponer nuevas sucursales
Competidor ...

[...truncado para traducción]

Individual skills in this repo

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

Skills relacionados