Communitygithub.com

CartoDB/Agent-Fähigkeiten

Führt den Benutzer durch die Erstellung von Composite-Score-Workflows, wenn er nach Composite Scores, Indizes, multivariablen Scores, Standortbewertungen, Marktpotenzial, Resilienzindizes, Risikoindizes, gewichteten Scores, PCA oder überwachtem/unüberwachtem Scoring fragt.

Was ist Agent-Fähigkeiten?

Diese Fähigkeit (Skill) ist für Entwickler und KI-Agenten gedacht, die mit der CARTO-Plattform arbeiten und Composite Scores, Indizes oder multivariate Ranglisten in Workflows erstellen möchten. Sie behandelt den gesamten Prozess von der Bestimmung des geeigneten Scoring-Ansatzes (überwacht, unüberwacht mit benutzerdefinierten Gewichten oder unüberwacht per Entropie/Erster Hauptkomponente) bis zum Aufbau der entsprechenden Pipeline. Die Fähigkeit unterstützt sowohl den MCP-Server (mit Werkzeugen wie `create_workflow`, `validate_workflow`, `run_workflow`) als auch die CLI (`carto workflows`) und stellt sicher, dass die richtigen Komponenten und Parameter verwendet werden. Sie enthält detaillierte Anleitungen, Fallstricke (z. B. zur Groß-/Kleinschreibung von Spaltennamen, zur Behandlung von kategorialen Variablen, zum Umgang mit dem `weights`-Parameter) sowie Referenzvorlagen für überwachte und unüberwachte Szenarien. Die Fähigkeit deckt häufige Variationen wie Risikoindizes, Marktpotenzialbewertungen und Resilienzindizes ab und ist damit ein umfassendes Werkzeug für räumliche Analysen und Entscheidungsunterstützung auf Basis von zusammengesetzten Scores.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Verwenden Sie diese Fähigkeit, wenn der Benutzer einen Composite Score, Index oder eine multivariate Rangliste in einem CARTO-Workflow erstellen möchte.

Voraussetzungen: Laden Sie carto-create-workflow für den Entwicklungsprozess. Es deckt beide Zugangspfade ab – die Workflow-Werkzeuge des MCP-Servers (create_workflow, validate_workflow, run_workflow) wenn verbunden, andernfalls die CLI carto workflows. Routing-Signale: carto-basics/references/access-paths.md.

Anleitung

Schritt 1: Bestimmen des Scoring-Ansatzes

Fragen Sie den Benutzer den folgenden Entscheidungsbaum ab:

  1. "Haben Sie eine Ziel-/Ergebnisvariable?" (z. B. Umsatz, Verkaufszahlen, Kriminalitätsrate)
    • Ja → Überwachte Methode mittels native.spatialcompositesupervised
  2. "Kein Ziel, aber haben Sie Expertenwissen über die Variablenbedeutung?" (d. h. benutzerdefinierte Gewichte)
    • 2a. Transparenz ist wichtiger als Knotenzahl → native.normalize pro Variable + native.selectexpression mit der gewichteten Summe direkt in SQL (a_norm * 0.5 + b_norm * 0.2 + c_norm * 0.3). Eingaben und Gewichte sind in Workflows inline einsehbar; jede normalisierte Spalte wird materialisiert; keine Abhängigkeit vom Analytics Toolbox. Verwenden, wenn Stakeholder die Formel sehen/prüfen müssen, oder wenn Sie nicht auf AT laufen.
    • 2b. Möchten Sie die AT-Pipeline (Skalierung, Aggregation, Bucketing) für sich erledigen lassen → native.spatialcompositeunsupervised mit scoring_method: CUSTOM_WEIGHTS. Ein Knoten, aber die Formel ist innerhalb der Komponente verborgen.
  3. "Kein Ziel, keine Gewichte?"
    • → Unüberwachte Methode mit ENTROPY oder FIRST_PC mittels native.spatialcompositeunsupervised

Erfolg: Sie haben identifiziert, welche Komponente und welche Scoring-Methode verwendet werden soll, bevor Sie die Pipeline entwerfen.

Schritt 2: Erstellen der Pipeline

Überwachte Pipeline (native.spatialcompositesupervised)

  1. Laden Sie den räumlichen Merkmalsdatensatz (vorindexiert auf H3 oder Quadbin)
  2. Laden Sie den Ziel-/Ergebnisdatensatz
  3. Verbinden Sie beide Datensätze über die räumliche Indexspalte
  4. Wählen Sie nur die relevanten Merkmalspalten aus (räumliche Indexspalte und Geometrie aus der Merkmalsauswahl entfernen – nur die tatsächlichen Merkmalsvariablen übergeben)
  5. Führen Sie native.spatialcompositesupervised mit Parametern aus:
    • model_type: LINEAR_REG
    • bucketize: EQUAL_INTERVALS_ZERO_CENTERED
    • n_buckets: 5
    • outlier_removal: true
    • r_squared_threshold: 0.4
  6. Ausgabe: Composite Score basierend auf Regressionsresiduen (identifiziert Gebiete, die im Vergleich zum Modell über-/unterdurchschnittlich abschneiden)

Erfolg: Der Workflow verbindet Merkmale mit der Zielvariable, wählt nur numerische Merkmalspalten aus und erzeugt einen residualbasierten Score pro räumlicher Zelle.

