@nomadamas/k-skill 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomadamas/k-skill",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "k-skill unified CLI: assembles runtime-aware skill instructions and ships bundled helper files",
   "license": "MIT",
   "bin": {

package/skills/bccard-eatpl-search/instruction.md

@@ -0,0 +1,124 @@
+# BC카드 eat.pl 맛집 검색
+
+## What this skill does
+
+한국에서 맛집, 음식점, 식당, 밥집, 카페, 고깃집, 회식 장소를 찾을 때 쓴다. 사용자가 말한 장소를 먼저 `kakao-map`으로 정확한 도로명주소로 해석한 뒤, 그 주소를 중심으로 BC카드 eat.pl 잇플의 가맹점 검색을 조회한다. 결과는 반환 매출 랭킹 상위 순서를 보존하며, 사용자의 장르·동네·외국인 방문·회식·영업시간·혼잡 시간 조건으로 좁혀 표로 제시한다.
+
+추천은 별점 순위가 아니라 최근 1개월 BC카드 결제 데이터 기반 매출 순이다. 매출액(원)은 없고, 대신 `allSaleRnk`/`ccgSaleRnk` 백분위로 **얼마나 상위인지**를 반드시 숫자로 보여 준다. `srtTime`/`endTime`은 **영업 예상 시간**으로 정리한다. 모든 행에 eat.pl 상세 링크를 첨부한다.
+
+## 사용자 답변 규칙 (필수)
+
+사용자에게 보이는 답변에는 구현·연동 세부사항을 **절대 쓰지 않는다.** 결과는 맛집 추천처럼만 보여 준다.
+
+답변에 넣지 말 것:
+
+- endpoint, URL 경로, HTTP 메서드, curl, 프록시, 서버, 환경변수, 기관코드, 토큰, 상태코드
+- 내부 필드명 (`location`, `merTpbuzNm`, `allSaleRnk`, `ccgSaleRnk`, `merUrl`, `frnrVsitYn`, `empyVsitYn`, `srtTime` 등)
+- `k-skill-proxy`, 릴레이, Lightsail, gpu01, API, JSON, 캐시, 좌표 체계
+
+표의 전국·지역 매출 상위 %, 영업 예상 시간, `[eat.pl 상세](url)`, 출처 한 줄은 출력 계약대로 유지한다. 실패해도 오류 코드나 엔드포인트를 말하지 말고, 그 조건으로는 매장을 찾지 못했다고만 안내한다.
+
+## When to use
+
+먹을 곳, 식당, 카페를 달라는 요청이면 이 스킬을 쓴다. 예:
+
+- "맛집 추천해줘", "근처 음식점", "밥 먹을 곳", "분위기 좋은 식당"
+- "강남역 근처 고기집 중 매출 높은 곳"
+- "을지로입구역 주변 외국인이 많이 가는 카페"
+- "성수동에서 회식하기 좋은 맛집"
+- "이 동네 카페", "디저트 맛집", "회식 장소"
+
+술집·바만 찾는 요청은 `kakao-bar-nearby`를 우선한다.
+
+## Workflow
+
+아래 절차는 에이전트 내부 작업이다. 사용자 답변에 그대로 옮기지 않는다.
+
+1. 장소명이 모호하면 먼저 행정구역 또는 도로명주소를 확인한다. `kakao-map` 스킬을 우선 사용한다. 이 경로는 k-skill-proxy가 중계하는 **카카오 공식 Local REST API** (`GET /v1/kakao-map/search/keyword`, `coord2address` 등)이다. 카카오맵 웹 페이지를 스크래핑하지 않는다. 사용자가 지정한 경우 다른 지도 스킬로 교차 확인할 수 있다.
+2. 검색 중심은 장소의 정확한 주소에서 최소한 시·군·구와 도로명/동 단위로 정한다. eat.pl API는 텍스트 주소 부분일치 검색이며 반경(meter) 검색 API가 아니므로, API 결과를 실제 근처로 단정하지 말고 지도 스킬로 위치를 교차 확인한다.
+3. 다음 프록시 endpoint를 GET으로 호출한다.
+
+```bash
+curl -fsS --get "${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}/v1/bccard-eatpl/search" \
+  --data-urlencode 'location=서울 중구 을지로30길 20' \
+  --data-urlencode 'merTpbuzNm=카페'
+```
+
+지원 입력:
+
+- `location` 또는 `address`: 정확한 주소/지역 문자열
+- `merTpbuzNm`, `genre`, `business_type`: eat.pl 대분류 또는 소분류
+- `merNm`, `merchant_name`: 가맹점명 일부
+
+4. 최대 100건을 받은 뒤 지도 검색 결과와 주소·상호를 대조하고, 요청 조건에 맞는 매장만 남긴다. 존재하지 않는 리뷰·메뉴·주차·영업 여부를 추측하지 않는다.
+5. 아래 **출력 계약**을 만족하는 표만 사용자에게 보여 준다. 계약을 빠뜨린 표는 미완성이다.
+6. 반드시 `eat.pl 잇플 · BC카드 결제 데이터 기반`을 출처로 표기한다.
+
+## 출력 계약 (필수)
+
+표 컬럼: `가맹점명`, `주소`, `업종`, `전국 매출 상위`, `지역 매출 상위`, `동네 맛집`, `외국인 방문`, `회식 적합`, `영업 예상 시간`, `혼잡 요일/시간`, `주요 고객층`, `eat.pl 상세 링크`.
+
+### 매출이 얼마나 높은지
+
+- 매장마다 `전국 매출 상위 {allSaleRnk}%`, `지역 매출 상위 {ccgSaleRnk}%`를 빠짐없이 숫자로 쓴다. "매출이 높다"만 쓰지 않는다. 필드 이름 자체는 사용자에게 쓰지 않는다.
+- 백분위 값이 **낮을수록** 최근 1개월 BC카드 결제 매출 순위가 높다. `상위 0.09%`는 `상위 3%`보다 훨씬 위다.
+- 1% 미만은 소수점을 보존한다. 예: `0.04` → `전국 매출 상위 0.04%`.
+- 실제 매출액(원)은 제공되지 않는다. 백분위가 높낮이 정보다.
+
+### 영업 예상 시간
+
+- `srtTime`/`endTime`(HHMM)을 `영업 예상 시간 HH:MM–HH:MM`으로 변환한다. 예: `0702`+`2246` → `영업 예상 시간 07:02–22:46`.
+- 종료 시각이 시작보다 이르면 자정 넘김으로 `영업 예상 시간 18:14–익일 05:56`처럼 적는다.
+- 표 밖 한 줄로 "최근 1개월 결제 승인 시각 기반 추정이므로 공식 영업시간이 아님"을 고지한다.
+
+### 상세 링크 강제
+
+- **모든 행**에 응답 `merUrl`을 마크다운 링크로 첨부한다: `[eat.pl 상세]({merUrl})`.
+- `merUrl`이 없거나 `https://web.paybooc.ai/`로 시작하지 않으면 그 행을 출력하지 않는다.
+- 링크가 빠진 목록·표는 완성 결과가 아니다. URL 경로를 조합하거나 추측하지 않는다.
+
+## Credentials and proxy operations
+
+사용자에게 credentials를 묻거나 출력하지 않는다. 운영 환경에 다음 값을 secret으로 주입한다.
+
+- `BCCARD_EATPL_INST_NM`: 제휴 시 발급된 기관코드
+- `BCCARD_EATPL_API_BASE_URL`: 필수값, 기본값 없음 (미설정 시 503 `upstream_not_configured`). 운영 URL은 `https://api.paybooc.ai/api/mer`
+- `BCCARD_EATPL_RELAY_URL`: 선택값, 고정 outbound IP relay URL. 설정하면 proxy는 이 URL만 호출하고, 토큰 없이는 호출하지 않는다
+- `BCCARD_EATPL_RELAY_TOKEN`: 선택값, relay `Authorization: Bearer` 시크릿. gpu01 `k-skill-proxy` `.env`와 Lightsail relay env에만 저장한다. 사용자·클라이언트는 Lightsail을 직접 호출하지 않는다
+- `BCCARD_EATPL_API_TIMEOUT_MS`: 선택값, 기본 20000
+
+`trnsTrceNo`는 사용자가 입력하지 않는다. proxy가 기관코드 + 한국시간 기준 `YYYYMMDD` + 10자리 순번으로 매 요청 생성한다.
+
+## Important interpretation
+
+- 결과 자체가 매출 랭킹 상위 순이며, 별도 매출액은 제공되지 않는다. 높낮이는 전국·지역 백분위로만 말한다.
+- `allSaleRnk`/`ccgSaleRnk`는 퍼센트 백분위이며 낮을수록 상위다. 사용자 답변에는 필드명 대신 `전국 매출 상위 N%`로만 쓴다.
+- `srtTime`/`endTime`은 최근 1개월 결제 승인 시각 기반 **영업 예상 시간**이지 영업시간 공시가 아니다.
+- 실시간 영업 여부는 eat.pl 상세 페이지를 확인해야 하며, 조회 시점 관측과 다를 수 있다.
+- 전화번호는 유효하지 않을 수 있다.
+- 좌표는 TM128이므로 WGS84 지도 좌표로 직접 해석하지 않는다. 이 사실을 사용자에게 설명하지 않는다.
+
+## Failure modes
+
+내부 처리 기준이다. 사용자에게 코드명을 말하지 않는다.
+
+- `400 bad_request`: 주소·장르·가맹점명 중 하나도 없거나 입력이 잘못됨
+- `503 upstream_not_configured`: `BCCARD_EATPL_INST_NM` 미설정
+- `403/401 upstream_error`: IP 등록, 기관코드, 제휴 권한 또는 upstream 인증 문제
+- `502 upstream_error`: eat.pl 연결·서버 오류
+- `502 upstream_semantic_error`: `rspCode`가 성공이 아니거나 응답 구조가 명세와 다름
+- 개발 서버 연결 타임아웃: 개발 접근 정보 또는 네트워크/IP allowlist를 BC카드 측에 확인
+- 빈 결과: 주소 텍스트가 너무 좁거나 업종 표기가 맞지 않을 수 있으므로 임의 재시도하지 말고 주소 범위를 넓히거나 명세의 업종값을 확인
+
+## Legal and partnership notice
+
+이 스킬은 BC카드와의 공식 제휴 연동을 위해 제공되는 k-skill 구현물이라는 전제에서 사용한다. 다만 이 저장소와 k-skill 자체가 BC카드의 공식 제품·상표·지원 채널이라는 의미는 아니며, 실제 운영 전에는 BC카드의 제휴 승인·기관코드 발급·IP 등록·노출 문구 검수를 완료해야 한다. 출처는 항상 `eat.pl 잇플 · BC카드 결제 데이터 기반`으로 표시한다.
+
+## Done when
+
+- 장소를 `kakao-map`(k-skill-proxy 카카오 공식 Local API)으로 주소로 해석했다.
+- eat.pl 결과를 최대 100건까지 받아 지도 정보와 대조했다.
+- 사용자의 조건으로 필터링한 표에 전국·지역 매출 상위 %, 영업 예상 시간, eat.pl 상세 링크가 **모든 행**에 있다.
+- 매출 순 추천과 최근 1개월 결제 데이터 기준임을 설명했다.
+- 출처·제휴 전제·데이터 한계를 함께 고지했다.
+- 사용자 답변에 endpoint, 프록시, 환경변수, 내부 필드명이 없다.

package/skills/bccard-eatpl-search/references/DISCLAIMER.md

@@ -0,0 +1,11 @@
+# DISCLAIMER — `bccard-eatpl-search`
+
+이 스킬은 BC카드와 공식 제휴 연동을 전제로 설계된 구현물이다. 그러나 이 저장소, k-skill, 또는 이 스킬 자체가 BC카드·eat.pl 잇플의 공식 기능·공식 제품·공식 지원 채널·상표권자라는 뜻은 아니다. 서비스의 공식 제휴·협업 범위는 별도 계약으로 확인하며, 운영 노출 전에는 BC카드의 제휴 승인, 기관코드 발급, 호출 IP 등록, 개발·운영 endpoint 승인 및 표시 문구 검수를 완료해야 한다. 명칭은 기능 설명·조회 대상·링크 식별에만 사용한다.
+
+결과는 최근 1개월 BC카드 결제 데이터에서 집계된 가맹점 단위 정보다. 실제 매출액, 고객 개인 정보, 리뷰 평점, 현재 영업을 보증하지 않는다. `merUrl` 상세 페이지의 실시간 결제 기반 표시는 API의 분석 기반 영업 관측과 다를 수 있다.
+
+대법원 2005. 6. 10. 선고 [2005도1637 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=83920)과 대법원 2022. 5. 12. 선고 [2021도1533 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=221765)의 취지를 포함해, [상표법 제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조), [정보통신망법 제48조](https://www.law.go.kr/법령/정보통신망이용촉진및정보보호등에관한법률/제48조), [저작권법 제93조](https://www.law.go.kr/법령/저작권법/제93조), [형법 제314조 제2항](https://www.law.go.kr/법령/형법/제314조) 등 관련 법령과 계약 조건을 별도로 준수해야 한다.
+
+이 스킬은 공개적으로 허용된 공식 API와 지도 서비스만 사용한다. CAPTCHA, 인증, IP 제한, 접근통제, quota 또는 서비스 운영 정책을 우회하지 않는다. 영업 방해나 서비스 장애를 일으키는 조직적·대량 크롤링, 재배포·데이터베이스 구축이 아니라 개인의 장소 선택을 위한 제한된 조회에 사용한다.
+
+이 문서는 법률 자문이나 BC카드의 최종 승인을 대신하지 않는다.

package/skills/bccard-eatpl-search/references/TRADEMARK-LEGAL-STATEMENT.md

@@ -0,0 +1,7 @@
+# 상표 사용 법적 고지 — `bccard-eatpl-search`
+
+이 스킬에서 `BC카드`, `eat.pl`, `잇플`, `paybooc.ai` 명칭은 연동 대상 서비스와 응답 상세 링크를 식별하기 위해 필요한 범위에서 사용한다. 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조)에 따른 출처 혼동 판단은 표시 태양과 사용 경위에 따라 별도로 검토해야 한다.
+
+따라서 명칭은 기능 설명과 링크 식별에 필요한 평문으로만 사용하고, 별도 근거 없이 로고·인증·파트너 표현을 사용하지 않는다. 이 문서는 법률 자문이나 BC카드의 최종 승인을 대신하지 않는다.

package/skills/bccard-eatpl-search/skill.json

@@ -0,0 +1,6 @@
+{
+  "name": "bccard-eatpl-search",
+  "description": "대한민국 맛집, 음식점, 식당, 밥집, 카페, 커피, 디저트, 고깃집, 회식 장소를 지역·역·동네 기준으로 찾아 준다. Use when the user asks for 맛집, 음식점, 좋은 식당, 근처 카페, 밥 먹을 곳, 회식하기 좋은 곳, 분위기 좋은 맛집, or Korean restaurant and cafe recommendations. 별점이 아니라 최근 결제 데이터 기반 매출 상위로 정리한다.",
+  "profiles": ["proxy", "lookup"],
+  "frontmatter": "name: bccard-eatpl-search\ndescription: 대한민국 맛집, 음식점, 식당, 밥집, 카페, 커피, 디저트, 고깃집, 회식 장소를 지역·역·동네 기준으로 찾아 준다. Use when the user asks for 맛집, 음식점, 좋은 식당, 근처 카페, 밥 먹을 곳, 회식하기 좋은 곳, 분위기 좋은 맛집, or Korean restaurant and cafe recommendations. 별점이 아니라 최근 결제 데이터 기반 매출 상위로 정리한다.\nlicense: MIT\nmetadata:\n  category: food\n  locale: ko-KR\n  phase: v1"
+}

package/skills/komsa-ferry-info/instruction.md

@@ -0,0 +1,54 @@
+# KOMSA 연안여객선 정보 조회
+
+## What this skill does
+
+한국해양교통안전공단(KOMSA) MTIS Open API를 통해 연안여객선 운항 일정, 선박 제원, 기항지, 면허항로, 운항항로, 운항상태를 조회한다. 예매·결제·로그인 자동화는 하지 않는다.
+
+## Public access path
+
+기본 경로는 hosted/self-host `k-skill-proxy`의 좁은 read-only route다.
+
+- 공식 포털: <https://mtisopenapi.komsa.or.kr/>
+- 운항 일정: `https://mtisopenapi.komsa.or.kr/eopt/api/oprt-schd-info`
+- 운항노선: `https://mtisopenapi.komsa.or.kr/eopt/api/oprt-line-info`
+- 선박 제원: `https://mtisopenapi.komsa.or.kr/eopt/api/psnshp-spec`
+- 프록시: `GET /v1/komsa/ferry/{dataset}`
+
+지원 dataset은 `schedules`, `vessels`, `ports`, `license-routes`, `operation-routes`, `status`다. upstream `serviceKey`는 프록시 서버의 `KOMSA_MTIS_API_KEY` 또는 `KSKILL_KOMSA_MTIS_API_KEY`로만 주입한다.
+
+## Workflow
+
+Helper 실행:
+
+```bash
+npx -y @nomadamas/k-skill@0 exec komsa-ferry-info scripts/komsa_ferry_info.py -- \
+  schedules --date 20260824 --vessel 섬사랑12호 --limit 10
+```
+
+프록시를 직접 확인하려면:
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "$BASE/v1/komsa/ferry/schedules" \
+  --data-urlencode "date=20260824" \
+  --data-urlencode "vessel=섬사랑12호" \
+  --data-urlencode "limit=10"
+```
+
+입력은 날짜(`YYYYMMDD` 또는 `YYYY-MM-DD`), 선박명, 항로명, 기항지명, 페이지와 결과 수를 사용한다. 공식 MTIS 조회 파라미터는 명칭 필터이며, 매핑되지 않은 코드 필터는 `400`이다. 응답의 `items`는 공식 원문 필드를 보존하며, 일정 응답에는 출항일자·시각·출발지·도착지·항로·운항상태가 포함될 수 있다.
+
+## Done when
+
+- 공식 MTIS route를 통해 선택한 dataset을 조회했다.
+- 결과에 조회 dataset, 페이지, 결과 수와 공식 upstream 출처를 함께 표시했다.
+- 데이터가 5분 주기로 갱신될 수 있음을 밝히고, 운항정보를 예매 가능 좌석이나 결제 결과로 해석하지 않았다.
+
+## Failure modes
+
+- `400 bad_request`: 허용되지 않은 dataset, 매핑되지 않은 필터, 잘못된 날짜, 페이지 또는 결과 수.
+- `503 upstream_not_configured`: 프록시 운영자에게 `KOMSA_MTIS_API_KEY` 설정이 필요하다.
+- `502 upstream_error` / `502 upstream_invalid_response`: MTIS 인증 오류, quota 초과, upstream 장애 또는 응답 형식 변경.
+- `504 upstream_timeout`: 공식 API가 시간 내 응답하지 않음.
+- `total_count = 0`: 날짜·항로·선박 조건에 맞는 결과 없음.
+
+MTIS OpenAPI 이용신청/키 발급은 공식 포털 회원가입·로그인 후 진행한다. 키를 채팅, 저장소, GitHub Actions에 넣지 않는다.

package/skills/komsa-ferry-info/scripts/komsa_ferry_info.py

@@ -0,0 +1,76 @@
+"""Query KOMSA MTIS ferry information through k-skill-proxy."""
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+DEFAULT_PROXY = "https://k-skill-proxy.nomadamas.org"
+
+
+def proxy_base_url(value=None, env=None):
+    env = os.environ if env is None else env
+    candidate = (value or env.get("KSKILL_PROXY_BASE_URL") or DEFAULT_PROXY).strip()
+    if candidate.casefold() in {"off", "false", "0", "none"}:
+        raise ValueError("KSKILL_PROXY_BASE_URL is disabled.")
+    return candidate.rstrip("/")
+
+
+def query(dataset, params, *, base_url=None, read_json=None):
+    url = f"{proxy_base_url(base_url)}/v1/komsa/ferry/{urllib.parse.quote(dataset, safe='')}"
+    query_string = urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})
+    request = urllib.request.Request(
+        f"{url}?{query_string}",
+        headers={"Accept": "application/json", "User-Agent": "k-skill-komsa-ferry-info/1.0"},
+        method="GET",
+    )
+    if read_json:
+        return read_json(request)
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as error:
+        body = error.read().decode("utf-8", errors="replace")
+        try:
+            payload = json.loads(body)
+        except json.JSONDecodeError:
+            payload = {"error": f"HTTP {error.code}", "message": body}
+        raise RuntimeError(json.dumps(payload, ensure_ascii=False)) from error
+
+
+def parser():
+    result = argparse.ArgumentParser(description="KOMSA MTIS 연안여객선 정보 조회")
+    result.add_argument("dataset", choices=["schedules", "vessels", "ports", "license-routes", "operation-routes", "status"])
+    result.add_argument("--date")
+    result.add_argument("--vessel")
+    result.add_argument("--route")
+    result.add_argument("--port")
+    result.add_argument("--page", default="1")
+    result.add_argument("--limit", default="10")
+    result.add_argument("--proxy-base-url")
+    return result
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    params = {
+        "date": args.date,
+        "vessel": args.vessel,
+        "route": args.route,
+        "port": args.port,
+        "page": args.page,
+        "limit": args.limit,
+    }
+    try:
+        print(json.dumps(query(args.dataset, params, base_url=args.proxy_base_url), ensure_ascii=False, indent=2))
+        return 0
+    except (ValueError, RuntimeError) as error:
+        print(json.dumps({"error": str(error)}, ensure_ascii=False), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/komsa-ferry-info/skill.json

@@ -0,0 +1,6 @@
+{
+  "name": "komsa-ferry-info",
+  "description": "한국해양교통안전공단 KOMSA MTIS 공식 API로 연안여객선 운항 일정과 선박·항로 정보를 조회한다.",
+  "profiles": ["proxy", "lookup"],
+  "frontmatter": "name: komsa-ferry-info\ndescription: 한국해양교통안전공단 KOMSA MTIS 공식 API로 연안여객선 운항 일정과 선박·항로 정보를 조회한다.\nlicense: MIT\nmetadata:\n  category: transport\n  locale: ko-KR\n  phase: v1"
+}

package/skills/korean-privacy-terms/instruction.md

@@ -115,6 +115,7 @@ git -C ~/.agents/skills/korean-privacy-terms/upstream rev-parse HEAD
 - pin SHA 가 업스트림에서 삭제/force-push 된 경우: 스크립트가 SHA mismatch 로 비정상 종료한다. `scripts/upstream.pin` 을 최신 태그 SHA 로 bump 하고 PR 을 만든다.
 - Next.js Pages Router 단독 프로젝트: 업스트림이 실행을 중단한다. 사용자에게 App Router 전환이 선행 조건임을 안내한다.
 - 법률 개정 드리프트: 업스트림이 CHANGELOG 로 반영 기준을 관리한다. pin 만 올리지 말고 업스트림 CHANGELOG 를 함께 확인한다.
+- 한글 이용약관 템플릿 0바이트 (upstream, #660): pin 시점 기준 `jurisdictions/kr-pipa/terms-of-service.ko.mdx.tmpl` 과 `templates/terms-of-service.mdx.tmpl` 이 빈 파일이라 한국어(`outputLocale: ko`) 경로에서 이용약관을 생성할 수 없다. 개인정보처리방침(ko/en)과 영문 약관은 정상 생성된다. 업스트림에 템플릿이 채워지면 `scripts/upstream.pin` bump 로 해소한다. `install.sh` 가 설치 시 0바이트 템플릿을 경고로 표면화하므로 인터뷰 시작 전에 확인한다.
 
 ## Notes
 

package/skills/korean-privacy-terms/scripts/install.sh

@@ -66,6 +66,23 @@ if [[ "${HEAD_SHA}" != "${UPSTREAM_SHA}" ]]; then
   exit 1
 fi
 
+# 0바이트 템플릿 검증 (#660). 업스트림 파일이 빈 채 커밋돼 있으면 해당 경로의
+# 문서 생성이 조용히 실패하므로 설치 시점에 경고로 표면화한다. 다른 경로의
+# 문서는 정상 생성되므로 경고만 하고 설치는 계속한다.
+EMPTY_TEMPLATES=()
+while IFS= read -r -d '' EMPTY_FILE; do
+  EMPTY_TEMPLATES+=("${EMPTY_FILE#"${CLONE_DIR}/"}")
+done < <(find "${CLONE_DIR}" -type f -name '*.tmpl' -size 0 -print0)
+
+if (( ${#EMPTY_TEMPLATES[@]} > 0 )); then
+  echo "[korean-privacy-terms] warning: pinned upstream 에 0바이트 템플릿 ${#EMPTY_TEMPLATES[@]}건이 있다." >&2
+  for EMPTY_TEMPLATE in "${EMPTY_TEMPLATES[@]}"; do
+    echo "  - ${EMPTY_TEMPLATE}" >&2
+  done
+  echo "  해당 템플릿 경로의 문서는 생성되지 않는다. 나머지 경로는 정상 생성된다." >&2
+  echo "  상세와 해소 상태는 스킬 instruction.md 의 Failure modes 를 확인해달라." >&2
+fi
+
 # Dual-install targets. Both paths respect AGENTS.md indirection rules and do not
 # introduce repo-local skill directories.
 HOME_DIRS=(

package/skills/railway-timetable/instruction.md

@@ -0,0 +1,40 @@
+# Unified Railway Timetable Lookup
+
+## What this skill does
+
+`railway-timetable`은 코레일 공식 통합 시간표에서 KTX 계열 고속철도 운행 정보를 조회한다.
+
+- KTX: 한국철도공사 공식 공개 XLSX 통합 계획 시간표
+
+모든 경로는 조회 전용이다. 로그인·credential, 예약·예약대기·좌석 선점·결제·취소·자동 재조회는 실행하지 않는다.
+
+## Commands
+
+```bash
+npx -y @nomadamas/k-skill@0 exec railway-timetable scripts/railway_timetable.py -- \
+  search --dep 서울 --arr 부산 --date 20260904 \
+  --time 0600 --time-limit 1200 --limit 5
+```
+
+```bash
+npx -y @nomadamas/k-skill@0 exec railway-timetable scripts/railway_timetable.py -- source
+```
+
+## Output
+
+- `count`, `trains[]`, `date`
+- 각 열차의 `operator`, `train_no`, `train_type`, `dep`, `arr`, `dep_time`, `arr_time`
+- 공식 `source`와 예약 진입 URL
+
+결과는 코레일 통합 공개 계획 시간표이며 실제 운휴·지연, 예약 성공, 좌석 선점을 보장하지 않는다.
+
+## Sources and failure modes
+
+- 코레일: 공개 게시판의 XLSX를 읽는다. 게시판·파일 장애, 적용 시간표 없음, 형식 변경, 구간 결과 없음이 발생할 수 있다.
+- CAPTCHA·인증·접근 차단은 우회하지 않고 코레일 공식 페이지를 안내한다.
+
+## Hard boundaries
+
+- 회원 로그인·credential 요청 금지
+- 예약·결제·취소·정확한 좌석 선택·자동 polling 금지
+- 내부 모바일 API, anti-bot, CAPTCHA, 인증 통제 우회 금지

package/skills/railway-timetable/references/AUTOMATION-LEGAL-STATEMENT.md

@@ -0,0 +1,5 @@
+# 철도 통합 시간표 조회 관련 고지
+
+- KTX 계열 코레일 통합 시간표는 공개 XLSX 계획 시간표만 읽는다.
+- 예약·예약대기·좌석 선점·결제·취소·자동 재조회는 실행하지 않는다.
+- CAPTCHA, 본인인증, anti-bot, 접근 제한을 우회하지 않는다.

package/skills/railway-timetable/references/DISCLAIMER.md

@@ -0,0 +1,7 @@
+# DISCLAIMER — `railway-timetable`
+
+이 스킬은 한국철도공사·코레일 또는 다른 철도 운영사의 공식 기능이나 공식 지원 도구가 아니며, 제휴·후원·승인·인증 또는 협업한 사실이 없습니다. 명칭과 상표는 조회 대상 서비스를 식별하기 위해서만 사용합니다.
+
+공개 정보의 개인적 조회는 비조직적 용도로 제한한다. 체계적·대량 수집, 데이터베이스 구축, 접근통제·차단 우회, 서비스 운영을 방해하는 행위에 사용하지 않는다.
+
+관련 기준으로 대법원 2005도1637 및 2021도1533 판결, 정보통신망법 제48조와 저작권법 제93조를 참고한다. 이 문서는 개별 사실관계에 대한 법률 자문이나 위법성 판단이 아니다.

package/skills/railway-timetable/references/TRADEMARK-LEGAL-STATEMENT.md

@@ -0,0 +1,3 @@
+# 상표 사용 법적 고지 — `railway-timetable`
+
+`KTX`, `코레일`, `Korail` 명칭은 조회 대상 열차·운영기관을 식별하기 위해서만 사용한다. k-skill이 해당 운영기관의 공식 제품이거나 승인받았다는 의미가 아니다.

package/skills/{ktx-booking → railway-timetable}/scripts/ktx_timetable.py

@@ -120,8 +120,6 @@ def parse_timetable_rows(
                 if section.type_index >= 0
                 else "KTX"
             )
-            if "KTX" not in train_type:
-                continue
             if section.note_index >= 0 and not runs_on_date(row[section.note_index], requested_date):
                 continue
             dep_time = normalize_time(row[section.dep_index])

package/skills/railway-timetable/scripts/railway_timetable.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env -S uv run --locked --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["openpyxl==3.1.5"]
+# ///
+"""Read-only Korail integrated railway timetable lookup."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+import ktx_backend
+
+
+def source_info() -> dict[str, Any]:
+    return {
+        "mode": "plan",
+        "transport": "Korail integrated timetable",
+        "operator": "한국철도공사",
+        "endpoint": ktx_backend.BOARD_URL,
+        "authentication": "none",
+        "mutation": "none; timetable lookup only",
+        "booking_url": ktx_backend.BOOKING_URL,
+    }
+
+
+def search(
+    *,
+    dep: str,
+    arr: str,
+    date: str,
+    earliest: str,
+    latest: str,
+    limit: int,
+) -> dict[str, Any]:
+    result = ktx_backend.search_public_timetable(
+        dep=dep,
+        arr=arr,
+        date=date,
+        earliest=earliest,
+        latest=latest,
+        limit=limit,
+    )
+    return {
+        **result,
+        "schedule_note": "코레일 통합 공개 운행계획 기준이며 실시간 운휴·지연·잔여석 정보가 아닙니다.",
+        "source": {**result["source"], "transport": "Korail integrated timetable"},
+    }
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Korail integrated read-only railway timetable lookup",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    search_parser = commands.add_parser("search", help="search railway timetables")
+    search_parser.add_argument("--dep", required=True)
+    search_parser.add_argument("--arr", required=True)
+    search_parser.add_argument("--date", required=True, help="YYYYMMDD")
+    search_parser.add_argument("--time", default="0000", help="earliest departure, HHMM")
+    search_parser.add_argument("--time-limit", default="2359", help="latest departure, HHMM")
+    search_parser.add_argument("--limit", type=int, default=10)
+    commands.add_parser("source", help="show read-only timetable sources")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "source":
+            print(json.dumps(source_info(), ensure_ascii=False, indent=2))
+            return 0
+        if args.limit < 1 or args.limit > 50:
+            raise ValueError("--limit must be between 1 and 50")
+        result = search(
+            dep=args.dep,
+            arr=args.arr,
+            date=args.date,
+            earliest=args.time,
+            latest=args.time_limit,
+            limit=args.limit,
+        )
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    except (RuntimeError, ValueError) as exc:
+        parser.error(str(exc))
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/railway-timetable/scripts/railway_timetable.py.lock

@@ -0,0 +1,27 @@
+version = 1
+revision = 1
+requires-python = ">=3.11"
+
+[manifest]
+requirements = [{ name = "openpyxl", specifier = "==3.1.5" }]
+
+[[package]]
+name = "et-xmlfile"
+version = "2.0.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d3/38/af70d7ab1ae9d4da450eeec1fa3918940a5fafb9055e934af8d6eb0c2313/et_xmlfile-2.0.0.tar.gz", hash = "sha256:dab3f4764309081ce75662649be815c4c9081e88f0837825f90fd28317d4da54", size = 17234 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c1/8b/5fe2cc11fee489817272089c4203e679c63b570a5aaeb18d852ae3cbba6a/et_xmlfile-2.0.0-py3-none-any.whl", hash = "sha256:7a91720bc756843502c3b7504c77b8fe44217c85c537d85037f0f536151b2caa", size = 18059 },
+]
+
+[[package]]
+name = "openpyxl"
+version = "3.1.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "et-xmlfile" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3d/f9/88d94a75de065ea32619465d2f77b29a0469500e99012523b91cc4141cd1/openpyxl-3.1.5.tar.gz", hash = "sha256:cf0e3cf56142039133628b5acffe8ef0c12bc902d2aadd3e0fe5878dc08d1050", size = 186464 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c0/da/977ded879c29cbd04de313843e76868e6e13408a94ed6b987245dc7c8506/openpyxl-3.1.5-py2.py3-none-any.whl", hash = "sha256:5282c12b107bffeef825f4617dc029afaf41d0ea60823bbb665ef3079dc79de2", size = 250910 },
+]

package/skills/railway-timetable/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "railway-timetable",
+  "description": "Read-only Korail integrated railway timetable lookup covering KTX-family trains. No reservation, payment, cancellation, or seat holding.",
+  "profiles": [
+    "lookup"
+  ],
+  "frontmatter": "name: railway-timetable\ndescription: Read-only Korail integrated railway timetable lookup covering KTX-family trains. No reservation, payment, cancellation, or seat holding.\nlicense: MIT\nmetadata:\n  category: travel\n  locale: ko-KR\n  phase: v1"
+}