@nomadamas/k-skill 0.6.0 → 0.8.0

package/skills/religious-facility-search/instruction.md

@@ -0,0 +1,195 @@
+# 종교시설 찾기 / Religious Facility Search
+
+## What this skill does
+
+동네·역명·랜드마크 텍스트를 기준점으로 잡고 주변 **종교시설을 거리순으로 조회**한다.
+교회, 성당, 사찰을 같은 경로로 다루며 기본 대상은 교회다.
+
+- 조회 전용이다. 등록, 연락, 방문 예약 같은 액션은 하지 않는다.
+- 위치는 사용자가 제공한 텍스트만 쓴다. 자동 위치 추적을 하지 않는다.
+- **공식 Kakao Local REST API**를 `k-skill-proxy` 경유로 호출한다. 사용자 머신에는
+  API 키가 필요 없고, 프록시 운영자의 `KAKAO_REST_API_KEY`로 인증한다.
+
+## When to use
+
+- "근처 교회 찾아줘"
+- "강남역 근처 교회 알려줘"
+- "명동 성당 위치가 어디야"
+- "경주에 절 어디 있어?"
+- "이 근처 종교시설 알려줘"
+- "온누리교회 주소 알려줘"
+
+## Inputs
+
+- `location`: 동네·역명·랜드마크. 예: `강남역`, `성수동`, `경주`
+- `--name`: 시설 이름으로 직접 검색. 예: `--name 온누리교회`
+- `--type`: `교회`(기본) / `성당` / `절` / `사찰` / `전체`
+- `--radius`: 기준점으로부터 최대 거리(m, 최대 20000). Kakao Local API의 상한이다
+- `--limit`: 표시 개수 (기본 5, 최대 45). 페이지당 15건씩 최대 3페이지를 가져온다
+- `--json`: JSON 출력
+
+사용자가 "성당", "절", "사찰"을 명시하면 `--type`을 그에 맞게 지정한다. 종류를 특정하지
+않고 "종교시설"이라고만 하면 `--type 전체`를 쓴다.
+
+위치도 이름도 없으면 **먼저 사용자에게 위치를 묻는다.** 비대화형 자동화에서는
+임의로 좁히지 말고 "입력 없음"을 명시한다.
+
+권장 질문:
+
+```text
+어느 동네나 역 근처에서 찾을까요? (예: 강남역, 성수동)
+```
+
+## Public access path discovered
+
+### 선택한 공개 경로
+
+공식 Kakao Local REST API의 keyword 검색 하나만 쓴다. `k-skill-proxy`가 운영자 키로
+인증을 대행하므로 사용자 머신에는 키가 필요 없다.
+
+1. `GET {proxy}/v1/kakao-map/search/keyword?q=<위치>`
+   → 첫 번째 결과를 기준점(anchor) 좌표로 쓴다.
+2. `GET {proxy}/v1/kakao-map/search/keyword?q=<종류>&x=<lon>&y=<lat>&radius=<m>&sort=distance&size=15&page=1..3`
+   → 거리순 장소 목록. 거리는 upstream이 주는 공식 `distance` 필드를 그대로 쓴다.
+
+`{proxy}`는 기본 `https://k-skill-proxy.nomadamas.org`이며 `KSKILL_PROXY_BASE_URL`로
+바꿀 수 있다. 같은 라우트를 `kakao-map` 스킬이 이미 쓰고 있다.
+
+### 왜 이 경로인가
+
+- **공식 문서화 API**: Kakao Developers가 스키마를 보장한다. 이전의 모바일 웹 표면
+  (`m.map.kakao.com`) 스크래핑은 문서가 없어 구조가 바뀌면 깨지는 상수 리스크가 있었다.
+- **proxy 편입 규칙 적합**: upstream이 API 키를 요구하므로 `AGENTS.md` 규칙상
+  `k-skill-proxy`를 거치는 것이 맞다. 프록시에 캐시·rate-limit이 있어 쿼터도 보호된다.
+- **거리 계산 불필요**: `sort=distance` + `distance` 필드가 공식 제공되어 haversine을
+  직접 돌릴 필요가 없다.
+- **전국 커버리지**: 지자체 공공데이터(예: 서울 종로구 교회 현황
+  `https://www.data.go.kr/data/15117640/fileData.do`)는 구 단위로만 공개되어 전국
+  표준데이터가 없다. 주 경로로 쓸 수 없어 참고 출처로만 둔다.
+- **분류가 데이터에 있음**: `category_name`에 종교 분류가 그대로 들어온다.
+
+```
+교회 → 문화,예술 > 종교 > 기독교 > 교회
+성당 → 문화,예술 > 종교 > 천주교 > 성당
+사찰 → 문화,예술 > 종교 > 불교 > 절,사찰
+기타 → 문화,예술 > 종교 > 종교시설 / 문화,예술 > 종교 > 통일교 …
+```
+
+`category_name`에 `종교` 노드가 있는 결과만 통과시키므로 `써브웨이 명동성당점` 같은
+이름만 비슷한 음식점·서점이 결과에 섞이지 않는다. `--type`은 그 안에서 마지막
+두 분류 토큰으로 한 번 더 좁힌다.
+
+### fallback 순서
+
+1. 기준점 해석 실패 → 거리 없이 결과 목록만 제공한다 (stderr에 사유 표시).
+2. 지정한 종류가 0건 → `--type 전체`로 넓히거나 `--radius`를 걸었다면 풀고 재시도한다.
+3. 검색 결과 0건 → 상위 행정구역으로 넓혀 재시도한다.
+4. 프록시 장애가 계속되면 결과를 지어내지 말고 실패를 그대로 알린다.
+
+## Workflow
+
+1. 사용자에게 위치와 시설 종류를 확인한다. 위치가 없으면 먼저 묻는다.
+2. helper를 실행한다.
+
+```bash
+npx -y @nomadamas/k-skill@0 exec religious-facility-search scripts/religious_facility_search.py -- "강남역" --limit 5
+```
+
+성당:
+
+```bash
+npx -y @nomadamas/k-skill@0 exec religious-facility-search scripts/religious_facility_search.py -- "명동" --type 성당 --limit 5
+```
+
+사찰:
+
+```bash
+npx -y @nomadamas/k-skill@0 exec religious-facility-search scripts/religious_facility_search.py -- "경주" --type 절 --limit 5
+```
+
+종류를 가리지 않을 때:
+
+```bash
+npx -y @nomadamas/k-skill@0 exec religious-facility-search scripts/religious_facility_search.py -- "성수동" --type 전체 --radius 600
+```
+
+이름으로 검색:
+
+```bash
+npx -y @nomadamas/k-skill@0 exec religious-facility-search scripts/religious_facility_search.py -- --name "온누리교회"
+```
+
+3. 결과를 3~5개로 요약한다. 각 항목에 이름, 주소, 거리, 연락처를 붙인다.
+4. 예배·미사·법회 시간을 물으면 **추정하지 말고** 카카오맵 장소 페이지나 전화로 안내한다.
+
+## Output
+
+기준 위치와 검색어를 먼저 보여주고 거리순 목록을 출력한다.
+
+```
+기준 위치: 강남역 2호선 (37.49809, 127.02800)
+검색어: "교회" · 후보 43건 중 종교시설 40건 (가까운 5건 표시)
+
+1. 강남성서침례교회  (교회 · 기독교)
+   서울 서초구 강남대로55길 9-11
+   약 313m
+   전화 02-3474-3609
+   지도 https://place.map.kakao.com/85095074
+```
+
+`--json`은 다음 구조로 출력한다.
+
+```json
+{
+  "query": "교회",
+  "anchor": { "name": "강남역 2호선", "lat": 37.49809, "lon": 127.02800 },
+  "scanned": 43,
+  "matched": 40,
+  "items": [
+    {
+      "id": "85095074",
+      "name": "강남성서침례교회",
+      "category": "교회",
+      "denomination": "기독교",
+      "category_group": "종교",
+      "lat": 37.4964,
+      "lon": 127.0380,
+      "address": "서울 서초구 강남대로55길 9-11",
+      "phone": "02-3474-3609",
+      "homepage": null,
+      "place_url": "https://place.map.kakao.com/85095074",
+      "distance_m": 313
+    }
+  ]
+}
+```
+
+`homepage`는 Kakao Local API가 외부 홈페이지를 제공하지 않아 항상 `null`이다.
+대신 `place_url`(카카오맵 장소 페이지)로 안내한다.
+
+## Done when
+
+- 기준 위치와 시설 종류를 확정하고 사용자에게 알렸다.
+- `category_name`의 `종교` 노드로 검증된 후보를 거리순 3~5개로 정리했다.
+- 각 후보에 주소와, 있으면 전화번호·카카오맵 링크를 붙였다.
+- 예배·미사·법회 시간을 임의로 지어내지 않고 공식 출처로 넘겼다.
+
+## Failure modes
+
+- **검색 결과 없음**: 검색어가 좁거나 오탈자다. 상위 행정구역으로 넓혀 재시도한다.
+- **지정 종류 0건**: 후보는 잡혔지만 해당 종류가 없다. `--type 전체`로 넓히거나, `--radius`를 걸었다면 풀고 확인한다. `--radius`는 결과를 좁히는 옵션이라 늘려도 새 후보를 가져오지 않는다.
+- **프록시 503 `upstream_not_configured`**: 프록시에 `KAKAO_REST_API_KEY`가 없다. 운영자에게 키 설정을 요청한다.
+- **프록시 401/403 → 503 변환**: Kakao 키 revoke나 일일 쿼터 초과 신호다. 잠시 후 재시도하고 계속되면 운영자에게 알린다.
+- **프록시 5xx / 타임아웃**: 프록시 또는 upstream 일시 장애. 재시도하고 계속 실패하면 그대로 보고한다.
+- **좌표 입력**: v1은 `위도,경도` 입력을 지원하지 않는다. helper가 명시적으로 거부하고
+  동네·역명을 요구한다.
+- **시·군 단위 입력**: 기준점이 그 안의 특정 장소로 잡혀 절대 거리가 대략치가 된다.
+  동·역 단위에서 가장 정확하다.
+- **예배·미사·법회 시간**: 이 데이터에 없다. 제공하지 않는다.
+
+## Notes
+
+- 공개 정보 조회 전용이다. 종교나 교단의 우열을 평가하거나 이단 여부를 판별하지 않는다.
+- 특정 시설이나 교단을 권유하지 않는다. 거리와 공개 정보만 근거로 나열한다.
+- 예배·미사·법회 시간, 성직자, 교단 소속은 이 데이터에 없다. 추정하지 않고 공식 출처로 넘긴다.
+- 사용자가 제공한 위치 텍스트만 쓴다. 위치를 자동으로 알아내려 하지 않는다.