Unüberwachte Pipeline (native.spatialcompositeunsupervised)

  1. Laden Sie den räumlichen Merkmalsdatensatz
  2. Wählen Sie nur die relevanten Merkmalspalten aus
  3. Kodieren Sie kategoriale/ordinale Variablen mit native.casewhen in numerische Werte (z. B. "Low_density_urban" → 4, "High_density_urban" → 2)
  4. Kehren Sie optional Variablen um, bei denen höher = schlechter, indem Sie sie in der SELECT-Abfrage, die an die Komponente übergeben wird, mit -1 multiplizieren
  5. Führen Sie native.spatialcompositeunsupervised mit Parametern aus:
    • scoring_method: CUSTOM_WEIGHTS / ENTROPY / FIRST_PC
    • weights: erforderlich, falls CUSTOM_WEIGHTS. Das Wire-Format ist ein JSON-kodierter String von Tripeln [[<Spalte>, <Gewicht>, <umkehren>], ...] – Spalte ist der Name der Merkmalspalte, Gewicht ist ein numerisches Gewicht (intern normalisiert, sodass die Summe 1 ergibt), umkehren ist ein Boolean (true kehrt die Variable um, sodass höher = schlechter zu höher = besser wird, ohne dass ein CASE WHEN nötig ist). Beispiel: '[["population_density", 0.5, false], ["accident_rate", 0.5, true]]'. Keine Objekt-Map.
    • scaling: RANKING
    • aggregation: LINEAR
    • output: RETURN_RANGE mit Bereich [0, 1]
  6. Ausgabe: Composite-Index-Score pro Standort

Erfolg: Alle Eingabevariablen sind numerisch, die Variablenrichtungen sind ausgerichtet (höher = besser für den Score), und die Ausgabe ist ein normalisierter Score pro räumlicher Zelle.

Fallstricke

  • Provider-Groß-/Kleinschreibung & SQL-Dialekt. Diese Fähigkeit verwendet Kleinbuchstaben für Spaltennamen (BigQuery / Databricks / Postgres / Redshift Konvention). Auf Snowflake erscheinen nicht in Anführungszeichen gesetzte Bezeichner in GROSSBUCHSTABEN – referenzieren Sie POPULATION_DENSITY, ACCIDENT_RATE usw. in Gewichten, Ausdrücken und nachgelagertem SQL. Siehe carto-create-workflow/references/providers/<provider>.md für die Groß-/Kleinschreibungsregeln und SQL-Dialekt-Äquivalente.
  • Alle Eingabevariablen müssen numerisch sein, mit ausgerichteter Richtung. Kodieren Sie ordinale Zeichenketten ("niedrig"/"mittel"/"hoch") zuerst über CASE WHEN, und wo "höher ist schlechter", multiplizieren Sie mit -1 (oder setzen Sie das reverse-Flag), bevor das Scoring erfolgt – das Vergessen kehrt die Score-Bedeutung um.
  • Überwachter R-Quadrat-Schwellenwert (Standard 0.4) ist großzügig. Wenn die Modellanpassung schlecht ist, ist der residualbasierte Score hauptsächlich Rauschen. Überprüfen Sie die Modelldiagnostik.
  • Benutzerdefinierte Gewichte werden intern normalisiert, sodass die Summe 1 ergibt. Die Absolutwerte sind nicht wichtig, nur die Verhältnisse.
  • Überwachte Scores sind Residuen, keine Rohwerte. Der Score identifiziert Gebiete, die vom Modell ABWEICHEN, nicht Gebiete mit den höchsten Rohwerten.
  • Entfernen Sie die räumliche Indexspalte und die Geometrie aus der Merkmalsauswahl – übergeben Sie nur die tatsächlichen Merkmalsvariablen an die Scoring-Komponente.
  • weights Typ-Label ist falsch gemeldet. Das Komponentenschema (via read_workflow_components MCP oder carto workflows components get native.spatialcompositeunsupervised --json) listet weights als type: "ColumnNumber", aber die tatsächliche Wire-Form ist ein ColumnAndNumber JSON-kodierter String von Tripeln [[<Spalte>, <Gewicht>, <umkehren>], ...] (siehe Schritt 2 oben). Vertrauen Sie dieser Fähigkeit und den Referenzvorlagen mehr als dem gemeldeten Typ-Label.
  • indexcol.allowedColumns ist ein UI-Hinweis, kein Validator. Das Schema listet ["geoid", "h3", "quadbin"] für native.spatialcompositeunsupervised.indexcol, aber es ist ein Workflows-Dropdown-Hinweis – jeder eindeutige Bezeichner funktioniert zur Laufzeit (z. B. store_id, cell_id).

Referenzvorlagen

Beide Beispiele verwenden Mailand-Raummerkmalsdaten auf Quadbin-Auflösung 18.

VorlageKomponenteDatei
Überwacht – Identifizierung resilienter Nachbarschaftennative.spatialcompositesupervisedcomposite-score-supervised.json
Unüberwacht – Marktpotenzial-Scoringnative.spatialcompositeunsupervisedcomposite-score-unsupervised.json

Häufige Variationen

VariationAnsatz
Risikoindex (Überschwemmung, Kriminalität usw.)Unüberwacht mit CUSTOM_WEIGHTS; Variablen umkehren, bei denen höher = sicherer
Marktpotenzial / StandortbewertungUnüberwacht mit CUSTOM_WEIGHTS oder ENTROPY; nachfrageseitige Variablen höher gewichten
ResilienzindexÜberwacht mit Ergebnisvariable (z. B. Umsatzänderung); Residuen zeigen Über-/Unterperformer
Datengetriebener Index (kein Domänenwissen)Unüberwacht mit FIRST_PC oder ENTROPY, damit die Varianz die Gewichte bestimmt
Human Development / zusammengesetzter IndikatorUnüberwacht mit CUSTOM_WEIGHTS und RANKING-Skalierung für ordinalsichere Aggregation

Individual skills in this repo

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

Verwandte Skills