Communitygithub.com

CartoDB/agent-skills

사용자가 합성 점수, 지수, 다중 변수 순위 지정, PCA, 지도/비지도 점수 매기기 등에 대해 질문할 때 CARTO 워크플로우에서 합성 점수 워크플로우를 구축하도록 안내합니다.

agent-skills란 무엇인가요?

이 스킬은 AI 에이전트(예: Claude Code, Cursor, Codex 등)가 CARTO 워크플로우 내에서 합성 점수(Composite Score) 또는 다중 변수 순위(Ranking) 시스템을 구축할 때 필요한 전체 프로세스를 안내합니다. 사용자가

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

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

사용자가 CARTO 워크플로우에서 합성 점수(composite score), 지수(index), 또는 다중 변수 순위(multi-variable ranking)를 만들고자 할 때 이 스킬을 사용하세요.

사전 조건: 개발 과정에서 carto-create-workflow를 로드하세요. 이는 MCP 서버의 워크플로우 도구(create_workflow, validate_workflow, run_workflow)가 연결되어 있을 때와 그렇지 않을 때 carto workflows CLI의 두 가지 접근 경로를 모두 다룹니다. 라우팅 신호: carto-basics/references/access-paths.md.

지침

1단계: 점수 매기기 접근 방식 결정

사용자에게 다음과 같은 결정 트리를 질문하세요:

  1. "목표/결과 변수(target/outcome variable)가 있습니까?" (예: 수익, 매출, 범죄율)
    • 예 → 지도(Supervised) 방법: native.spatialcompositesupervised 사용
  2. "목표 변수는 없지만, 변수의 중요도에 대한 전문가 지식이 있습니까?" (즉, 사용자 정의 가중치)
    • 2a. 투명성(Transparency)이 노드 수보다 중요함 → 변수별로 native.normalize를 수행하고, 가중 합을 SQL에 직접 작성한 native.selectexpression 사용 (예: a_norm * 0.5 + b_norm * 0.2 + c_norm * 0.3). 입력과 가중치는 Workflows에서 인라인으로 검사 가능하며, 각 정규화된 컬럼은 구체화(materialize)됩니다. Analytics Toolbox에 의존하지 않습니다. 이해관계자가 공식을 보고 감사(audit)해야 할 때, 또는 AT를 사용하지 않을 때 사용하세요.
    • 2b. AT 파이프라인(스케일링, 집계, 버킷팅)을 자동으로 처리하기를 원함 → scoring_method: CUSTOM_WEIGHTS와 함께 native.spatialcompositeunsupervised 사용. 하나의 노드이지만 공식은 구성 요소 내부에 숨겨져 있습니다.
  3. "목표 변수도, 가중치도 없습니까?"
    • → ENTROPY 또는 FIRST_PC와 함께 비지도(Unsupervised) 방법 사용: native.spatialcompositeunsupervised

성공: 파이프라인을 설계하기 전에 어떤 구성 요소와 점수 매기기 방법을 사용할지 식별했습니다.

2단계: 파이프라인 구축

지도 파이프라인 (native.spatialcompositesupervised)

  1. 공간 특성 데이터셋 로드 (H3 또는 Quadbin에서 사전 색인화됨)
  2. 목표/결과 데이터셋 로드
  3. 공간 인덱스 컬럼을 기준으로 두 데이터셋 조인
  4. 관련 특성 컬럼만 선택 (공간 인덱스 컬럼과 지오메트리는 특성 선택에서 제외 — 실제 특성 변수만 전달)
  5. 매개변수와 함께 native.spatialcompositesupervised 실행:
    • model_type: LINEAR_REG
    • bucketize: EQUAL_INTERVALS_ZERO_CENTERED
    • n_buckets: 5
    • outlier_removal: true
    • r_squared_threshold: 0.4
  6. 출력: 회귀 잔차 기반 합성 점수 (모델 대비 과대/과소 성능 지역 식별)

성공: 워크플로우가 특성과 목표 변수를 조인하고, 숫자 특성 컬럼만 선택하며, 공간 셀당 잔차 기반 점수를 생성합니다.

비지도 파이프라인 (native.spatialcompositeunsupervised)

  1. 공간 특성 데이터셋 로드
  2. 관련 특성 컬럼만 선택
  3. native.casewhen을 사용하여 범주형/순서형 변수를 숫자로 인코딩 (예: "Low_density_urban" → 4, "High_density_urban" → 2)
  4. 선택적으로 값이 클수록 나쁜 변수는 구성 요소에 전달되는 SELECT 쿼리에서 -1을 곱하여 방향을 반전시킴
  5. 매개변수와 함께 native.spatialcompositeunsupervised 실행:
    • scoring_method: CUSTOM_WEIGHTS / ENTROPY / FIRST_PC
    • weights: CUSTOM_WEIGHTS인 경우 필수. 전선 형식은 삼중항(triples)의 JSON 인코딩 문자열 [[<column>, <weight>, <reverse>], ...] — column은 특성 컬럼 이름, weight는 숫자 가중치(내부적으로 합이 1이 되도록 정규화됨), reverse는 부울 값(true는 CASE WHEN 없이 값이 클수록 나쁨을 값이 클수록 좋음으로 반전시킴). 예: '[["population_density", 0.5, false], ["accident_rate", 0.5, true]]'. 객체 맵(object map)이 아닙니다.
    • scaling: RANKING
    • aggregation: LINEAR
    • output: RETURN_RANGE, 범위 [0, 1]
  6. 출력: 위치별 합성 지수 점수

