@nomadamas/k-skill 0.1.0

package/skills/seoul-bike/scripts/seoul_bike.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""Single-entrypoint CLI for the seoul-bike skill.
+
+Subcommands:
+  nearby --lat LAT --lon LON   — find realtime Seoul Bike stations near coordinates
+  search KEYWORD               — search station names in realtime availability page(s)
+  realtime                     — fetch raw realtime station availability
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+for _stream in (sys.stdout, sys.stderr):
+    reconfigure = getattr(_stream, "reconfigure", None)
+    if reconfigure is not None:
+        try:
+            reconfigure(encoding="utf-8")
+        except (OSError, ValueError):
+            pass
+
+TIMEOUT_SEC = 15
+PROXY_BASE_URL_NAME = "KSKILL_PROXY_BASE_URL"
+DEFAULT_PROXY_BASE_URL = "https://k-skill-proxy.nomadamas.org"
+PROXY_DOWN_MSG = "설정된 k-skill-proxy 서버가 응답하지 않습니다. 잠시 후 재시도하거나 운영자에게 문의하세요."
+PROXY_KEY_NOT_CONFIGURED_MSG = "k-skill-proxy에 필요한 API 키가 설정되어 있지 않습니다. 운영자에게 문의하세요."
+
+
+def get_proxy_base_url() -> str:
+    value = os.environ.get(PROXY_BASE_URL_NAME)
+    if value and value.strip() and value.strip() != "replace-me":
+        return value.strip().rstrip("/")
+    return DEFAULT_PROXY_BASE_URL
+
+
+def fetch_json(path: str, params: dict[str, Any]) -> dict[str, Any]:
+    query = urllib.parse.urlencode(params)
+    url = f"{get_proxy_base_url()}{path}?{query}"
+    req = urllib.request.Request(url, headers={"User-Agent": "k-skill/seoul-bike"})
+    with urllib.request.urlopen(req, timeout=TIMEOUT_SEC) as resp:
+        raw = resp.read().decode("utf-8")
+    return json.loads(raw)
+
+
+def _to_int(value: Any) -> int | None:
+    if value in (None, ""):
+        return None
+    try:
+        return int(float(value))
+    except (TypeError, ValueError):
+        return None
+
+
+def normalize_realtime_row(row: dict[str, Any]) -> dict[str, Any]:
+    rack_total = _to_int(row.get("rackTotCnt") or row.get("rack_total_count"))
+    available = _to_int(row.get("parkingBikeTotCnt") or row.get("available_bikes"))
+    empty_docks = None if rack_total is None or available is None else max(0, rack_total - available)
+    return {
+        "station_id": row.get("stationId") or row.get("station_id"),
+        "station_name": row.get("stationName") or row.get("station_name"),
+        "rack_total_count": rack_total,
+        "available_bikes": available,
+        "empty_docks": empty_docks,
+        "shared_percent": _to_int(row.get("shared") or row.get("shared_percent")),
+        "latitude": row.get("stationLatitude") or row.get("latitude"),
+        "longitude": row.get("stationLongitude") or row.get("longitude"),
+    }
+
+
+def realtime_rows(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    status = payload.get("rentBikeStatus") or {}
+    rows = status.get("row") or []
+    return rows if isinstance(rows, list) else []
+
+
+def filter_realtime_rows(payload: dict[str, Any], keyword: str, limit: int) -> list[dict[str, Any]]:
+    normalized_keyword = keyword.strip().lower()
+    matches: list[dict[str, Any]] = []
+    for row in realtime_rows(payload):
+        station_name = str(row.get("stationName") or row.get("station_name") or "")
+        if normalized_keyword in station_name.lower():
+            matches.append(normalize_realtime_row(row))
+            if len(matches) >= limit:
+                break
+    return matches
+
+
+def format_station(item: dict[str, Any]) -> str:
+    distance = item.get("distance_m")
+    distance_text = f", 거리 {distance}m" if distance is not None else ""
+    bikes = item.get("available_bikes")
+    docks = item.get("empty_docks")
+    bikes_text = "알 수 없음" if bikes is None else f"{bikes}대"
+    docks_text = "알 수 없음" if docks is None else f"{docks}개"
+    return f"- {item.get('station_name')}: 대여 가능 {bikes_text}, 빈 거치대 {docks_text}{distance_text}"
+
+
+def format_nearby(payload: dict[str, Any]) -> list[str]:
+    query = payload.get("query") or {}
+    lines = [
+        f"따릉이 주변 대여소 {payload.get('count', 0)}곳",
+        f"기준 좌표: {query.get('latitude')}, {query.get('longitude')} / 반경 {query.get('radius_m')}m",
+    ]
+    for item in payload.get("items") or []:
+        lines.append(format_station(item))
+    requested_at = (payload.get("proxy") or {}).get("requested_at")
+    if requested_at:
+        lines.append(f"조회 시각: {requested_at}")
+    return lines
+
+
+def cmd_nearby(args: argparse.Namespace) -> int:
+    payload = fetch_json(
+        "/v1/seoul-bike/nearby",
+        {"lat": args.lat, "lon": args.lon, "radius_m": args.radius_m, "limit": args.limit},
+    )
+    if args.json:
+        json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+    else:
+        print("\n".join(format_nearby(payload)))
+    return 0
+
+
+def fetch_realtime_payload(start_index: int = 1, end_index: int = 1000) -> dict[str, Any]:
+    rows: list[dict[str, Any]] = []
+    current_start = start_index
+    page_size = max(1, end_index - start_index + 1)
+    requested_at = None
+
+    while True:
+        current_end = current_start + page_size - 1
+        payload = fetch_json(
+            "/v1/seoul-bike/realtime",
+            {"startIndex": current_start, "endIndex": current_end},
+        )
+        if requested_at is None:
+            requested_at = (payload.get("proxy") or {}).get("requested_at")
+        page_rows = realtime_rows(payload)
+        rows.extend(page_rows)
+
+        total_count = _to_int((payload.get("rentBikeStatus") or {}).get("list_total_count"))
+        if total_count is None or current_end >= total_count or not page_rows:
+            break
+        current_start = current_end + 1
+
+    return {
+        "rentBikeStatus": {"row": rows},
+        "proxy": {"requested_at": requested_at},
+    }
+
+
+def fetch_realtime_pages(start_index: int = 1, end_index: int = 1000) -> list[dict[str, Any]]:
+    return realtime_rows(fetch_realtime_payload(start_index, end_index))
+
+
+def cmd_search(args: argparse.Namespace) -> int:
+    payload = fetch_realtime_payload(args.start_index, args.end_index)
+    matches = filter_realtime_rows(payload, args.keyword, args.limit)
+    if args.json:
+        json.dump({"keyword": args.keyword, "count": len(matches), "items": matches, "proxy": payload.get("proxy")}, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+    else:
+        if not matches:
+            print(f"'{args.keyword}'와 일치하는 따릉이 대여소가 없습니다.", file=sys.stderr)
+            return 1
+        print(f"따릉이 대여소 검색: {args.keyword}")
+        for item in matches:
+            print(format_station(item))
+        requested_at = (payload.get("proxy") or {}).get("requested_at")
+        if requested_at:
+            print(f"조회 시각: {requested_at}")
+    return 0
+
+
+def cmd_realtime(args: argparse.Namespace) -> int:
+    payload = fetch_json(
+        "/v1/seoul-bike/realtime",
+        {"startIndex": args.start_index, "endIndex": args.end_index},
+    )
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="서울 따릉이 실시간 대여소 조회")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    nearby = sub.add_parser("nearby", help="좌표 주변 대여소 조회")
+    nearby.add_argument("--lat", required=True, type=float)
+    nearby.add_argument("--lon", required=True, type=float)
+    nearby.add_argument("--radius-m", type=int, default=500)
+    nearby.add_argument("--limit", type=int, default=10)
+    nearby.add_argument("--json", action="store_true")
+    nearby.set_defaults(func=cmd_nearby)
+
+    search = sub.add_parser("search", help="실시간 대여소 이름 검색")
+    search.add_argument("keyword")
+    search.add_argument("--start-index", type=int, default=1)
+    search.add_argument("--end-index", type=int, default=1000, help="page size end index for the first realtime page; search continues through all pages")
+    search.add_argument("--limit", type=int, default=10)
+    search.add_argument("--json", action="store_true")
+    search.set_defaults(func=cmd_search)
+
+    realtime = sub.add_parser("realtime", help="실시간 대여소 원문 JSON 조회")
+    realtime.add_argument("--start-index", type=int, default=1)
+    realtime.add_argument("--end-index", type=int, default=1000)
+    realtime.set_defaults(func=cmd_realtime)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        try:
+            payload = json.loads(body)
+        except json.JSONDecodeError:
+            payload = None
+        if exc.code == 503 and isinstance(payload, dict) and payload.get("error") == "upstream_not_configured":
+            print(PROXY_KEY_NOT_CONFIGURED_MSG, file=sys.stderr)
+        elif isinstance(payload, dict) and payload.get("message"):
+            print(str(payload["message"]), file=sys.stderr)
+        else:
+            print(f"API HTTP 오류: {exc.code} {exc.reason}", file=sys.stderr)
+        return 1
+    except urllib.error.URLError as exc:
+        print(f"{PROXY_DOWN_MSG} (상세: {exc.reason})", file=sys.stderr)
+        return 1
+    except json.JSONDecodeError as exc:
+        print(f"API 응답 JSON 파싱 실패: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/seoul-bike/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "seoul-bike",
+  "description": "서울 따릉이 실시간 대여소의 대여 가능 자전거와 빈 거치대를 좌표 주변 또는 대여소 이름으로 조회한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: seoul-bike\ndescription: 서울 따릉이 실시간 대여소의 대여 가능 자전거와 빈 거치대를 좌표 주변 또는 대여소 이름으로 조회한다.\nlicense: MIT\nmetadata:\n  category: transit\n  locale: ko-KR\n  phase: v1"
+}

package/skills/seoul-density/instruction.md

@@ -0,0 +1,109 @@
+# Seoul Density
+
+## What this skill does
+
+서울 실시간 도시데이터 API(data.seoul.go.kr)를 호출해 121개 핫스팟의 **현재 혼잡도 단계**(여유 / 보통 / 약간 붐빔 / 붐빔)와 **추정 인구 범위**를 반환한다.
+
+데이터는 KT·SKT 통신 신호 기반 추계치이며, 5분 주기로 갱신되나 호출 시점 기준 약 15분 전 값이다.
+
+## When to use
+
+- "지금 강남역 얼마나 붐벼?"
+- "홍대 지금 인파 어때?"
+- "명동 지금 사람 많아?"
+- "여의도한강공원 지금 여유로워?"
+
+## Prerequisites
+
+별도 API 키 발급 없이 그대로 쓸 수 있다. 모든 호출은 **k-skill-proxy 경유**다.
+
+- 기본 프록시 URL: `https://k-skill-proxy.nomadamas.org` — 프록시 서버가 `SEOUL_OPEN_API_KEY`를 보유하고 있어 사용자는 키 없이 호출만 하면 된다.
+- `KSKILL_PROXY_BASE_URL` 환경변수로 프록시 주소를 바꿀 수 있다(예: 별도 self-host 프록시).
+
+## Single entrypoint
+
+이 스킬의 모든 동작은 **단일 진입점**을 통한다. OS·CWD에 관계없이 동일하게 동작하도록 절대 경로 + Python launcher fallback을 사용한다:
+
+```bash
+# macOS / Linux / Git-bash
+python3 "$SKILL_DIR/scripts/seoul_density.py" <subcommand> [args]
+
+# Windows (PowerShell): py 런처 또는 python
+py -3 "$env:SKILL_DIR\scripts\seoul_density.py" <subcommand> [args]
+```
+
+`$SKILL_DIR`은 이 SKILL.md가 위치한 디렉토리다(`~/.claude/skills/seoul-density` 또는 레포의 `seoul-density/`). 호출 예시는 아래 Workflow 참조.
+
+첫 사용 시 `Bash(python3 *seoul_density.py:*)` (또는 PowerShell 환경에서 `PowerShell(py -3 *seoul_density.py*)`) 패턴 한 번만 승인하면 이후 호출은 모두 자동 허용된다. 외부 dependency는 없고 Python 표준 라이브러리만 사용한다.
+
+### Subcommands
+
+| 명령 | 설명 |
+|------|------|
+| `list [--json]` | 지원 121개 장소 목록 (카테고리별) |
+| `match <키워드> [--limit N] [--json]` | 사용자 입력 → 지원 장소명 매칭 |
+| `query <장소명> [--json]` | 실시간 혼잡도/인구 조회 (사람이 읽는 요약 또는 JSON) |
+
+## Workflow
+
+### 1. 모호한 입력은 match로 후보 확인 (선택)
+
+사용자가 "홍대 인파"처럼 모호하게 말하면 먼저 후보를 확인한다.
+
+```bash
+python3 "$SKILL_DIR/scripts/seoul_density.py" match "홍대" --json
+# → ["홍대 관광특구", "홍대입구역(2호선)"]
+```
+
+후보가 1개면 바로 `query`로 넘어가도 되고(스크립트가 자동 매칭), 여러 개면 어느 쪽인지 사용자에게 확인한다.
+
+### 2. 혼잡도 조회
+
+키워드 1개만 매칭되면 자동으로 보정한다.
+
+```bash
+# macOS / Linux / Git-bash
+python3 "$SKILL_DIR/scripts/seoul_density.py" query "강남역"
+
+# Windows PowerShell
+py -3 "$env:SKILL_DIR\scripts\seoul_density.py" query "강남역"
+```
+
+출력 예시:
+
+```
+장소: 강남역
+혼잡도: 약간 붐빔
+인구 추정: 24000~26000명
+기준 시각: 2026-05-14 09:30
+상황: 사람이 몰려있을 수 있어요
+```
+
+기계적 후처리가 필요하면 `--json` 플래그를 쓴다:
+
+```bash
+python3 "$SKILL_DIR/scripts/seoul_density.py" query "강남역" --json
+```
+
+자동 매칭을 끄고 싶으면 `--no-auto`를 쓴다.
+
+## Done when
+
+- 장소명, 혼잡도 단계, 추정 인구 범위(최소~최대), 기준 시각, 혼잡도 메시지를 사용자에게 전달했다.
+
+## Failure modes
+
+| 상황 | 동작 |
+|------|------|
+| 프록시 정상 응답 | 별도 키 불필요, 즉시 결과 반환 |
+| 지원하지 않는 장소명 (`exit 1`) | `match` 결과로 후보 제안 |
+| 프록시 HTTP/네트워크 오류 (`exit 1`) | stderr에 사유 출력, `KSKILL_PROXY_BASE_URL` 점검 또는 5분 후 재시도 안내 |
+| 새벽 01~05시 빈 응답 | 실시간 데이터 미제공 시간대임을 안내 |
+| 일일 할당량 초과 | 다음 날 재시도 안내 |
+
+## Notes
+
+- 인구 수치는 실제값이 아닌 **추계치** (KT·SKT 통신 신호 데이터 기반).
+- 데이터는 호출 시점 기준 **약 15분 전** 값.
+- 단일 진입점 외에 `curl`, `python3 -c`, `source` 같은 inline 명령을 직접 실행하지 말 것. 그렇게 하면 사용자가 매번 별도 승인을 받아야 한다.
+- 새 카테고리/장소가 추가되면 `seoul-density/scripts/seoul_density.py`의 `AREAS` 딕셔너리만 갱신한다.

package/skills/seoul-density/scripts/seoul_density.py

@@ -0,0 +1,271 @@
+"""Single-entrypoint CLI for the seoul-density skill.
+
+All skill operations route through `python3 seoul-density/scripts/seoul_density.py <subcommand>`
+so users only have to approve one Bash pattern on first use.
+
+Subcommands:
+  list                       — print supported area names grouped by category
+  match <keyword>            — fuzzy-match a user keyword to a supported area name
+  query <area-name> [--json] — fetch and summarize real-time density for the area
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+import urllib.parse
+from typing import Any
+
+for _stream in (sys.stdout, sys.stderr):
+    reconfigure = getattr(_stream, "reconfigure", None)
+    if reconfigure is not None:
+        try:
+            reconfigure(encoding="utf-8")
+        except (OSError, ValueError):
+            pass
+
+
+AREAS: dict[str, list[str]] = {
+    "고궁·문화유산": [
+        "경복궁", "광화문·덕수궁", "보신각", "서울 암사동 유적", "창덕궁·종묘",
+    ],
+    "관광특구": [
+        "강남 MICE 관광특구", "동대문 관광특구", "명동 관광특구", "이태원 관광특구",
+        "잠실 관광특구", "종로·청계 관광특구", "홍대 관광특구",
+    ],
+    "공원": [
+        "강서한강공원", "고척돔", "광나루한강공원", "광화문광장",
+        "국립중앙박물관·용산가족공원", "난지한강공원", "남산공원", "노들섬",
+        "뚝섬한강공원", "망원한강공원", "반포한강공원", "보라매공원",
+        "북서울꿈의숲", "서대문독립공원", "서리풀공원·몽마르뜨공원", "서울대공원",
+        "서울숲공원", "송현녹지광장", "아차산", "안양천", "양화한강공원",
+        "어린이대공원", "여의도한강공원", "여의서로", "올림픽공원", "월드컵공원",
+        "응봉산", "이촌한강공원", "잠실종합운동장", "잠실한강공원", "잠원한강공원",
+        "청계산", "홍제폭포",
+    ],
+    "발달상권": [
+        "가락시장", "가로수길", "광장(전통)시장", "김포공항", "남대문시장", "노량진",
+        "덕수궁길·정동길", "북창동 먹자골목", "북촌한옥마을", "서촌", "성수카페거리",
+        "송리단길·호수단길", "신촌 스타광장", "압구정로데오거리", "여의도", "연남동",
+        "영등포 타임스퀘어", "용리단길", "이태원 앤틱가구거리", "익선동", "인사동",
+        "잠실롯데타워·석촌호수", "창동 신경제 중심지", "청담동 명품거리",
+        "청량리 제기동 일대 전통시장", "해방촌·경리단길", "DDP(동대문디자인플라자)",
+        "DMC(디지털미디어시티)",
+    ],
+    "인구밀집지역": [
+        "가산디지털단지역", "강남역", "건대입구역", "고덕역", "고속터미널역", "교대역",
+        "구로디지털단지역", "구로역", "군자역", "대림역", "동대문역", "뚝섬역",
+        "미아사거리역", "발산역", "사당역", "삼각지역", "서울대입구역",
+        "서울식물원·마곡나루역", "서울역", "성신여대입구역", "선릉역", "시의회 앞",
+        "수유역", "신논현역·논현역", "신도림역", "신림역", "신촌·이대역", "쌍문역",
+        "신정네거리역", "역삼역", "연신내역", "양재역", "왕십리역", "용산역",
+        "오목교역·목동운동장", "잠실새내역", "잠실역", "장지역", "장한평역", "천호역",
+        "총신대입구(이수)역", "충정로역", "합정역", "혜화역", "홍대입구역(2호선)",
+        "회기역",
+    ],
+}
+
+
+TIMEOUT_SEC = 10
+PROXY_BASE_URL_NAME = "KSKILL_PROXY_BASE_URL"
+DEFAULT_PROXY_BASE_URL = "https://k-skill-proxy.nomadamas.org"
+PROXY_DOWN_MSG = "설정된 k-skill-proxy 서버가 응답하지 않습니다. 잠시 후 재시도하거나 운영자에게 문의하세요."
+PROXY_KEY_NOT_CONFIGURED_MSG = "k-skill-proxy에 필요한 API 키가 설정되어 있지 않습니다. 운영자에게 문의하세요."
+
+
+def all_areas() -> list[str]:
+    return [name for group in AREAS.values() for name in group]
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    if args.json:
+        json.dump(AREAS, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+        return 0
+    for category, names in AREAS.items():
+        print(f"## {category} ({len(names)}곳)")
+        print(", ".join(names))
+        print()
+    return 0
+
+
+def _normalize(text: str) -> str:
+    """Strip whitespace and common location suffixes for loose matching."""
+    cleaned = "".join(ch for ch in text if not ch.isspace())
+    for suffix in ("관광특구", "한강공원", "공원", "시장", "역", "거리", "광장"):
+        if cleaned.endswith(suffix) and len(cleaned) > len(suffix):
+            cleaned = cleaned[: -len(suffix)]
+            break
+    return cleaned
+
+
+def fuzzy_match(keyword: str, limit: int = 5) -> list[str]:
+    names = all_areas()
+    keyword = keyword.strip()
+    if not keyword:
+        return []
+
+    exact = [n for n in names if keyword in n]
+    if exact:
+        return exact[:limit]
+
+    contained = [n for n in names if n in keyword]
+    if contained:
+        return contained[:limit]
+
+    norm_kw = _normalize(keyword)
+    if norm_kw:
+        loose = [n for n in names if norm_kw and (norm_kw in _normalize(n) or _normalize(n) in norm_kw)]
+        if loose:
+            return loose[:limit]
+
+    return difflib.get_close_matches(keyword, names, n=limit, cutoff=0.3)
+
+
+def cmd_match(args: argparse.Namespace) -> int:
+    matches = fuzzy_match(args.keyword, limit=args.limit)
+    if not matches:
+        print(f"'{args.keyword}'와 일치하는 지원 장소가 없습니다.", file=sys.stderr)
+        print("'python3 seoul-density/scripts/seoul_density.py list' 로 전체 목록을 확인하세요.", file=sys.stderr)
+        return 1
+    if args.json:
+        json.dump(matches, sys.stdout, ensure_ascii=False)
+        sys.stdout.write("\n")
+    else:
+        for name in matches:
+            print(name)
+    return 0
+
+
+def get_proxy_base_url() -> str:
+    value = os.environ.get(PROXY_BASE_URL_NAME)
+    if value and value != "replace-me":
+        return value.rstrip("/")
+    return DEFAULT_PROXY_BASE_URL
+
+
+def fetch_density_via_proxy(area: str) -> dict[str, Any]:
+    base_url = get_proxy_base_url()
+    query = urllib.parse.urlencode({"area": area})
+    url = f"{base_url}/v1/seoul-density/citydata?{query}"
+    req = urllib.request.Request(url, headers={"User-Agent": "k-skill/seoul-density"})
+    with urllib.request.urlopen(req, timeout=TIMEOUT_SEC) as resp:
+        raw = resp.read().decode("utf-8")
+    return json.loads(raw)
+
+
+def summarize(payload: dict[str, Any]) -> dict[str, Any]:
+    result = payload.get("RESULT") or {}
+    code = result.get("RESULT.CODE")
+    message = result.get("RESULT.MESSAGE", "")
+    if code and code != "INFO-000":
+        raise RuntimeError(f"API 오류: {code} {message}".strip())
+
+    rows = payload.get("SeoulRtd.citydata_ppltn") or []
+    if not rows:
+        raise RuntimeError("인구 데이터가 없습니다. 장소명을 'match' 서브커맨드로 확인하세요.")
+
+    row = rows[0]
+    return {
+        "area": row.get("AREA_NM"),
+        "congestion_level": row.get("AREA_CONGEST_LVL"),
+        "population_min": row.get("AREA_PPLTN_MIN"),
+        "population_max": row.get("AREA_PPLTN_MAX"),
+        "as_of": row.get("PPLTN_TIME"),
+        "message": row.get("AREA_CONGEST_MSG"),
+    }
+
+
+def cmd_query(args: argparse.Namespace) -> int:
+    area = args.area.strip()
+    if area not in all_areas():
+        suggestions = fuzzy_match(area, limit=3)
+        if len(suggestions) == 1 and getattr(args, "auto", True):
+            print(f"'{area}' → '{suggestions[0]}' 로 자동 매칭", file=sys.stderr)
+            area = suggestions[0]
+        else:
+            hint = (
+                f" 가까운 후보: {', '.join(suggestions)}" if suggestions else ""
+            )
+            print(f"지원하지 않는 장소: {area}{hint}", file=sys.stderr)
+            return 1
+
+    try:
+        payload = fetch_density_via_proxy(area)
+        summary = summarize(payload)
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        try:
+            payload = json.loads(body)
+        except json.JSONDecodeError:
+            payload = None
+        if exc.code == 503 and isinstance(payload, dict) and payload.get("error") == "upstream_not_configured":
+            print(PROXY_KEY_NOT_CONFIGURED_MSG, file=sys.stderr)
+        elif isinstance(payload, dict) and payload.get("message"):
+            print(str(payload["message"]), file=sys.stderr)
+        else:
+            print(f"API HTTP 오류: {exc.code} {exc.reason}", file=sys.stderr)
+        return 1
+    except urllib.error.URLError as exc:
+        print(f"{PROXY_DOWN_MSG} (상세: {exc.reason})", file=sys.stderr)
+        return 1
+    except (RuntimeError, json.JSONDecodeError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    if args.json:
+        json.dump(summary, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+        return 0
+
+    print(f"장소: {summary['area']}")
+    print(f"혼잡도: {summary['congestion_level']}")
+    print(f"인구 추정: {summary['population_min']}~{summary['population_max']}명")
+    print(f"기준 시각: {summary['as_of'] or '알 수 없음'}")
+    print(f"상황: {summary['message']}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="seoul_density",
+        description="서울 실시간 도시데이터(혼잡도/인구) 단일 진입점 CLI",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_list = sub.add_parser("list", help="지원 장소 목록 출력")
+    p_list.add_argument("--json", action="store_true")
+    p_list.set_defaults(func=cmd_list)
+
+    p_match = sub.add_parser("match", help="키워드 → 지원 장소명 매칭")
+    p_match.add_argument("keyword")
+    p_match.add_argument("--limit", type=int, default=5)
+    p_match.add_argument("--json", action="store_true")
+    p_match.set_defaults(func=cmd_match)
+
+    p_query = sub.add_parser("query", help="장소 혼잡도 조회")
+    p_query.add_argument("area", help="지원 장소명 (목록은 'list' 참조)")
+    p_query.add_argument("--json", action="store_true")
+    p_query.add_argument(
+        "--no-auto",
+        dest="auto",
+        action="store_false",
+        help="후보가 1개뿐이어도 자동 매칭하지 않음",
+    )
+    p_query.set_defaults(func=cmd_query, auto=True)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/seoul-density/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "seoul-density",
+  "description": "서울 주요 121개 핫스팟 장소의 실시간 혼잡도와 인구 현황을 조회한다. 지금 강남역이 얼마나 붐비는지, 홍대 인파가 얼마나 되는지 물어볼 때 사용한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: seoul-density\ndescription: 서울 주요 121개 핫스팟 장소의 실시간 혼잡도와 인구 현황을 조회한다. 지금 강남역이 얼마나 붐비는지, 홍대 인파가 얼마나 되는지 물어볼 때 사용한다.\nlicense: MIT\nmetadata:\n  category: utility\n  locale: ko-KR\n  phase: v1"
+}