@nomadamas/k-skill 0.1.0

package/skills/gov-overseas-trip-report/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "gov-overseas-trip-report",
+  "description": "선관위·권익위·정보공개포털·주요 지방의회 등 검증된 공개 표면에서 공무국외출장/국외훈련 보고서·현황을 조회하고, 첨부 원문이 있으면 kordoc으로 사실·공개성·검토 신호만 구조화한다. 부정부패 판정 도구가 아니다.",
+  "profiles": [
+    "browser",
+    "lookup"
+  ],
+  "frontmatter": "name: gov-overseas-trip-report\ndescription: 선관위·권익위·정보공개포털·주요 지방의회 등 검증된 공개 표면에서 공무국외출장/국외훈련 보고서·현황을 조회하고, 첨부 원문이 있으면 kordoc으로 사실·공개성·검토 신호만 구조화한다. 부정부패 판정 도구가 아니다.\nlicense: MIT\nmetadata:\n  category: civic\n  locale: ko-KR\n  phase: v1"
+}

package/skills/han-river-water-level/instruction.md

@@ -0,0 +1,83 @@
+# Han River Water Level
+
+## What this skill does
+
+기본적으로 `https://k-skill-proxy.nomadamas.org/v1/han-river/water-level` 로 요청해서 현재 수위와 유량을 요약한다.
+
+## When to use
+
+- "한강대교 지금 수위 어때?"
+- "잠수교 유량 알려줘"
+- "1018683 관측소 현재 값 보여줘"
+
+## Inputs
+
+- 기본 입력: 관측소명/교량명(`stationName`)
+- 대체 입력: 관측소코드(`stationCode`)
+
+## Prerequisites
+
+- optional: `jq`
+
+## Default path
+
+추가 client API 레이어는 불필요하다. 그냥 프록시 서버에 HTTP 요청만 넣으면 된다.
+
+사용자는 별도 HRFCO `ServiceKey` 를 준비할 필요가 없다. upstream key는 proxy 서버에서만 주입한다.
+
+`KSKILL_PROXY_BASE_URL` 환경변수가 있으면 그 값을 사용하고, 없으면 기본 경로 `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+
+## Example requests
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/han-river/water-level' \
+  --data-urlencode 'stationName=한강대교'
+```
+
+관측소코드로 바로 조회해도 된다.
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/han-river/water-level' \
+  --data-urlencode 'stationCode=1018683'
+```
+
+## Keep the answer compact
+
+응답에는 아래만 먼저 정리한다.
+
+- 관측소명 / 관측소코드
+- 관측 시각
+- 현재 수위(m)
+- 현재 유량(m^3/s)
+- 기준 수위(관심/주의/경보/심각) 중 값이 있는 항목
+
+## Ambiguous station names
+
+입력이 너무 넓으면 proxy 는 `ambiguous_station` 과 함께 `candidate_stations` 를 돌려준다.
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/han-river/water-level' \
+  --data-urlencode 'stationName=한강'
+```
+
+이때는 후보 중 하나를 골라 다시 `stationName` 또는 `stationCode` 로 조회한다.
+
+## Detailed API paths
+
+구현 세부는 아래 문서만 참고한다.
+
+- `docs/features/han-river-water-level.md`
+- `docs/features/k-skill-proxy.md`
+
+## Failure modes
+
+- 관측소명이 너무 넓어서 여러 관측소가 동시에 잡히는 경우
+- 잘못된 관측소코드/관측소명으로 station lookup 이 실패하는 경우
+- 프록시 서버에 `HRFCO_OPEN_API_KEY` 가 비어 있는 경우
+- 실시간 자료 갱신 지연으로 최신 10분 자료가 비어 있는 경우
+
+## Notes
+
+- 기본 경로는 항상 `k-skill-proxy.nomadamas.org` 의 water-level endpoint 다.
+- upstream 은 `waterlevel/info.json` 으로 관측소 메타데이터를 찾고, `waterlevel/list/10M/{WLOBSCD}.json` 으로 최신값을 조회한다.
+- 결과는 원시자료 기반이므로 조회 시각을 함께 적는다.