성공: 모든 입력 변수가 숫자이고, 변수 방향이 정렬되었으며(값이 클수록 점수에 좋음), 출력은 공간 셀당 정규화된 점수입니다.

주의 사항 (Gotchas)

  • 공급자(Provider) 대소문자 규칙 및 SQL 방언. 이 스킬은 소문자 컬럼명(BigQuery / Databricks / Postgres / Redshift 규칙)을 사용합니다. Snowflake에서는 따옴표 없는 식별자가 대문자로 표시됩니다 — 가중치, 표현식 및 다운스트림 SQL에서 POPULATION_DENSITY, ACCIDENT_RATE 등을 참조하세요. 대소문자 규칙과 SQL 방언 동등 항목은 carto-create-workflow/references/providers/<provider>.md를 참조하세요.
  • 모든 입력 변수는 숫자여야 하며, 방향이 정렬되어야 합니다. 먼저 CASE WHEN을 통해 순서형 문자열("low"/"medium"/"high")을 인코딩하고, "값이 클수록 나쁨"인 경우 점수 매기기 전에 -1을 곱하거나(또는 reverse 플래그 설정) 하세요 — 이를 잊으면 점수 의미가 반전됩니다.
  • 지도 학습 R-제곱 임계값(기본값 0.4)은 관대합니다. 모델 적합도가 낮으면 잔차 기반 점수는 대부분 잡음입니다. 모델 진단을 검사하세요.
  • 사용자 정의 가중치는 내부적으로 합이 1이 되도록 정규화됩니다. 절대값은 중요하지 않으며, 비율만 중요합니다.
  • 지도 학습 점수는 잔차(residuals)입니다. 원시 값이 아닙니다. 점수는 모델에서 벗어난(DEVIATE) 영역을 식별하며, 원시 값이 가장 높은 영역을 식별하지 않습니다.
  • 특성 선택에서 공간 인덱스 컬럼과 지오메트리를 제거하세요 — 점수 매기기 구성 요소에 실제 특성 변수만 전달하세요.
  • weights 유형 레이블이 잘못 보고됩니다. 구성 요소 스키마(read_workflow_components MCP 또는 carto workflows components get native.spatialcompositeunsupervised --json 통해)는 weights를 type: "ColumnNumber"로 나열하지만, 실제 전선 형태는 삼중항의 ColumnAndNumber JSON 인코딩 문자열 [[<column>, <weight>, <reverse>], ...]입니다(위 2단계 참조). 보고된 유형 레이블보다 이 스킬과 참조 템플릿을 신뢰하세요.
  • indexcol.allowedColumns는 UI 힌트일 뿐, 유효성 검사기가 아닙니다. 스키마는 native.spatialcompositeunsupervised.indexcol에 대해 ["geoid", "h3", "quadbin"]을 나열하지만, 이는 Workflows 드롭다운 힌트입니다 — 런타임에는 고유 식별자 컬럼(예: store_id, cell_id)이 작동합니다.

참조 템플릿 (Reference Templates)

두 예제 모두 Quadbin 해상도 18의 밀라노(Milan) 공간 특성 데이터를 사용합니다.

템플릿구성 요소파일
지도 학습 — 회복력 있는 지역 식별native.spatialcompositesupervisedcomposite-score-supervised.json
비지도 학습 — 시장 잠재력 점수 매기기native.spatialcompositeunsupervisedcomposite-score-unsupervised.json

일반적인 변형 (Common Variations)

변형접근 방식
위험 지수 (홍수, 범죄 등)CUSTOM_WEIGHTS와 함께 비지도 학습; 값이 클수록 안전한 변수는 방향 반전
시장 잠재력 / 부지 점수 매기기CUSTOM_WEIGHTS 또는 ENTROPY와 함께 비지도 학습; 수요 측 변수에 더 높은 가중치 부여
회복력 지수결과 변수(예: 수익 변화)와 함께 지도 학습; 잔차가 과대/과소 성과 지역을 드러냄
데이터 기반 지수 (도메인 전문 지식 없음)FIRST_PC 또는 ENTROPY와 함께 비지도 학습; 분산이 가중치를 결정하도록 함
인간 개발 / 합성 지표CUSTOM_WEIGHTS 및 RANKING 스케일링과 함께 비지도 학습; 순서형 안전 집계를 위해 사용

Individual skills in this repo

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

관련 스킬