package/skills/religious-facility-search/scripts/religious_facility_search.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""종교시설 찾기 — 공식 Kakao Local API (k-skill-proxy 경유).
+
+공개 접근 경로:
+  1) GET {proxy}/v1/kakao-map/search/keyword?q=<위치> → 기준점 좌표 (anchor)
+  2) GET {proxy}/v1/kakao-map/search/keyword?q=<종류>&x=..&y=..&radius=..&sort=distance
+     → 거리순 장소 목록 (공식 distance 필드 사용)
+
+upstream이 Kakao Developers REST API 키를 요구하므로 k-skill-proxy를 거친다
+(사용자 머신에는 키가 필요 없고, 프록시 운영자 키로 인증한다).
+category_name에 "종교" 노드가 있는 결과만 통과시키므로
+이름에 "교회"가 들어간 카페·서점 같은 오탐이 걸러진다.
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+DEFAULT_PROXY_BASE = "https://k-skill-proxy.nomadamas.org"
+SEARCH_KEYWORD_PATH = "/v1/kakao-map/search/keyword"
+
+USER_AGENT = "k-skill-religious-facility-search/1"
+
+RELIGION_CATEGORY = "종교"
+TYPE_ALIASES = {
+    "교회": ["교회"],
+    "성당": ["성당"],
+    "절": ["절", "사찰"],
+    "사찰": ["절", "사찰"],
+    "전체": [],
+}
+# --type 전체: "종교시설" 단일 키워드는 교회·사찰을 놓치므로 종류별로 합친다
+ALL_TYPE_QUERIES = ["교회", "성당", "사찰"]
+COORD_RE = re.compile(r"^\s*(-?\d+\.\d+)\s*,\s*(-?\d+\.\d+)\s*$")
+PAGE_SIZE = 15          # Kakao Local keyword 검색의 페이지당 최대 건수
+MAX_PAGES = 3           # 페이지네이션 상한 → 최대 45개 후보
+MAX_CANDIDATES = PAGE_SIZE * MAX_PAGES
+
+
+class LookupError_(Exception):
+    """조회 실패를 명시적 실패 모드로 올린다."""
+
+
+def proxy_base():
+    return (os.environ.get("KSKILL_PROXY_BASE_URL") or DEFAULT_PROXY_BASE).rstrip("/")
+
+
+def fetch_json(url, timeout=15):
+    request = urllib.request.Request(url, headers={"user-agent": USER_AGENT, "accept": "application/json"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as error:
+        detail = ""
+        try:
+            detail = error.read().decode("utf-8", errors="replace")[:200]
+        except Exception:
+            pass
+        raise LookupError_(f"프록시 HTTP {error.code} ({detail or '응답 본문 없음'})") from error
+    except urllib.error.URLError as error:
+        raise LookupError_(f"네트워크 오류: {error.reason}") from error
+
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise LookupError_("프록시 응답이 JSON이 아니다 (proxy 변경 가능)") from error
+
+
+def search_places(query, x=None, y=None, radius=None, max_pages=MAX_PAGES):
+    """proxy keyword 검색. (documents, meta)를 돌려준다. 첫 페이지가 비면 명시적 실패."""
+    params = {"q": query, "size": PAGE_SIZE}
+    if x is not None and y is not None:
+        params.update({"x": x, "y": y, "sort": "distance"})
+        if radius:
+            params["radius"] = radius
+
+    documents, meta = [], {}
+    for page in range(1, max_pages + 1):
+        params["page"] = page
+        url = f"{proxy_base()}{SEARCH_KEYWORD_PATH}?{urllib.parse.urlencode(params)}"
+        payload = fetch_json(url)
+        batch = payload.get("documents") or []
+        meta = payload.get("meta") or {}
+        documents.extend(batch)
+        if page == 1 and not documents:
+            raise LookupError_(f'"{query}" 검색 결과가 비었다 (검색어를 넓히거나 지역명을 붙여볼 것)')
+        if meta.get("is_end", True) or not batch:
+            break
+    return documents, meta
+
+
+def map_place(document):
+    parts = [p.strip() for p in (document.get("category_name") or "").split(">") if p.strip()]
+    distance_raw = (document.get("distance") or "").strip()
+    return {
+        "id": document.get("id"),
+        "name": document.get("place_name"),
+        "category": parts[-1] if parts else None,
+        "denomination": parts[-2] if len(parts) >= 4 else None,
+        "category_group": RELIGION_CATEGORY if RELIGION_CATEGORY in parts else None,
+        "lat": float(document["y"]) if document.get("y") else None,
+        "lon": float(document["x"]) if document.get("x") else None,
+        "address": (document.get("road_address_name") or document.get("address_name") or "").strip() or None,
+        "jibun": (document.get("address_name") or "").strip() or None,
+        "phone": (document.get("phone") or "").strip() or None,
+        "homepage": None,  # Kakao Local API는 외부 홈페이지를 제공하지 않는다
+        "place_url": document.get("place_url"),
+        "distance_m": int(distance_raw) if distance_raw else None,
+    }
+
+
+def resolve_anchor(location):
+    """위치 문자열을 좌표로 바꾼다. 실패하면 None (거리 없이 결과만 제공)."""
+    try:
+        documents, _ = search_places(location)
+    except LookupError_:
+        return None
+    if not documents:
+        return None
+    top = documents[0]
+    return {"name": top.get("place_name"), "lat": float(top["y"]), "lon": float(top["x"])}
+
+
+def _category_tokens(place):
+    tokens = []
+    for part in (place.get("category"), place.get("denomination")):
+        if not part:
+            continue
+        tokens.extend(token.strip() for token in part.replace(",", " ").split() if token.strip())
+    return tokens
+
+
+def matches_type(place, facility_type):
+    if place.get("category_group") != RELIGION_CATEGORY:
+        return False
+    wanted = TYPE_ALIASES.get(facility_type, [facility_type])
+    if not wanted:
+        return True
+    tokens = _category_tokens(place)
+    return any(token in tokens for token in wanted)
+
+
+def _dedupe_by_id(places):
+    seen, unique = set(), []
+    for place in places:
+        if place["id"] not in seen:
+            seen.add(place["id"])
+            unique.append(place)
+    return unique
+
+
+def collect(query, facility_type, anchor, radius_m, limit):
+    x = y = None
+    if anchor:
+        x, y = anchor["lon"], anchor["lat"]
+
+    if facility_type == "전체" and query == "전체":
+        # "종교시설" 단일 검색은 교회·사찰을 놓치므로 종류별 검색을 합친다
+        documents, scanned, hits = [], 0, 0
+        for token in ALL_TYPE_QUERIES:
+            try:
+                docs, _ = search_places(token, x=x, y=y, radius=radius_m)
+            except LookupError_:
+                continue  # 한 종류가 0건이어도 나머지 종류는 돌려준다
+            hits += 1
+            scanned += len(docs)
+            documents.extend(docs)
+        if hits == 0:
+            raise LookupError_('"전체" 검색 결과가 비었다 (지역을 넓히거나 --type을 좁혀볼 것)')
+    else:
+        documents, _ = search_places(query, x=x, y=y, radius=radius_m)
+        scanned = len(documents)
+
+    places = _dedupe_by_id(map_place(doc) for doc in documents)
+    places = [p for p in places if matches_type(p, facility_type)]
+
+    if anchor:
+        places.sort(key=lambda p: (p["distance_m"] is None, p["distance_m"] or 0))
+
+    return scanned, len(places), places[:limit]
+
+
+def format_report(query, anchor, scanned, matched, places, facility_type):
+    lines = []
+    if anchor:
+        lines.append(f"기준 위치: {anchor['name']} ({anchor['lat']:.5f}, {anchor['lon']:.5f})")
+    summary = f'검색어: "{query}" · 후보 {scanned}건 중 종교시설 {matched}건'
+    if matched > len(places):
+        summary += f" (가까운 {len(places)}건 표시)"
+    lines.append(summary)
+    lines.append("")
+
+    if not places:
+        lines.append(f"조건에 맞는 {facility_type}을(를) 찾지 못했다. 지역을 넓혀 다시 찾거나 "
+                     f"--type 전체 로 확인할 것 (--radius 는 결과를 좁히는 옵션이다).")
+        return "\n".join(lines)
+
+    for index, place in enumerate(places, start=1):
+        label = place["category"] or "종교시설"
+        if place.get("denomination"):
+            label = f"{label} · {place['denomination']}"
+        lines.append(f"{index}. {place['name']}  ({label})")
+        if place.get("address"):
+            lines.append(f"   {place['address']}")
+        if place.get("distance_m") is not None:
+            lines.append(f"   약 {place['distance_m']:,}m")
+        contact = []
+        if place.get("phone"):
+            contact.append(f"전화 {place['phone']}")
+        if place.get("homepage"):
+            contact.append(place["homepage"])
+        if contact:
+            lines.append("   " + "  ".join(contact))
+        lines.append(f"   지도 {place['place_url']}")
+        lines.append("")
+
+    lines.append("예배·미사·법회 시간은 이 데이터에 없다. 각 홈페이지나 전화로 확인할 것.")
+    return "\n".join(lines).rstrip()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="종교시설 찾기 (공식 Kakao Local API, k-skill-proxy 경유)")
+    parser.add_argument("location", nargs="?", help="동네·역명·랜드마크 (예: 강남역, 성수동)")
+    parser.add_argument("--name", help="교회/시설 이름으로 직접 검색")
+    parser.add_argument("--type", default="교회", choices=sorted(TYPE_ALIASES), help="시설 종류 (기본: 교회)")
+    parser.add_argument("--radius", type=int, help="기준 위치로부터 최대 거리(m, 최대 20000)")
+    parser.add_argument("--limit", type=int, default=5, help=f"표시 개수 (기본 5, 최대 {MAX_CANDIDATES})")
+    parser.add_argument("--json", action="store_true", help="JSON으로 출력")
+    args = parser.parse_args()
+
+    if not args.location and not args.name:
+        parser.error("location 또는 --name 중 하나는 필요하다. 사용자에게 현재 위치를 먼저 물어볼 것.")
+
+    if not 1 <= args.limit <= MAX_CANDIDATES:
+        parser.error(f"--limit은 1~{MAX_CANDIDATES} 사이여야 한다. 페이지 {MAX_PAGES}장(페이지당 "
+                     f"{PAGE_SIZE}건)까지만 가져오므로 그보다 많이 표시할 수 없다.")
+
+    if args.radius is not None and not 1 <= args.radius <= 20000:
+        parser.error("--radius는 1~20000(m) 사이여야 한다. Kakao Local API의 상한이다.")
+
+    if args.location and COORD_RE.match(args.location):
+        parser.error("좌표 검색은 지원하지 않는다. 동네·역명·랜드마크로 입력할 것 (예: 강남역, 성수동).")
+
+    if args.name:
+        # 위치는 좌표(x,y)로 전달하므로 검색어는 시설 이름만 쓴다
+        # ("강남역 온누리교회"처럼 붙이면 keyword API가 0건을 돌려준다)
+        query = args.name
+    elif args.type == "전체":
+        query = args.type  # collect()가 종류별 검색으로 풀어서 합친다
+    else:
+        query = args.type
+
+    try:
+        anchor = resolve_anchor(args.location) if args.location else None
+        if args.location and anchor is None:
+            print(f"기준 위치 \"{args.location}\"을(를) 찾지 못해 거리 없이 조회한다.", file=sys.stderr)
+        scanned, matched, places = collect(query, args.type, anchor, args.radius, args.limit)
+    except LookupError_ as error:
+        print(f"조회 실패: {error}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps({"query": query, "anchor": anchor, "scanned": scanned,
+                          "matched": matched, "items": places},
+                         ensure_ascii=False, indent=2))
+    else:
+        print(format_report(query, anchor, scanned, matched, places, args.type))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/religious-facility-search/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "religious-facility-search",
+  "description": "Use when the user asks 근처 교회 찾기, 성당 위치, 절·사찰 찾기, 종교시설 조회, or church/cathedral/temple lookup by Korean neighborhood, station, or landmark. 공식 Kakao Local API를 k-skill-proxy 경유로 호출해 종교시설을 거리순으로 조회하고 주소·전화·카카오맵 링크를 정리한다. 사용자 API 키가 필요 없는 조회 전용 스킬이다.",
+  "profiles": [
+    "proxy",
+    "lookup"
+  ],
+  "frontmatter": "name: religious-facility-search\ndescription: Use when the user asks 근처 교회 찾기, 성당 위치, 절·사찰 찾기, 종교시설 조회, or church/cathedral/temple lookup by Korean neighborhood, station, or landmark. 공식 Kakao Local API를 k-skill-proxy 경유로 호출해 종교시설을 거리순으로 조회하고 주소·전화·카카오맵 링크를 정리한다. 사용자 API 키가 필요 없는 조회 전용 스킬이다.\nlicense: MIT\nmetadata:\n  category: religion\n  locale: ko-KR\n  phase: v1"
+}