package/skills/han-river-water-level/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "han-river-water-level",
+  "description": "한강홍수통제소 기반 현재 수위/유량을 관측소명 또는 관측소코드로 조회한다. 기본 경로는 k-skill-proxy의 han-river water-level endpoint다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: han-river-water-level\ndescription: 한강홍수통제소 기반 현재 수위/유량을 관측소명 또는 관측소코드로 조회한다. 기본 경로는 k-skill-proxy의 han-river water-level endpoint다.\nlicense: MIT\nmetadata:\n  category: utility\n  locale: ko-KR\n  phase: v1"
+}

package/skills/highway-traffic-status/instruction.md

@@ -0,0 +1,88 @@
+# 고속도로 교통량·소통·CCTV 조회
+
+## What this skill does
+
+- 한국도로공사 공공데이터포털(`data.ex.co.kr`)의 실시간 교통량 API로 전국 고속도로 콘존(구간)별 속도, 교통량, 소통등급(원활/서행/정체)을 조회한다.
+- 국가교통정보센터 ITS(`openapi.its.go.kr`)의 CCTV 정보 API로 좌표 범위 내 고속도로 CCTV 이름·좌표·HLS 스트림 URL을 조회한다.
+
+이 스킬은 **조회 전용**이다. 경로 안내, 내비게이션, 통행료 계산은 범위 밖이다.
+
+## When to use
+
+- "지금 경부고속도로 막혀?"
+- "서울 요금소 쪽 정체 상황 알려줘"
+- "서해안선 상행 소통 어때?"
+- "판교 근처 고속도로 CCTV 보여줘"
+
+## When not to use
+
+- 대중교통 길찾기 → `korean-transit-route`
+- 자동차 경로/내비게이션 → `kakao-map`
+- 시내 도로·일반국도 상세 소통 (v1은 고속도로 중심)
+
+## Prerequisites
+
+- Python 3.9+ (stdlib only, 외부 패키지 없음)
+- 사용자 API 키 **불필요** — 두 upstream 모두 공개 데모 키(`test`)로 동작함을 확인했다 (2026-07-21). 공개 엔드포인트이므로 k-skill-proxy를 경유하지 않고 직접 호출한다.
+
+선택 환경변수 (데모 키 회수/쿼터 대비):
+
+- `KSKILL_EXDATA_API_KEY` — data.ex.co.kr 개인 인증키 (https://data.ex.co.kr 회원가입 후 발급)
+- `KSKILL_ITS_API_KEY` — openapi.its.go.kr 개인 인증키 (https://www.its.go.kr/opendata)
+
+`~/.config/k-skill/secrets.env` 의 같은 이름 키도 읽는다.
+
+## Workflow
+
+### 1. 실시간 소통/교통량 조회
+
+```bash
+python3 highway-traffic-status/scripts/highway_traffic.py traffic --route 경부 --text
+```
+
+- `--route`: 노선명 일부(`경부`, `서해안`) 또는 노선번호(`0010`)
+- `--keyword`: 구간(콘존) 이름 키워드 (예: `서울TG`, `양재`)
+- `--limit N`: 출력 행 수 (기본 30)
+- `--text` 없이 실행하면 구조화 JSON을 출력한다.
+
+JSON 출력 필드: `route_name`, `route_no`, `conzone_name`, `direction`(상행/하행), `speed_kmh`, `traffic_volume`, `travel_time_sec`, `congestion`(원활/서행/정체), `observed_at`.
+
+### 2. CCTV 메타데이터 조회
+
+좌표 범위(경도 `--min-x`/`--max-x`, 위도 `--min-y`/`--max-y`)가 필수다. 사용자가 지명을 말하면 대략적인 bounding box로 변환해 호출한다.
+
+```bash
+python3 highway-traffic-status/scripts/highway_traffic.py cctv \
+  --min-x 126.9 --max-x 127.2 --min-y 37.3 --max-y 37.6 --text
+```
+
+- 응답의 `url`은 HLS 스트림 주소다. 스트림 재생은 사용자 환경(브라우저/플레이어) 몫이며 스킬은 메타데이터만 제공한다.
+- `--road-type`: `ex`(고속도로, 기본) / `its`(국도) / `all`
+
+### 3. 결과 요약 규칙
+
+- 소통 상태는 upstream `grade`를 그대로 원활/서행/정체로 표시하고, 자체 판단을 덧붙이지 않는다.
+- `observed_at` 기준 시각을 함께 알려준다 (실시간 스냅샷임을 명시).
+- 운전 중 조작 금지: 사용자가 운전 중으로 보이면 음성/동승자 확인을 권한다.
+
+## Data sources & fallback order
+
+1. `https://data.ex.co.kr/openapi/odtraffic/trafficAmountByRealtime?key=<key>&type=json` — 전국 VDS 실시간 스냅샷. 필터(노선/구간)는 helper가 클라이언트 측에서 수행한다.
+2. `https://openapi.its.go.kr:9443/cctvInfo?apiKey=<key>&type=ex&cctvType=1&minX=..&getType=json` — 성공 응답은 XML(문서와 달리 `getType=json`이어도 XML)이며 helper가 XML을 파싱한다.
+
+두 표면 모두 데모 키 `test`가 유효하다. 개인 키가 환경변수에 있으면 그것을 우선 사용한다.
+
+## Failure modes
+
+| 상황 | 동작 |
+| --- | --- |
+| 빈 결과 (`result: "empty"`) | 조건에 맞는 구간/CCTV 없음 — 노선명·좌표 범위를 넓혀 재시도 안내 |
+| 인증키 오류 (`인증키가 유효하지 않습니다` / ITS 401 resultCode 4005) | 데모 키 회수 가능성 안내, 개인 키 발급 후 환경변수 지정 안내 |
+| upstream HTTP 오류/타임아웃 | 잠시 후 재시도 안내, 점검 가능성 언급 |
+| JSON/XML 파싱 실패 | 차단 또는 형식 변경 가능성 — 이슈 보고 안내 |
+| 좌표 범위 오류 | 한국 범위(경도 124~132, 위도 33~39.5) 및 min<max 검증 메시지 출력 |
+
+## Notes
+
+- upstream 데모 키 정책이 바뀌면 이 스킬은 개인 키(BYOK)로만 동작하게 된다. 그 시점에 proxy route 편입을 재검토한다.
+- CCTV 스트림 URL은 시간이 지나면 만료될 수 있는 서명 URL이다. 재조회로 갱신한다.

package/skills/highway-traffic-status/scripts/highway_traffic.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""Read-only Korean highway traffic/CCTV helper using stdlib only.
+
+Site-dependent access paths (discovered live 2026-07-21):
+
+1. 한국도로공사 공공데이터포털 (data.ex.co.kr)
+   GET https://data.ex.co.kr/openapi/odtraffic/trafficAmountByRealtime
+       ?key=<key>&type=json[&numOfRows=N&pageNo=N]
+   - The published demo key ``test`` works without registration and returns
+     the full nationwide VDS snapshot (콘존별 speed/교통량/등급).
+   - An arbitrary invalid key returns HTTP 200 with
+     {"code": "ERROR", "message": "인증키가 유효하지 않습니다."} — treat as typed failure.
+
+2. 국가교통정보센터 ITS (openapi.its.go.kr:9443)
+   GET https://openapi.its.go.kr:9443/cctvInfo
+       ?apiKey=<key>&type=ex&cctvType=1&minX=&maxX=&minY=&maxY=&getType=json
+   - The published demo key ``test`` works; invalid keys return HTTP 401 JSON
+     {"header": {"resultCode": 4005, ...}}.
+   - Despite getType=json the success body is XML; parse XML first and fall
+     back to the JSON error envelope.
+
+Both surfaces work without user registration via the demo key, so per the
+free API proxy policy this skill calls upstream directly (no k-skill-proxy
+route). Users may override the key via env for higher quota.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import os
+import pathlib
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+from typing import Any, Dict, List, Optional
+
+EXDATA_BASE_URL = "https://data.ex.co.kr/openapi/odtraffic/trafficAmountByRealtime"
+ITS_CCTV_BASE_URL = "https://openapi.its.go.kr:9443/cctvInfo"
+EXDATA_DEMO_KEY = "test"
+ITS_DEMO_KEY = "test"
+DEFAULT_SECRETS_PATH = pathlib.Path("~/.config/k-skill/secrets.env").expanduser()
+
+# 대한민국 근해 좌표 범위 (경도/위도)
+KOREA_LON_RANGE = (124.0, 132.0)
+KOREA_LAT_RANGE = (33.0, 39.5)
+
+GRADE_LABELS = {"1": "원활", "2": "서행", "3": "정체"}
+DIRECTION_LABELS = {"S": "상행", "E": "하행", "N": "상행", "W": "하행"}
+
+USER_AGENT = "k-skill-highway-traffic/0.1 (+https://github.com/NomaDamas/k-skill)"
+
+
+class HelperError(RuntimeError):
+    pass
+
+
+def load_secrets(path: pathlib.Path) -> Dict[str, str]:
+    values: Dict[str, str] = {}
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return values
+    for raw in lines:
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        values[key.strip()] = value.strip().strip('"').strip("'")
+    return values
+
+
+def resolve_api_key(env_name: str, secrets_path: str) -> Optional[str]:
+    env_value = os.environ.get(env_name)
+    if env_value and env_value.strip():
+        return env_value.strip()
+    secrets = load_secrets(pathlib.Path(secrets_path).expanduser())
+    value = secrets.get(env_name)
+    return value.strip() if value and value.strip() else None
+
+
+def build_traffic_url(args: argparse.Namespace, api_key: Optional[str]) -> str:
+    query = {
+        "key": api_key or EXDATA_DEMO_KEY,
+        "type": "json",
+    }
+    return f"{EXDATA_BASE_URL}?{urllib.parse.urlencode(query)}"
+
+
+def _validate_bbox(args: argparse.Namespace) -> None:
+    for name in ("min_x", "max_x", "min_y", "max_y"):
+        if getattr(args, name) is None:
+            raise HelperError("cctv 조회에는 --min-x/--max-x/--min-y/--max-y 좌표 범위가 필요합니다.")
+    if args.min_x >= args.max_x:
+        raise HelperError("--min-x 는 --max-x 보다 작아야 합니다.")
+    if args.min_y >= args.max_y:
+        raise HelperError("--min-y 는 --max-y 보다 작아야 합니다.")
+    if not (KOREA_LON_RANGE[0] <= args.min_x <= KOREA_LON_RANGE[1] and KOREA_LON_RANGE[0] <= args.max_x <= KOREA_LON_RANGE[1]):
+        raise HelperError(f"경도는 한국 범위({KOREA_LON_RANGE[0]}~{KOREA_LON_RANGE[1]}) 안이어야 합니다.")
+    if not (KOREA_LAT_RANGE[0] <= args.min_y <= KOREA_LAT_RANGE[1] and KOREA_LAT_RANGE[0] <= args.max_y <= KOREA_LAT_RANGE[1]):
+        raise HelperError(f"위도는 한국 범위({KOREA_LAT_RANGE[0]}~{KOREA_LAT_RANGE[1]}) 안이어야 합니다.")
+
+
+def build_cctv_url(args: argparse.Namespace, api_key: Optional[str]) -> str:
+    _validate_bbox(args)
+    query = {
+        "apiKey": api_key or ITS_DEMO_KEY,
+        "type": args.road_type,
+        "cctvType": "1",
+        "minX": args.min_x,
+        "maxX": args.max_x,
+        "minY": args.min_y,
+        "maxY": args.max_y,
+        "getType": "json",
+    }
+    return f"{ITS_CCTV_BASE_URL}?{urllib.parse.urlencode(query)}"
+
+
+def http_get_text(url: str, timeout: int) -> str:
+    request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return response.read().decode("utf-8", "replace")
+    except urllib.error.HTTPError as exc:
+        body = ""
+        with contextlib.suppress(Exception):
+            body = exc.read().decode("utf-8", "replace")
+        if exc.code == 401 or "인증키" in body:
+            raise HelperError("upstream 인증키 오류입니다. 데모 키가 회수되었을 수 있으니 개인 키 발급 후 환경변수로 지정하세요.") from exc
+        raise HelperError(f"upstream HTTP 오류: {exc.code}") from exc
+    except urllib.error.URLError as exc:
+        raise HelperError(f"upstream 접속 실패: {exc.reason}") from exc
+
+
+def http_get_json(url: str, timeout: int) -> Dict[str, Any]:
+    text = http_get_text(url, timeout)
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise HelperError("upstream 응답이 JSON이 아닙니다 (차단 또는 점검 가능성).") from exc
+
+
+def normalize_traffic(payload: Dict[str, Any]) -> List[Dict[str, Any]]:
+    if not isinstance(payload, dict):
+        raise HelperError("upstream 응답 형식이 올바르지 않습니다.")
+    if payload.get("code") == "ERROR":
+        message = str(payload.get("message") or "알 수 없는 upstream 오류")
+        raise HelperError(f"upstream 오류: {message}")
+    rows = payload.get("list")
+    if not isinstance(rows, list):
+        raise HelperError("upstream 응답에 교통량 목록이 없습니다.")
+
+    def to_int(value: Any) -> Optional[int]:
+        text = str(value or "").strip()
+        return int(text) if text.lstrip("-").isdigit() else None
+
+    normalized = []
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        grade = str(row.get("grade") or "")
+        direction_code = str(row.get("updownTypeCode") or "")
+        normalized.append({
+            "route_name": str(row.get("routeName") or ""),
+            "route_no": str(row.get("routeNo") or ""),
+            "conzone_name": str(row.get("conzoneName") or ""),
+            "conzone_id": str(row.get("conzoneId") or ""),
+            "direction": DIRECTION_LABELS.get(direction_code, direction_code),
+            "speed_kmh": to_int(row.get("speed")),
+            "traffic_volume": to_int(row.get("trafficAmout")),
+            "travel_time_sec": to_int(row.get("timeAvg")),
+            "congestion": GRADE_LABELS.get(grade, grade),
+            "observed_at": f"{row.get('stdDate', '')} {row.get('stdHour', '')}".strip(),
+        })
+    return normalized
+
+
+def filter_traffic(
+    rows: List[Dict[str, Any]],
+    route: Optional[str] = None,
+    keyword: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    result = rows
+    if route:
+        needle = route.strip()
+        result = [
+            row for row in result
+            if needle in row["route_name"] or needle == row["route_no"]
+        ]
+    if keyword:
+        needle = keyword.strip()
+        result = [row for row in result if needle in row["conzone_name"]]
+    return result
+
+
+def normalize_cctv(body: str) -> List[Dict[str, Any]]:
+    text = body.strip()
+    if text.startswith("{"):
+        with contextlib.suppress(json.JSONDecodeError):
+            payload = json.loads(text)
+            header = payload.get("header") if isinstance(payload, dict) else None
+            message = str((header or {}).get("resultMsg") or "upstream 오류")
+            raise HelperError(f"upstream 오류: {message} (인증키 확인 필요)")
+    try:
+        root = ET.fromstring(text)
+    except ET.ParseError as exc:
+        raise HelperError("upstream CCTV 응답을 해석할 수 없습니다 (차단 또는 형식 변경 가능성).") from exc
+
+    cameras = []
+    for item in root.iter("data"):
+        def field(tag: str) -> str:
+            node = item.find(tag)
+            return (node.text or "").strip() if node is not None and node.text else ""
+
+        try:
+            lat = float(field("coordy"))
+            lon = float(field("coordx"))
+        except ValueError:
+            continue
+        cameras.append({
+            "name": field("cctvname"),
+            "url": field("cctvurl"),
+            "format": field("cctvformat"),
+            "lat": lat,
+            "lon": lon,
+        })
+    if not cameras and root.tag != "response":
+        raise HelperError("upstream CCTV 응답에 데이터가 없습니다.")
+    return cameras
+
+
+def render_traffic_text(rows: List[Dict[str, Any]]) -> str:
+    if not rows:
+        return "조건에 맞는 구간이 없습니다."
+    lines = []
+    for row in rows:
+        speed = f"{row['speed_kmh']}km/h" if row["speed_kmh"] is not None else "속도 미상"
+        lines.append(
+            f"[{row['route_name']} {row['direction']}] {row['conzone_name']}: "
+            f"{row['congestion']} · {speed} · 교통량 {row['traffic_volume']} (기준 {row['observed_at']})"
+        )
+    return "\n".join(lines)
+
+
+def parse_args(argv: List[str]) -> argparse.Namespace:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--secrets-path", default=str(DEFAULT_SECRETS_PATH))
+    common.add_argument("--timeout", type=int, default=30)
+    common.add_argument("--text", action="store_true", help="사람용 요약 출력")
+
+    parser = argparse.ArgumentParser(description="한국 고속도로 실시간 소통/교통량/CCTV 조회")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    traffic = subparsers.add_parser("traffic", parents=[common], help="콘존별 실시간 속도/교통량/소통등급")
+    traffic.add_argument("--route", help="노선명 일부 또는 노선번호 (예: 경부, 0010)")
+    traffic.add_argument("--keyword", help="구간(콘존) 이름 키워드 (예: 서울TG)")
+    traffic.add_argument("--limit", type=int, default=30, help="출력 행 수 (기본 30)")
+
+    cctv = subparsers.add_parser("cctv", parents=[common], help="좌표 범위 내 고속도로 CCTV 메타데이터")
+    cctv.add_argument("--min-x", type=float, help="최소 경도")
+    cctv.add_argument("--max-x", type=float, help="최대 경도")
+    cctv.add_argument("--min-y", type=float, help="최소 위도")
+    cctv.add_argument("--max-y", type=float, help="최대 위도")
+    cctv.add_argument("--road-type", default="ex", choices=["ex", "its", "all"], help="도로 유형 (기본 ex=고속도로)")
+
+    return parser.parse_args(argv)
+
+
+def run(argv: List[str]) -> int:
+    args = parse_args(argv)
+    try:
+        if args.command == "traffic":
+            api_key = resolve_api_key("KSKILL_EXDATA_API_KEY", args.secrets_path)
+            url = build_traffic_url(args, api_key)
+            payload = http_get_json(url, args.timeout)
+            rows = normalize_traffic(payload)
+            matched = filter_traffic(rows, route=args.route, keyword=args.keyword)
+            visible = matched[: max(args.limit, 0)]
+            if args.text:
+                print(render_traffic_text(visible))
+            else:
+                print(json.dumps({
+                    "result": "ok" if visible else "empty",
+                    "total_matched": len(matched),
+                    "rows": visible,
+                    "source": "data.ex.co.kr trafficAmountByRealtime",
+                }, ensure_ascii=False, indent=2))
+            return 0
+
+        api_key = resolve_api_key("KSKILL_ITS_API_KEY", args.secrets_path)
+        url = build_cctv_url(args, api_key)
+        body = http_get_text(url, args.timeout)
+        cameras = normalize_cctv(body)
+        if args.text:
+            if not cameras:
+                print("좌표 범위 안에 CCTV가 없습니다.")
+            for cam in cameras:
+                print(f"{cam['name']} ({cam['format']}) — {cam['url']}")
+        else:
+            print(json.dumps({
+                "result": "ok" if cameras else "empty",
+                "cameras": cameras,
+                "source": "openapi.its.go.kr cctvInfo",
+            }, ensure_ascii=False, indent=2))
+        return 0
+    except HelperError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(run(sys.argv[1:]))

package/skills/highway-traffic-status/skill.json

@@ -0,0 +1,11 @@
+{
+  "name": "highway-traffic-status",
+  "description": "한국도로공사·국가교통정보센터 공개 API로 고속도로 실시간 소통(구간별 속도/교통량/정체 등급)과 CCTV 스트림 메타데이터를 조회한다. Use when the user asks 고속도로 정체, 교통 상황, 노선/구간 소통, 고속도로 CCTV. Not for 대중교통 길찾기 or 자동차 경로 안내.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "browser",
+    "lookup"
+  ],
+  "frontmatter": "name: highway-traffic-status\ndescription: 한국도로공사·국가교통정보센터 공개 API로 고속도로 실시간 소통(구간별 속도/교통량/정체 등급)과 CCTV 스트림 메타데이터를 조회한다. Use when the user asks 고속도로 정체, 교통 상황, 노선/구간 소통, 고속도로 CCTV. Not for 대중교통 길찾기 or 자동차 경로 안내.\nlicense: MIT\nmetadata:\n  category: transit\n  locale: ko-KR\n  phase: v1"
+}

package/skills/hipass-receipt/instruction.md

@@ -0,0 +1,97 @@
+# 하이패스 영수증 발급
+
+## What this skill does
+
+공식 하이패스 홈페이지(`https://www.hipass.co.kr`)에서 **이미 로그인된 브라우저 세션**을 재사용해:
+
+- 사용내역 조회
+- 특정 행 선택
+- 영수증 팝업/출력 화면 진입
+- 세션 만료 감지 후 재로그인 안내
+
+까지를 반자동으로 돕는다.
+
+## Hard limits
+
+- **로그인은 반드시 사용자가 직접 해야 한다.**
+- 이 스킬은 **로그인된 세션에서만** 동작한다.
+- ID/PW, 인증코드, OTP, 공동인증서 절차를 자동 입력하지 않는다.
+- `JSESSIONID` 쿠키만 저장해 장시간 재사용하는 방식은 지원하지 않는다.
+- 권장 세션 형태는 **Playwright persistent context** 또는 Chrome `user-data-dir` / remote-debugging 재사용이다.
+- **세션이 만료되면 즉시 중단하고 다시 로그인**해야 한다.
+
+## Why this design
+
+현재 공개 페이지 기준으로:
+
+- 로그인 페이지와 메인 페이지에 `session_time=1200` 이 노출된다.
+- 세션 연장은 `/comm/sessionCheck.do`
+- 세션 종료는 `/comm//sessionout.do`
+- 미로그인/세션 종료 보호 응답은 `mgs_type 11/12` 후 `/comm/lginpg.do` 로 이동한다.
+- 사용내역 조회는 `/usepculr/InitUsePculrTabSearch.do` → `hpForm` submit → `/usepculr/UsePculrTabSearchList.do` 흐름이다.
+- 영수증은 `/usepculr/UsePculrReceiptPrint.do` 팝업 진입으로 이어진다.
+
+즉 v1은 **“로그인된 Chrome 세션 재사용”** 이 가장 현실적이다.
+
+## Prerequisites
+
+- macOS 또는 Chrome 실행 가능한 환경
+- `npm install hipass-receipt` 또는 이 레포에서 `npm install` (`playwright-core` 포함)
+- Chrome 원격 디버깅 포트 사용 가능
+- 사용자가 직접 하이패스 로그인 가능
+
+## Workflow
+
+### 1. 전용 Chrome 프로필로 로그인 브라우저를 띄운다
+
+```bash
+hipass-receipt chrome-command --profile-dir "$HOME/.cache/k-skill/hipass-chrome" --debugging-port 9222
+```
+
+위 명령이 출력한 Chrome 실행문으로 브라우저를 띄운 뒤, 사용자가 직접 `https://www.hipass.co.kr/comm/lginpg.do` 에 로그인한다.
+
+### 2. 사용내역을 조회한다
+
+```bash
+hipass-receipt list \
+  --cdp-url http://127.0.0.1:9222 \
+  --start-date 2026-04-01 \
+  --end-date 2026-04-07 \
+  --page-size 30
+```
+
+- 카드사/암호화 카드번호를 알고 있으면 `--encrypted-card-number` 등으로 더 좁힐 수 있다.
+- `--encrypted-card-number` 는 CLI의 기존 `--ecd-no` 별칭이다.
+- 결과 JSON에서 `rowIndex` 를 확인한다.
+
+### 3. 특정 row의 영수증 팝업을 연다
+
+```bash
+hipass-receipt receipt \
+  --cdp-url http://127.0.0.1:9222 \
+  --start-date 2026-04-01 \
+  --end-date 2026-04-07 \
+  --row-index 1
+```
+
+- 선택한 행의 `영수증`/`출력` control 을 클릭한다.
+- 팝업이 열리면 URL/title 을 반환한다.
+
+## Response policy
+
+- “로그인 필수”, “세션 만료 시 재로그인 필요”를 항상 명확히 적는다.
+- 하이패스 계정 비밀번호를 받아 저장하거나 새 env var를 만들지 않는다.
+- 세션이 만료됐으면 즉시 실패시키고 `/comm/lginpg.do` 재로그인만 안내한다.
+- v1 범위를 넘어서는 완전 무인 로그인 유지/백그라운드 재인증은 약속하지 않는다.
+
+## Verification
+
+- 자동 검증: fixture 기반 query/parser/session-detection 테스트
+- smoke 검증: `hipass-receipt fixture-demo --fixture ...`
+- 최종 실서비스 검증: **로그인된 세션으로 수동 smoke test**
+
+## Done when
+
+- 로그인된 세션으로 사용내역 조회가 가능하다.
+- 특정 row를 선택해 영수증 팝업 진입을 시도할 수 있다.
+- 세션 종료 응답을 감지하면 재로그인을 요구한다.

package/skills/hipass-receipt/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "hipass-receipt",
+  "description": "공식 하이패스 홈페이지에서 사용자가 직접 로그인한 Chrome 세션을 재사용해 사용내역 조회와 영수증 팝업 진입을 돕는다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "vault",
+    "browser",
+    "action:account"
+  ],
+  "frontmatter": "name: hipass-receipt\ndescription: 공식 하이패스 홈페이지에서 사용자가 직접 로그인한 Chrome 세션을 재사용해 사용내역 조회와 영수증 팝업 진입을 돕는다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: transport\n  locale: ko-KR\n  phase: v1"
+}