package/skills/ktx-booking/instruction.md

@@ -1,61 +0,0 @@
-# KTX Official Timetable Lookup
-
-## What this skill does
-
-한국철도공사가 로그인 없이 공개하는 최신 KTX 운행시간표 XLSX를 내려받아 출발역·도착역·출발시간 조건에 맞는 열차를 찾는다.
-
-이 스킬은 **공식 계획 시간표 조회 전용**이다.
-
-- 회원 로그인, credential, Korail 앱 내부 API를 사용하지 않는다.
-- Dynapath 또는 anti-bot token을 생성·재현·우회하지 않는다.
-- 실시간 잔여석, 실제 운휴·지연, 호차·좌석번호는 조회하지 않는다.
-- 예약, 예약대기, 좌석 선점, 결제, 취소, 자동 재조회는 실행하지 않는다.
-- 구매와 실시간 운행 확인은 공식 코레일 페이지에서 사용자가 직접 진행한다.
-
-실행 환경에는 Python 3.11 이상과 `uv`가 필요하다. `uv`가 helper에 고정된 `openpyxl` 환경을 자동 설치한다.
-
-## Commands
-
-```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- \
-  search --dep 서울 --arr 부산 --date 20260819 --time 0600 --time-limit 1200 --limit 5
-```
-
-```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- source
-```
-
-## Inputs
-
-- `--dep`: 출발역명. `서울`과 `서울역` 모두 허용한다.
-- `--arr`: 도착역명.
-- `--date`: `YYYYMMDD`.
-- `--time`: 가장 이른 출발시각 `HHMM`, 기본 `0000`.
-- `--time-limit`: 가장 늦은 출발시각 `HHMM`, 기본 `2359`.
-- `--limit`: 최대 결과 수, 1~50.
-
-## Output
-
-- `count`
-- `trains[]`: `train_no`, `train_type`, `dep`, `arr`, `dep_time`, `arr_time`
-- `date`
-- `schedule_note`
-- `source`: 공식 게시물 제목·게시일·XLSX URL·게시판 URL
-- `booking_url`
-
-항상 이 결과는 **공개 운행계획 시간표**이며 실시간 잔여석·운휴·지연 정보가 아니라는 점을 명시한다.
-
-## Failure modes
-
-- 공식 시간표 게시판 또는 XLSX 다운로드 실패
-- 요청일에 적용되는 KTX 시간표 없음
-- XLSX 형식 변경으로 header를 찾지 못함
-- 요청 구간·시간대 결과 없음: 오류가 아니라 `count: 0`
-- 잘못된 날짜·시간·limit: 실행 전 오류
-
-## Hard boundaries
-
-- 로그인·credential 요청 금지
-- `ScheduleView`, `korail2`, Dynapath 등 앱 내부 경로 사용 금지
-- 예약·결제·취소·좌석 선점 금지
-- CAPTCHA·인증·anti-bot 통제 우회 금지

package/skills/ktx-booking/references/AUTOMATION-LEGAL-STATEMENT.md

@@ -1,10 +0,0 @@
-# KTX 공식 시간표 조회 관련 고지
-
-이 스킬은 한국철도공사가 공개한 시간표 게시판과 XLSX 첨부파일만 읽는다.
-
-- 회원 로그인과 credential을 사용하지 않는다.
-- Korail 앱 내부 API, `ScheduleView`, Dynapath token을 호출·생성·재현하지 않는다.
-- CAPTCHA, anti-bot 또는 접근통제를 우회하지 않는다.
-- 실시간 잔여석, 예약, 좌석 선점, 결제, 취소를 실행하지 않는다.
-
-결과는 공개 운행계획 시간표이며 실제 운휴·지연·잔여석 정보가 아니다. 실제 이용 전에는 공식 코레일 예매 페이지에서 다시 확인해야 한다.

package/skills/ktx-booking/references/DISCLAIMER.md

@@ -1,14 +0,0 @@
-# DISCLAIMER — `ktx-booking`
-
-이 스킬은 한국철도공사·코레일·KTX의 공식 기능 또는 공식 지원 도구가 아니며, 공식 제휴·후원·승인·인증 또는 협업한 사실이 전혀 없습니다. 상표와 서비스명은 열차 조회·호환 대상을 설명하기 위해서만 사용합니다.
-
-대법원 2005. 6. 10. 선고 [2005도1637 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=83920)(소니용 리모컨 사건)은 기능 설명용 표장과 출처표시를 구별했습니다. [상표법 제2조](https://www.law.go.kr/법령/상표법/제2조), [제89조](https://www.law.go.kr/법령/상표법/제89조), [제90조](https://www.law.go.kr/법령/상표법/제90조), [제108조](https://www.law.go.kr/법령/상표법/제108조)에 따른 출처 혼동 판단은 별도입니다.
-
-대법원 2022. 5. 12. 선고 [2021도1533 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=221765)은 공개정보 수집만으로 곧바로 [정보통신망법 제48조](https://www.law.go.kr/법령/정보통신망이용촉진및정보보호등에관한법률/제48조) 위반이 되는 것은 아닌 사정을 제시했지만, 철도 예매 자동화·접근통제 우회·반복 선점을 허용하지 않습니다. [저작권법 제93조](https://www.law.go.kr/법령/저작권법/제93조)와 [형법 제314조 제2항](https://www.law.go.kr/법령/형법/제314조)도 별도입니다.
-
-- 공개 운행정보 자동 수집은 반드시 개인의 정보 조회용으로만 사용합니다.
-- 매진 감시, 조직적·대량 크롤링, 반복 선점·예약·취소, 공격적 polling을 하지 않습니다.
-- CAPTCHA·anti-bot·로그인·접근통제·rate limit·IP 차단을 우회하거나 차단 회피를 하지 않습니다.
-- `MACRO ERROR`나 접근 거부가 나타나면 즉시 중단하며 정상 예매 영업을 방해하지 않습니다.
-
-이 문서는 적법성을 보증하는 법률 자문이 아닙니다.

package/skills/ktx-booking/references/TRADEMARK-LEGAL-STATEMENT.md

@@ -1,9 +0,0 @@
-# 상표 사용 법적 고지 — `ktx-booking`
-
-이 스킬에서 `KTX`, `코레일`, `Korail` 명칭은 열차 조회·예약·취소의 **대상 철도 서비스와 운영기관**을 식별하기 위해 사용한다. k-skill의 출처나 운영주체를 코레일로 표시하려는 사용이 아니다.
-
-대법원 2005. 6. 10. 선고 [2005도1637 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=83920)은 타인의 표장을 출처표시가 아니라 상품 기능 또는 적용 기종을 밝히기 위해 사용하고 상표 사용으로 인식될 수 없는 경우 침해가 아니라고 판시했다. [상표법 제2조](https://www.law.go.kr/법령/상표법/제2조), [제89조](https://www.law.go.kr/법령/상표법/제89조), [제90조](https://www.law.go.kr/법령/상표법/제90조), [제108조](https://www.law.go.kr/법령/상표법/제108조)와 대법원 [2011다18802](https://www.law.go.kr/LSW/precInfoP.do?precSeq=167457), [2019후10418](https://law.go.kr/LSW/precInfoP.do?mode=0&precSeq=230725) 판결에 따라 실제 거래계에서 출처표시로 기능하는지는 표시 태양과 사용 경위 등을 종합해 판단해야 한다.
-
-따라서 이 명칭은 필요한 범위의 평문으로만 사용하고, 별도 근거 없이 로고, 공식·제휴·후원·인증·파트너 표현을 사용하지 않는다. 각 상표의 권리는 해당 권리자에게 있다. 이 문서는 운송계약, API·서비스 약관, 개인정보 또는 예약·결제 흐름의 적법성을 판단하지 않는다.
-
-전체 검토: [제3자 상표의 기능 설명·호환 대상 표시 검토](https://github.com/NomaDamas/k-skill/blob/dev/docs/legal/trademark-use-review.md)

package/skills/ktx-booking/skill.json

@@ -1,8 +0,0 @@
-{
-  "name": "ktx-booking",
-  "description": "Read-only KTX operating-timetable lookup from official Korail public XLSX attachments. No login, internal mobile API, anti-bot bypass, live seat availability, reservation, or payment.",
-  "profiles": [
-    "lookup"
-  ],
-  "frontmatter": "name: ktx-booking\ndescription: Read-only KTX operating-timetable lookup from official Korail public XLSX attachments. No login, internal mobile API, anti-bot bypass, live seat availability, reservation, or payment.\nlicense: MIT\nmetadata:\n  category: travel\n  locale: ko-KR\n  phase: v1"
-}

package/skills/srt-booking/instruction.md

@@ -1,75 +0,0 @@
-# SRT Live Timetable Lookup
-
-## What this skill does
-
-`SRTrain`의 시간표 검색 경로를 이용해 현재 SRT 운행 후보와 일반실·특실 예약 가능 여부를 조회한다.
-
-이 스킬은 회원 로그인 불필요한 **라이브 조회 전용**이다.
-
-- `auto_login=False` 익명 client를 사용한다.
-- NetFunnel 대기열과 시간표 검색 요청만 실행한다.
-- 예약, 예약대기, 좌석 선점, 결제, 취소, 자동 재조회는 실행하지 않는다.
-- 정확한 호차·좌석번호를 조회하지 않는다.
-- 구매는 공식 SRT 페이지에서 사용자가 직접 진행한다.
-
-실행 환경에는 Python 3.11 이상과 `uv`가 필요하다. `uv`가 없으면 공식 설치 문서를 안내하고 조회를 실행하지 않는다.
-
-## Commands
-
-```bash
-npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- \
-  search \
-  --dep 수서 \
-  --arr 부산 \
-  --date 20260819 \
-  --time 0600 \
-  --time-limit 1200 \
-  --limit 5
-```
-
-현재 라이브 조회 endpoint와 안전 경계:
-
-```bash
-npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- source
-```
-
-출력:
-
-- 열차번호·열차종류
-- 출발역·도착역
-- 현재 출발·도착 시각
-- 일반실·특실 예약 가능 여부
-- 사용한 라이브 search endpoint
-- 공식 SRT 페이지
-
-## Workflow
-
-1. 출발역, 도착역, 날짜, 시간대를 확인한다.
-2. `search`를 한 번 실행한다. `수서역`처럼 `역`이 붙은 입력은 helper가 표준 역명으로 정규화한다.
-3. 현재 운행 후보를 제시한다.
-4. 좌석 구매가 필요하면 `booking_url`을 제공하고 종료한다.
-5. 사용자가 다시 요청하지 않는 한 polling·매진 감시를 시작하지 않는다.
-
-## Hard boundaries
-
-- `KSKILL_SRT_ID`, `KSKILL_SRT_PASSWORD` 또는 회원 로그인을 요구하지 않는다.
-- helper에 `reserve`, `reservations`, `cancel`, `payment`, waiting-list 명령을 추가하지 않는다.
-- 예약 endpoint, 결제 endpoint 또는 계정 endpoint를 호출하지 않는다.
-- NetFunnel key를 예약·선점 자동화에 사용하지 않는다.
-- CAPTCHA·접근 거부·계정 제한이 발생하면 즉시 중단한다.
-- 사용자 요청 한 번을 반복 수집이나 장기 실행으로 확장하지 않는다.
-
-## Failure modes
-
-- NetFunnel 대기 또는 SRT 접근 제한
-- `SRTrain` 설치·호환성 문제
-- 날짜·시간 또는 역명 오류
-- 조건에 맞는 열차 없음
-
-이 경우 차단을 우회하지 않고 [SRT 공식 조회 페이지](https://etk.srail.kr/hpg/hra/01/selectScheduleList.do?pageId=TK0101010000)를 안내한다.
-
-## Legal notice
-
-```bash
-npx -y @nomadamas/k-skill@0 read srt-booking references/AUTOMATION-LEGAL-STATEMENT.md
-```