@nomadamas/k-skill 0.4.3 → 0.5.0

package/package.json

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

package/skills/animal-pharmacy-search/instruction.md

@@ -0,0 +1,150 @@
+# 동물약국·동물용의약품 취급 약국 조회
+
+## What this skill does
+
+홍익메디케어가 운영하는 인증 없는 공개 Streamable HTTP MCP 서버를 직접 호출한다.
+
+- 엔드포인트: `https://hkmedi.co.kr/pharmacy-mcp`
+- 지역별 동물약국 목록 조회
+- 제품명·분류·증상 키워드로 동물용의약품 검색
+- 특정 제품을 최근 6개월 안에 홍익메디케어에서 구매한 약국 조회
+- 별도 API key나 `k-skill-proxy` 없이 사용자 머신에서 직접 호출
+
+이 데이터는 민간 유통사인 홍익메디케어의 거래·디렉터리 데이터다. 공공기관의
+동물약국 인허가 원장이나 전국 모든 유통사의 판매 자료가 아니다.
+
+## When to use
+
+- "서울 강남구 동물약국 알려줘"
+- "목포시 동물약국 리스트 찾아줘"
+- "동물용 항생제 제품 뭐가 있어?"
+- "오리더밀 취급하는 서울 약국 찾아줘"
+- "피부 관련 동물약 파는 인천 약국 있어?"
+
+## When not to use
+
+- 동물의 증상을 진단하거나 약을 처방·추천해야 하는 요청
+- 용량, 투여 주기, 병용 가능 여부를 결정하는 요청
+- 현재 매장 재고를 확정하거나 구매를 자동화하는 요청
+- 공공기관의 공식 인허가 상태·행정처분 확인이 필요한 요청
+
+동물의 상태가 위급하거나 약물 선택이 필요한 경우 수의사 진료를 우선 안내한다.
+
+## Access path
+
+기본 경로는 bundled helper다.
+
+```bash
+npx -y @nomadamas/k-skill@0 exec animal-pharmacy-search scripts/animal_pharmacy_mcp.py -- tools
+```
+
+helper는 Python 표준 라이브러리만 사용해 MCP `initialize` 후 세션 ID를 유지하며
+`tools/list` 또는 `tools/call`을 실행한다. 서버가 JSON 또는 SSE로 응답해도
+동일한 JSON 결과로 정규화한다.
+
+직접 MCP 클라이언트에 등록할 수도 있다.
+
+```bash
+claude mcp add --transport http animal-pharmacy https://hkmedi.co.kr/pharmacy-mcp
+codex mcp add animal-pharmacy --url https://hkmedi.co.kr/pharmacy-mcp
+```
+
+## Tool selection
+
+| 사용자 요청 | MCP 도구 | 주요 입력 |
+| --- | --- | --- |
+| 지역별 동물약국 목록 | `find_animal_pharmacies` | `city`, 선택 `gu`, `keyword`, `limit` |
+| 제품명·분류·증상 키워드 검색 | `search_product` | `keyword` |
+| 제품 취급 약국 조회 | `find_pharmacies_by_product` | `item_srl` 또는 `product_name`, 선택 `city`, `gu`, `limit` |
+
+### 지역별 동물약국
+
+```bash
+npx -y @nomadamas/k-skill@0 exec animal-pharmacy-search scripts/animal_pharmacy_mcp.py -- \
+  call find_animal_pharmacies \
+  --arg city=서울 \
+  --arg gu=강남구 \
+  --arg limit=5
+```
+
+`result._meta.pharmacies`에서 약국명, 전화번호, 주소, 행정구역, 좌표를 읽는다.
+사용자가 지역을 주지 않았다면 시·도와 시·군·구를 먼저 묻는다.
+
+### 제품 검색
+
+```bash
+npx -y @nomadamas/k-skill@0 exec animal-pharmacy-search scripts/animal_pharmacy_mcp.py -- \
+  call search_product \
+  --arg keyword=항생제
+```
+
+제품명뿐 아니라 서버가 등록한 분류·증상 태그도 검색한다. `keyword`는 최소
+2글자여야 한다. 결과의 `item_srl`과 `item_name`을 제시하되, 검색 결과를
+진단·처방·효능 보증으로 해석하지 않는다.
+
+### 제품 취급 약국
+
+제품명이 충분히 구체적이면 `product_name`으로 바로 검색할 수 있다.
+
+```bash
+npx -y @nomadamas/k-skill@0 exec animal-pharmacy-search scripts/animal_pharmacy_mcp.py -- \
+  call find_pharmacies_by_product \
+  --arg product_name=오리더밀 \
+  --arg city=서울 \
+  --arg limit=5
+```
+
+제품명이 모호하거나 동명이 여러 개면 먼저 `search_product`로 `item_srl`을
+확인한 뒤 정확 조회한다.
+
+```bash
+npx -y @nomadamas/k-skill@0 exec animal-pharmacy-search scripts/animal_pharmacy_mcp.py -- \
+  call find_pharmacies_by_product \
+  --arg item_srl=4452 \
+  --arg city=서울 \
+  --arg limit=5
+```
+
+## Provenance and interpretation
+
+`find_pharmacies_by_product` 결과에는 반드시 아래 의미를 함께 전달한다.
+
+- 약국은 **최근 6개월 안에 홍익메디케어에서 해당 제품을 구매한 이력** 기준이다.
+- 이 기준은 해당 약국의 과거 취급 근거이지 현재 재고·판매 가능 여부 보장이 아니다.
+- 다른 유통사를 통한 구매나 전국 모든 동물약국을 포괄하지 않을 수 있다.
+- 방문 전에 전화로 제품명과 현재 재고를 확인하도록 안내한다.
+
+`find_animal_pharmacies`는 지역 디렉터리이며 제품 취급 여부를 뜻하지 않는다.
+제품까지 확인하려면 별도로 `find_pharmacies_by_product`를 호출한다.
+
+## Response style
+
+- 보통 3~5곳만 약국명, 전화번호, 주소 순으로 정리한다.
+- 제품 검색은 제품명과 `item_srl`을 함께 보여준다.
+- 취급 약국 결과에는 최근 6개월 홍익메디케어 구매 이력 기준임을 한 문장으로 명시한다.
+- 좌표는 사용자가 지도 연결을 원할 때만 보조 정보로 쓴다.
+- 전화번호와 주소는 조회 목적에 필요한 공개 사업장 정보로만 사용한다.
+
+## Failure modes
+
+- `406 Not Acceptable` 또는 SSE 요구: `Accept: application/json, text/event-stream`을 모두 보낸다.
+- `keyword must be at least 2 characters`: 2글자 이상의 키워드로 다시 검색한다.
+- 빈 제품 결과: 다른 제품명·분류·증상 키워드를 제안한다.
+- 빈 약국 결과: `gu`를 빼고 시·도 단위로 넓히거나 지역 표기를 확인한다.
+- MCP 세션 오류: 새 `initialize`로 세션을 다시 만든다. 무한 재시도하지 않는다.
+- 연결 실패·5xx: 홍익메디케어 민간 MCP 장애로 보고 현재 조회 불가를 알린다.
+- 현재 재고 확인 요청: MCP 결과만으로 확정하지 않고 약국 전화 확인을 안내한다.
+
+## Privacy
+
+- 인증·로그인·개인정보 입력이 없는 공개 조회 전용이다.
+- 사용자나 반려동물의 의료정보를 서버에 전달하지 않는다.
+- 진단·처방·복약 결정을 대신하지 않는다.
+
+## Done when
+
+- 지역 목록, 제품 검색, 제품 취급 약국 중 맞는 도구를 선택했다.
+- 실제 MCP 응답의 `_meta` 구조를 기준으로 결과를 정리했다.
+- 제품 취급 약국에는 최근 6개월 홍익메디케어 구매 이력이라는 출처와 한계를 명시했다.
+- 현재 재고는 보장되지 않으므로 방문 전 전화 확인을 안내했다.
+- 진단·처방 없이 조회 결과만 제공했다.

package/skills/animal-pharmacy-search/scripts/animal_pharmacy_mcp.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+"""홍익메디케어 공개 Streamable HTTP MCP 서버를 호출한다."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from typing import Any, Sequence
+
+DEFAULT_ENDPOINT = "https://hkmedi.co.kr/pharmacy-mcp"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+PROTOCOL_VERSION = "2025-03-26"
+USER_AGENT = "k-skill-animal-pharmacy/1.0"
+
+
+class AnimalPharmacyMcpError(RuntimeError):
+    """설정 또는 MCP 호출 실패 때 발생한다."""
+
+
+def parse_json_object(raw: str, *, arg_name: str) -> dict[str, Any]:
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise argparse.ArgumentTypeError(
+            f"{arg_name}은 올바른 JSON이어야 합니다: {exc}"
+        ) from exc
+    if not isinstance(value, dict):
+        raise argparse.ArgumentTypeError(f"{arg_name}은 JSON 객체여야 합니다")
+    return value
+
+
+def parse_positive_float(raw: str) -> float:
+    try:
+        value = float(raw)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("timeout은 숫자여야 합니다") from exc
+    if value <= 0:
+        raise argparse.ArgumentTypeError("timeout은 0보다 커야 합니다")
+    return value
+
+
+def parse_kv_pairs(pairs: Sequence[str]) -> dict[str, Any]:
+    args: dict[str, Any] = {}
+    for pair in pairs:
+        if "=" not in pair:
+            raise argparse.ArgumentTypeError(
+                f"인자 '{pair}'는 key=value 형식이어야 합니다"
+            )
+        key, raw_value = pair.split("=", 1)
+        if not key:
+            raise argparse.ArgumentTypeError(
+                f"인자 '{pair}'의 key가 비어 있습니다"
+            )
+        try:
+            value = json.loads(raw_value)
+        except json.JSONDecodeError:
+            value = raw_value
+        args[key] = value
+    return args
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="홍익메디케어 동물약국 MCP 도구를 호출합니다.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "예시:\n"
+            "  animal_pharmacy_mcp.py tools\n"
+            "  animal_pharmacy_mcp.py call find_animal_pharmacies --arg city=서울 --arg gu=강남구\n"
+            "  animal_pharmacy_mcp.py call search_product --arg keyword=항생제\n"
+            "  animal_pharmacy_mcp.py call find_pharmacies_by_product --arg product_name=오리더밀 --arg city=서울\n"
+        ),
+    )
+    parser.add_argument(
+        "--endpoint",
+        default=os.getenv("ANIMAL_PHARMACY_MCP_ENDPOINT", DEFAULT_ENDPOINT),
+        help="동물약국 MCP 엔드포인트(기본값: %(default)s).",
+    )
+    parser.add_argument(
+        "--timeout-seconds",
+        type=parse_positive_float,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        help="각 MCP HTTP 요청 제한 시간(기본값: %(default)s초).",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    subparsers.add_parser(
+        "tools", help="사용 가능한 MCP 도구와 입력 스키마를 JSON으로 출력합니다."
+    )
+
+    call_parser = subparsers.add_parser(
+        "call", help="MCP 도구 하나를 호출하고 결과를 JSON으로 출력합니다."
+    )
+    call_parser.add_argument(
+        "tool",
+        choices=[
+            "find_animal_pharmacies",
+            "search_product",
+            "find_pharmacies_by_product",
+        ],
+        help="호출할 동물약국 MCP 도구명.",
+    )
+    call_parser.add_argument(
+        "--json",
+        dest="json_args",
+        type=lambda raw: parse_json_object(raw, arg_name="--json"),
+        default=None,
+        help="도구 인자를 JSON 객체로 전달합니다.",
+    )
+    call_parser.add_argument(
+        "--arg",
+        dest="kv_args",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="도구 인자입니다. 반복 지정할 수 있습니다.",
+    )
+    return parser.parse_args(argv)
+
+
+def parse_mcp_response(raw: bytes, content_type: str) -> dict[str, Any]:
+    text = raw.decode("utf-8")
+    if "text/event-stream" in content_type:
+        data_lines = [
+            line[6:] for line in text.splitlines() if line.startswith("data: ")
+        ]
+        if not data_lines:
+            raise AnimalPharmacyMcpError("MCP SSE 응답에 data 이벤트가 없습니다")
+        text = data_lines[-1]
+
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise AnimalPharmacyMcpError(
+            f"MCP 응답이 올바른 JSON이 아닙니다: {exc}"
+        ) from exc
+    if not isinstance(payload, dict):
+        raise AnimalPharmacyMcpError("MCP 응답이 JSON 객체가 아닙니다")
+    if "error" in payload:
+        error = payload["error"]
+        message = error.get("message", str(error)) if isinstance(error, dict) else str(error)
+        raise AnimalPharmacyMcpError(message)
+    return payload
+
+
+def post_rpc(
+    endpoint: str,
+    payload: dict[str, Any],
+    *,
+    timeout_seconds: float,
+    session_id: str | None = None,
+) -> tuple[dict[str, Any], str | None]:
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+        "User-Agent": USER_AGENT,
+    }
+    if session_id:
+        headers["Mcp-Session-Id"] = session_id
+
+    request = urllib.request.Request(
+        endpoint,
+        data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+        headers=headers,
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout_seconds) as response:
+            parsed = parse_mcp_response(
+                response.read(),
+                response.headers.get("Content-Type", ""),
+            )
+            return parsed, response.headers.get("Mcp-Session-Id") or session_id
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise AnimalPharmacyMcpError(
+            f"동물약국 MCP HTTP {exc.code}: {detail}"
+        ) from exc
+    except urllib.error.URLError as exc:
+        raise AnimalPharmacyMcpError(
+            f"동물약국 MCP 연결 실패 {endpoint}: {exc.reason}"
+        ) from exc
+    except TimeoutError as exc:
+        raise AnimalPharmacyMcpError(
+            f"동물약국 MCP 요청 시간이 {timeout_seconds:g}초를 초과했습니다"
+        ) from exc
+
+
+def initialize(endpoint: str, *, timeout_seconds: float) -> str:
+    payload, session_id = post_rpc(
+        endpoint,
+        {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {},
+                "clientInfo": {
+                    "name": "k-skill-animal-pharmacy",
+                    "version": "1.0.0",
+                },
+            },
+        },
+        timeout_seconds=timeout_seconds,
+    )
+    if "result" not in payload:
+        raise AnimalPharmacyMcpError("MCP initialize 응답에 result가 없습니다")
+    if not session_id:
+        raise AnimalPharmacyMcpError("MCP initialize 응답에 세션 ID가 없습니다")
+    return session_id
+
+
+def run_mcp(
+    endpoint: str,
+    command: str,
+    tool: str | None = None,
+    arguments: dict[str, Any] | None = None,
+    *,
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+) -> Any:
+    session_id = initialize(endpoint, timeout_seconds=timeout_seconds)
+    if command == "tools":
+        payload = {
+            "jsonrpc": "2.0",
+            "id": 2,
+            "method": "tools/list",
+            "params": {},
+        }
+    elif command == "call" and tool:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": 2,
+            "method": "tools/call",
+            "params": {"name": tool, "arguments": arguments or {}},
+        }
+    else:
+        raise AnimalPharmacyMcpError(f"지원하지 않는 명령입니다: {command}")
+
+    response, _ = post_rpc(
+        endpoint,
+        payload,
+        timeout_seconds=timeout_seconds,
+        session_id=session_id,
+    )
+    return response.get("result")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = parse_args(argv)
+    tool_args: dict[str, Any] | None = None
+    if args.command == "call":
+        tool_args = dict(args.json_args or {})
+        tool_args.update(parse_kv_pairs(args.kv_args))
+
+    try:
+        result = run_mcp(
+            args.endpoint,
+            args.command,
+            getattr(args, "tool", None),
+            tool_args,
+            timeout_seconds=args.timeout_seconds,
+        )
+    except AnimalPharmacyMcpError as exc:
+        print(f"animal_pharmacy_mcp.py: {exc}", file=sys.stderr)
+        return 2
+
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/animal-pharmacy-search/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "animal-pharmacy-search",
+  "description": "홍익메디케어 공개 MCP 서버로 지역별 동물약국 목록, 동물용의약품 검색, 최근 6개월 구매 이력 기반 취급 약국을 조회한다. 조회 전용.",
+  "profiles": [
+    "lookup"
+  ],
+  "frontmatter": "name: animal-pharmacy-search\ndescription: 홍익메디케어 공개 MCP 서버로 지역별 동물약국 목록, 동물용의약품 검색, 최근 6개월 구매 이력 기반 취급 약국을 조회한다. 조회 전용.\nlicense: MIT\nmetadata:\n  category: health\n  locale: ko-KR\n  phase: v1"
+}

package/skills/consumer-price-safety-search/instruction.md

@@ -0,0 +1,30 @@
+# 소비자 가격·안전 조회
+
+## Draft status
+
+이 스킬은 #390의 **draft scaffold**다. 참가격과 소비자24는 서로 다른
+upstream이다. 소비자24는 `openapiSvcId`(서비스 카탈로그 ID), 서비스별
+승인 `serviceKey`, 리콜 메뉴 `cntntsId`를 분리해 관리해야 한다.
+
+## Planned v1
+
+- 참가격 품목·지역별 가격
+- 소비자24 물품정보
+- 소비자24 전체 신청 서비스의 리콜 정보
+- 서비스별 키 allowlist와 공식 오류 코드 보존
+
+## Credential model
+
+`serviceKey`만 secret이며 gpu01 runtime env에 보관한다. `openapiSvcId`와
+`cntntsId`는 공개 매핑이므로 저장소 코드에 둘 수 있다. 최종 env 이름과
+서비스별 성공 여부는 live probe 후 확정한다.
+
+## Official sources
+
+- 참가격: https://www.data.go.kr/dataset/3043385/openapi.do
+- 소비자24 목록: https://www.consumer.go.kr/user/ftc/consumer/openApiSvcUser/120/selectOpenApiSvcList.do
+
+## Draft stop condition
+
+전체 신청 서비스별 키가 실제 성공하는지 확인하고 실패하는 live E2E부터
+추가한 뒤 proxy route, helper, parser, 문서와 manual QA를 완성한다.

package/skills/consumer-price-safety-search/skill.json

@@ -0,0 +1,6 @@
+{
+  "name": "consumer-price-safety-search",
+  "description": "한국소비자원 참가격과 소비자24 물품·리콜정보를 공식 API로 조회한다. 현재는 서비스별 인증키·메뉴 매핑을 검증하는 draft scaffold다.",
+  "profiles": ["proxy", "lookup"],
+  "frontmatter": "name: consumer-price-safety-search\ndescription: 한국소비자원 참가격과 소비자24 물품·리콜정보를 공식 API로 조회한다. 현재는 서비스별 인증키·메뉴 매핑을 검증하는 draft scaffold다.\nlicense: MIT\nmetadata:\n  category: consumer\n  locale: ko-KR\n  phase: draft"
+}

package/skills/government-support-survey/instruction.md

@@ -0,0 +1,52 @@
+# 정부지원 전수조사
+
+## What this skill does
+
+`k-skill-proxy`의 `/v1/government-support/survey`를 호출해 다음 공개 공고를 하나의 스키마로 조사한다.
+
+- K-Startup Open API
+- 기업마당
+- 정보통신산업진흥원(NIPA)
+- 한국콘텐츠진흥원(KOCCA)
+- 중소기업기술개발사업 종합관리시스템(SMTECH)
+
+이 스킬은 현재 모집 공고의 제목·분야·주관기관·접수기간·공식 URL을 수집하고, 사용자의 프로젝트 조건과 대조해 `즉시 지원 가능`, `요건 충족 시 가능`, `사업 변형 시 가능`, `부적합`으로 보수적으로 분류한다.
+
+## Required workflow
+
+1. 회사·팀·프로젝트의 업력, 소재지, 업종, 기술, 대표자 연령, 기업 형태, 매출·투자 단계, 원하는 지원 유형을 확인한다.
+2. 먼저 5개 소스를 모두 조회한다. 사용자가 범위를 좁힌 경우에만 `--sources`를 제한한다.
+3. 응답의 `complete`와 소스별 `ok`를 확인한다. 하나라도 실패하면 “전수조사 완료”라고 표현하지 말고 누락 소스를 명시한다.
+4. 제목만으로 자격을 확정하지 않는다. 후보의 공식 상세 URL과 첨부 공고문에서 신청대상·제외조건·지역·업력·중복수혜 제한을 확인한다.
+5. 결과마다 공식 출처 URL, 접수 마감일, 판정 근거, 추가 확인사항을 표시한다.
+6. 실제 신청은 공식 사이트에서 진행한다. 최종 제출 직전에는 사용자 승인을 받는다.
+
+## Command
+
+```bash
+npx -y @nomadamas/k-skill@0 exec government-support-survey scripts/run_survey.py -- \
+  --sources kstartup bizinfo nipa kocca smtech \
+  --keyword "AI 바우처" \
+  --max-pages 3
+```
+
+전체 공고를 넓게 조사할 때는 `--keyword`를 생략한다. 응답이 너무 클 때만 공고 유형별 키워드로 여러 번 나눠 조회한다.
+
+## Output contract
+
+- `complete`: 요청한 모든 소스가 정상 조사됐는지
+- `sources`: 소스별 성공 여부, 조회 페이지, 수집 건수, 오류
+- `items`: `source`, `id`, `title`, `field`, `org`, `apply_start`, `apply_end`, `reg_date`, `url`
+- `attribution`: upstream 코드와 공식 데이터 출처, 재배포 범위
+
+## Failure modes
+
+- `complete=false`: 일부 소스 실패. 수집된 결과는 부분 결과이며 누락 소스를 수동 확인한다.
+- `401/403` 또는 차단 신호: 우회하지 말고 공식 브라우저 화면으로 전환한다.
+- `0 items parsed; site layout may have changed`: 파서 개편 가능성이므로 해당 소스를 성공 처리하지 않는다.
+- K-Startup 키 미설정: 나머지 공개 포털 결과는 유지하되 K-Startup 누락을 명시한다.
+- CAPTCHA·로그인·본인인증: 자동 우회하지 않는다.
+
+## Legal and redistribution boundary
+
+이 스킬의 조사 로직은 `djfksjd/ir-search`의 MIT 라이선스 구현을 참고해 재작성했으며 저작권·라이선스 고지는 `npx -y @nomadamas/k-skill@0 read government-support-survey references/NOTICE.md`에 보존한다. 정부 포털 공고 원문과 첨부는 포털별 이용조건이 다르므로 k-skill은 이를 미러링하거나 재배포하지 않고 구조화 메타데이터와 공식 링크만 제공한다.

package/skills/government-support-survey/references/NOTICE.md

@@ -0,0 +1,30 @@
+# 출처, 라이선스, 재배포 범위
+
+## 참고한 오픈소스
+
+- 프로젝트: [djfksjd/ir-search](https://github.com/djfksjd/ir-search)
+- 라이선스: [MIT License](https://github.com/djfksjd/ir-search/blob/main/LICENSE)
+- 원 저작권 표시: `Copyright (c) 2026 ir-search contributors`
+
+MIT 라이선스는 사용·수정·병합·배포·재라이선스를 허용하며, 소프트웨어의 복제물 또는 중요한 부분에 저작권 고지와 허가 고지를 포함해야 한다. 이 문서는 해당 attribution을 보존한다.
+
+이번 통합은 upstream 파일을 그대로 복제하지 않고, 공개 포털 접근 경로·정규화 스키마·fail-closed 원칙을 참고해 k-skill-proxy의 Node.js 구현과 k-skill CLI 계약으로 재작성했다.
+
+## 공식 데이터 출처
+
+| 소스 | 공식 URL | k-skill 처리 |
+|---|---|---|
+| K-Startup | https://www.data.go.kr/data/15125364/openapi.do | 공공데이터포털 Open API 응답의 공고 메타데이터와 링크 |
+| 기업마당 | https://www.bizinfo.go.kr/ | 공개 모집 목록의 메타데이터와 공식 상세 링크 |
+| NIPA | https://www.nipa.kr/home/2-2 | 공개 사업공고 목록의 메타데이터와 공식 상세 링크 |
+| KOCCA | https://www.kocca.kr/kocca/pims/list.do | 공개 지원공고 목록의 메타데이터와 공식 상세 링크 |
+| SMTECH | https://www.smtech.go.kr/front/ifg/no/notice02_list.do | 공개 R&D 공고 목록의 메타데이터와 공식 상세 링크 |
+
+## 재배포 판단
+
+- **오픈소스 코드**: MIT 조건에 따라 attribution을 유지하면 재사용·수정·재배포 가능.
+- **K-Startup Open API 데이터**: 데이터셋 상세 페이지의 이용조건을 따라 사용하며 출처를 표시한다.
+- **각 기관의 공고 원문·첨부파일**: 개별 저작권·공공누리·제3자 권리가 다를 수 있으므로 일괄 재배포 가능하다고 간주하지 않는다.
+- **k-skill-proxy 응답**: 제목, 기관, 날짜, 식별자, 공식 링크 같은 사실 메타데이터만 구조화한다. 공고 본문·첨부파일을 저장하거나 미러링하지 않는다.
+
+공고 내용을 인용하거나 첨부파일을 재배포해야 하는 별도 기능은 각 자료에 표시된 공공누리 유형과 이용약관을 건별 확인한 뒤 구현해야 한다.

package/skills/government-support-survey/scripts/run_survey.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Government support survey helper. Proxy-first, stdlib only."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+DEFAULT_PROXY_BASE_URL = "https://k-skill-proxy.nomadamas.org"
+VALID_SOURCES = ("kstartup", "bizinfo", "nipa", "kocca", "smtech")
+
+
+def build_url(args: argparse.Namespace) -> str:
+    base = (args.proxy_base_url or os.environ.get("KSKILL_PROXY_BASE_URL")
+            or DEFAULT_PROXY_BASE_URL).rstrip("/")
+    params = {
+        "sources": ",".join(args.sources),
+        "maxPages": str(args.max_pages),
+        "perPage": str(args.per_page),
+    }
+    if args.keyword:
+        params["keyword"] = args.keyword
+    return f"{base}/v1/government-support/survey?{urllib.parse.urlencode(params)}"
+
+
+def parser() -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(
+        description="K-Startup·기업마당·NIPA·KOCCA·SMTECH 정부지원 공고 전수조사"
+    )
+    result.add_argument("--sources", nargs="+", choices=VALID_SOURCES, default=list(VALID_SOURCES))
+    result.add_argument("--keyword", default="")
+    result.add_argument("--max-pages", type=int, default=1)
+    result.add_argument("--per-page", type=int, default=100)
+    result.add_argument("--proxy-base-url")
+    result.add_argument("--timeout", type=float, default=30)
+    result.add_argument("--compact", action="store_true")
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    if not 1 <= args.max_pages <= 10:
+        parser().error("--max-pages must be between 1 and 10")
+    if not 1 <= args.per_page <= 100:
+        parser().error("--per-page must be between 1 and 100")
+    request = urllib.request.Request(
+        build_url(args),
+        headers={"Accept": "application/json", "User-Agent": "k-skill-government-support-survey/1.0"},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=args.timeout) as response:
+            payload = json.load(response)
+    except urllib.error.HTTPError as error:
+        body = error.read().decode("utf-8", errors="replace")
+        print(body or f"HTTP {error.code}", file=sys.stderr)
+        return 2
+    except (urllib.error.URLError, TimeoutError) as error:
+        print(f"k-skill-proxy request failed: {error}", file=sys.stderr)
+        return 2
+
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=None if args.compact else 2)
+    sys.stdout.write("\n")
+    return 0 if payload.get("complete") else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/government-support-survey/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "government-support-survey",
+  "description": "K-Startup·기업마당·NIPA·KOCCA·SMTECH의 공개 정부지원 공고를 k-skill-proxy로 전수조사하고 프로젝트 적합성을 보수적으로 분류한다. 사용자가 정부지원사업, 창업지원, 사업화·R&D·바우처·입주공간 공고를 한 번에 찾아달라고 할 때 사용한다.",
+  "profiles": [
+    "proxy",
+    "browser",
+    "action:submission"
+  ],
+  "frontmatter": "name: government-support-survey\ndescription: K-Startup·기업마당·NIPA·KOCCA·SMTECH의 공개 정부지원 공고를 k-skill-proxy로 전수조사하고 프로젝트 적합성을 보수적으로 분류한다. 사용자가 정부지원사업, 창업지원, 사업화·R&D·바우처·입주공간 공고를 한 번에 찾아달라고 할 때 사용한다."
+}

package/skills/kamis-food-price/instruction.md

@@ -0,0 +1,66 @@
+# KAMIS 농수축산물 가격 조회
+
+## What this skill does
+
+한국농수산식품유통공사 KAMIS의 `dailyPriceByCategoryList`를
+`k-skill-proxy`의 좁은 read-only route로 호출한다. 농산물·축산물·수산물의
+부류별 도매/소매 가격과 전일, 1주일, 1개월, 1년, 평년 비교값을 반환한다.
+
+이 skill은 쇼핑몰 최저가나 투자 추천이 아니라 공식 유통가격 조회용이다.
+
+## Inputs
+
+- `p_productclscode`: `01` 소매, `02` 도매. 기본 `01`
+- `p_itemcategorycode`: `100` 식량작물, `200` 채소류, `300` 특용작물,
+  `400` 과일류, `500` 축산물, `600` 수산물. 기본 `100`
+- `p_countycode`: 지역 코드(예: `1101` 서울). 생략하면 전체 지역
+- `p_regday`: `YYYY-MM-DD`, 생략하면 최근 조사일
+- `p_convert_kg_yn`: `Y` 또는 `N`. 기본 `N`
+
+사용자가 문서식 별칭인 `p_product_cls_code`, `p_country_code`,
+`p_item_category_code`를 주어도 proxy가 실제 upstream 계약명으로 정규화한다.
+
+## Workflow
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "$BASE/v1/kamis/food-price/daily-category" \
+  --data-urlencode "p_productclscode=01" \
+  --data-urlencode "p_itemcategorycode=200" \
+  --data-urlencode "p_countycode=1101" \
+  --data-urlencode "p_convert_kg_yn=N"
+```
+
+응답의 `items` 각 항목에서 `item_name`, `kind_name`, `rank`, `unit`,
+`dpr1`(조회일), `dpr2`(1일 전), `dpr3`(1주일 전), `dpr5`(1개월 전),
+`dpr6`(1년 전), `dpr7`(평년)을 확인한다. 가격 문자열의 쉼표와 `-`를
+숫자로 바꿀 때는 빈 값 여부를 먼저 보존한다.
+
+## Access path and credentials
+
+일반 사용자는 hosted `k-skill-proxy`를 사용하므로 KAMIS 키가 필요 없다.
+proxy 운영자는 KAMIS에서 발급받은 `KAMIS_API_KEY`를 서버 runtime env에
+보관한다. upstream의 `p_cert_id`는 별도 API key가 아니라 요청자 ID
+파라미터이며, 현재 proxy는 live 계약에서 검증한 `TEST` 값을 사용한다.
+키를 URL, 로그, 저장소, 사용자 응답에 노출하지 않는다.
+
+공식 문서:
+<https://www.kamis.or.kr/customer/reference/openapi_list.do?action=detail&boardno=1>
+
+실제 upstream 경로는 `xml.do`이지만 `p_returntype=json`을 사용한다. 이는
+KAMIS의 공식 계약이며 URL을 `json.do`로 바꾸지 않는다.
+
+## Failure modes
+
+- `400 bad_request`: 잘못된 날짜, 지역 코드, 부류 코드, 도소매 값
+- `503 upstream_not_configured`: proxy runtime에 `KAMIS_API_KEY` 없음
+- `400` 또는 `502 upstream_error`: KAMIS code `200`, `900`, 네트워크/상류 오류
+- `items: []`, upstream code `001`: 해당 조건의 가격 없음
+- KAMIS가 JSON 대신 점검 HTML/XML을 반환하면 `upstream_invalid_response`
+- 가격은 조사 시점의 공식 데이터이며 구매 보장·법률 판단·투자 조언이 아니다
+
+## Done when
+
+- 조회 조건과 `query`가 응답에 남아 있다.
+- 각 가격 항목의 조회일과 비교 기간을 구분했다.
+- 답변에 KAMIS 원문 출처와 조회 조건을 함께 적었다.

package/skills/kamis-food-price/scripts/run_kamis.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Read KAMIS prices through the hosted proxy, with an optional direct mode."""
+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"
+UPSTREAM = "https://www.kamis.or.kr/service/price/xml.do"
+
+
+def secrets(path):
+    values = {}
+    try:
+        with open(path, encoding="utf-8") as stream:
+            for line in stream:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    key, value = line.split("=", 1)
+                    values[key.strip()] = value.strip().strip("\"'")
+    except OSError:
+        pass
+    return values
+
+
+def query(args):
+    if args.product_class not in {"01", "02"}:
+        raise ValueError("--product-class must be 01 or 02")
+    if args.category not in {"100", "200", "300", "400", "500", "600"}:
+        raise ValueError("--category must be 100, 200, 300, 400, 500, or 600")
+    if args.convert_kg not in {"Y", "N"}:
+        raise ValueError("--convert-kg must be Y or N")
+    result = {
+        "p_productclscode": args.product_class,
+        "p_itemcategorycode": args.category,
+        "p_convert_kg_yn": args.convert_kg,
+        "p_returntype": "json",
+    }
+    if args.county:
+        if not args.county.isdigit() or len(args.county) != 4:
+            raise ValueError("--county must be a four-digit KAMIS code")
+        result["p_countycode"] = args.county
+    if args.date:
+        if len(args.date) != 10 or args.date[4] != "-" or args.date[7] != "-":
+            raise ValueError("--date must be YYYY-MM-DD")
+        result["p_regday"] = args.date
+    return result
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="KAMIS 농수축산물 가격 조회")
+    parser.add_argument("--product-class", default="01")
+    parser.add_argument("--category", default="100")
+    parser.add_argument("--county")
+    parser.add_argument("--date")
+    parser.add_argument("--convert-kg", default="N")
+    parser.add_argument("--text", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--direct", action="store_true")
+    parser.add_argument("--proxy-base-url", default=os.getenv("KSKILL_PROXY_BASE_URL", DEFAULT_PROXY))
+    parser.add_argument("--secrets-path", default=os.path.expanduser("~/.config/k-skill/secrets.env"))
+    args = parser.parse_args(argv)
+    key = None
+    try:
+        params = query(args)
+    except ValueError as error:
+        print(f"[error] {error}", file=sys.stderr)
+        return 2
+
+    if args.direct:
+        local = secrets(args.secrets_path)
+        key = os.getenv("KSKILL_KAMIS_API_KEY") or local.get("KSKILL_KAMIS_API_KEY")
+        if not key:
+            print("[error] --direct requires KSKILL_KAMIS_API_KEY", file=sys.stderr)
+            return 3
+        assert key is not None
+        params = {**params, "action": "dailyPriceByCategoryList", "p_cert_key": key, "p_cert_id": "TEST"}
+        url = f"{UPSTREAM}?{urllib.parse.urlencode(params)}"
+    else:
+        url = f"{args.proxy_base_url.rstrip('/')}/v1/kamis/food-price/daily-category?{urllib.parse.urlencode(params)}"
+
+    if args.dry_run:
+        display_params = {**params}
+        if args.direct:
+            display_params["p_cert_key"] = "<redacted>"
+        display_url = url.replace(key, "<redacted>") if args.direct and key is not None else url
+        print(json.dumps({"url": display_url, "query": display_params}, ensure_ascii=False, indent=2))
+        return 0
+
+    try:
+        with urllib.request.urlopen(urllib.request.Request(url, headers={"accept": "application/json"}), timeout=30) as response:
+            payload = json.loads(response.read())
+    except (OSError, ValueError, urllib.error.HTTPError) as error:
+        print(f"[error] KAMIS request failed: {error}", file=sys.stderr)
+        return 4
+
+    if args.text:
+        items = payload.get("items", payload.get("data", {}).get("item", []))
+        for item in items:
+            print(f"{item.get('item_name', '?')} {item.get('kind_name', '')} {item.get('dpr1', '-')}{item.get('unit', '')}")
+    else:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/kamis-food-price/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "kamis-food-price",
+  "description": "KAMIS 농수축산물 유통 Open API를 k-skill-proxy 경유로 호출해 부류별 도소매 가격과 전일·주간·월간·연간 비교값을 조회한다. 조회 전용.",
+  "profiles": [
+    "proxy",
+    "lookup"
+  ],
+  "frontmatter": "name: kamis-food-price\ndescription: KAMIS 농수축산물 유통 Open API를 k-skill-proxy 경유로 호출해 부류별 도소매 가격과 전일·주간·월간·연간 비교값을 조회한다. 조회 전용.\nlicense: MIT\nmetadata:\n  category: food\n  locale: ko-KR\n  phase: v1"
+}

package/skills/korean-cinema-search/instruction.md

@@ -136,6 +136,12 @@ CGV는 시간표 중심으로 본다.
 npx --yes daiso get /api/cgv/timetable --keyword 강남 --playDate <YYYYMMDD> --json
 ```
 
+CGV 공개 endpoint가 `503 CGV_UPSTREAM_UNAVAILABLE`을 반환하면 CGV 공식 웹사이트
+(`https://www.cgv.co.kr`)를 브라우저 사용 스킬로 대체 조회한다. 이때도 공개 상영정보
+조회만 수행하고, 로그인·예매·결제는 진행하지 않는다. 공식 웹사이트에서 비정상 접속
+차단, CAPTCHA, 브라우저 검증 또는 유사한 접근 제한이 표시되면 이를 우회하지 말고
+CGV 조회를 중단한다.
+
 메가박스와 롯데시네마는 잔여석 endpoint를 사용할 수 있다.
 
 ```bash
@@ -165,7 +171,7 @@ npx --yes daiso get /api/lottecinema/seats --keyword 월드타워 --playDate <YY
 
 ## Failure modes
 
-- public endpoint는 upstream 상태에 따라 간헐적인 5xx를 줄 수 있다.
+- CGV 공개 endpoint가 CGV 원본 서비스의 봇 차단·접속 제한을 받으면 `503 CGV_UPSTREAM_UNAVAILABLE`을 반환할 수 있다. 이 응답은 skill 또는 CLI 입력 오류가 아니라 upstream 접근 실패이므로 CGV 공식 웹사이트를 브라우저 사용 스킬로 대체 조회한다. 공식 웹사이트에서도 차단, CAPTCHA, 브라우저 검증 또는 유사한 접근 제한이 표시되면 우회하지 말고 중단한다.
 - 지역 키워드가 넓으면 다른 지점이 섞일 수 있다.
 - 시간표와 잔여석은 시점에 따라 달라진다.
 - 일부 체인은 상영작, 시간표, 잔여석 endpoint의 입력값이 다르므로 theaterId, movieId가 있으면 그 값을 우선 사용한다.

package/skills/mofa-travel-safety/instruction.md

@@ -0,0 +1,62 @@
+# 외교부 해외안전·여행경보 조회
+
+## What this skill does
+
+외교부 `국가·지역별 여행경보 목록 조회(0404 대륙정보)` API를
+`k-skill-proxy`의 좁은 read-only route로 조회한다. 국가명 또는 ISO 2자리
+코드로 공식 여행경보 단계, 지역 유형, 경보 내용, 작성일과 공식 지도 URL을
+확인한다.
+
+이 skill은 자체적인 안전/위험 점수나 여행 허가 판단을 만들지 않는다.
+응답된 외교부 공식 경보와 원문 링크를 사실 그대로 요약한다.
+
+## Inputs
+
+- `country_iso_alp2`: ISO 2자리 국가코드(예: `RU`)
+- `country_nm`: 한글 국가명(예: `러시아`)
+- `page`: 기본 `1`
+- `perPage`: 기본 `10`, 최대 `100`
+
+국가명과 ISO 코드는 동시에 주지 않는다.
+
+## Workflow
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "$BASE/v1/mofa-travel-safety/travel-alerts" \
+  --data-urlencode "country_iso_alp2=RU" \
+  --data-urlencode "perPage=10"
+```
+
+응답 `items`의 `country_nm`, `country_iso_alp2`, `alarm_lvl`,
+`region_ty`, `remark`, `written_dt`, `dang_map_download_url`을 원문 기준으로
+요약한다. `alarm_lvl` 숫자의 의미는 답변에서 임의로 재분류하지 말고
+외교부 원문/0404 설명을 함께 제시한다.
+
+## Access path and credentials
+
+일반 사용자는 hosted `k-skill-proxy`를 사용하므로 data.go.kr 키가 필요
+없다. proxy 운영자는 승인된 `DATA_GO_KR_API_KEY`를 서버 runtime env에
+보관한다. 키는 URL, 로그, 저장소, 사용자 응답에 노출하지 않는다.
+
+공식 API:
+<https://www.data.go.kr/data/15095500/openapi.do>
+
+실제 upstream:
+`https://apis.data.go.kr/1262000/TravelAlarmService0404/getTravelAlarm0404List`
+
+## Fallback and failure modes
+
+- 먼저 proxy route를 사용하고, 실패하면 공식 data.go.kr API 문서와 0404
+  원문 링크만 안내한다. 임의의 안전 판정을 대신하지 않는다.
+- `400 bad_request`: 잘못된 ISO 코드, 국가명, 페이지 값
+- `503 upstream_not_configured`: proxy runtime에 data.go.kr 키 없음
+- `502 upstream_error`: 외교부/data.go.kr 인증·quota·상류 장애
+- `upstream_invalid_response`: JSON 대신 XML/HTML 오류 응답
+- `items: []`: 해당 조건에 맞는 국가/지역 기록 없음
+
+## Done when
+
+- 국가명 또는 ISO 코드와 조회 시각을 답변에 적었다.
+- `alarm_lvl`, `region_ty`, `remark`를 공식 필드명과 함께 제시했다.
+- 원문 API 문서와 0404 공식 링크를 함께 제공했다.

package/skills/mofa-travel-safety/scripts/run_mofa_travel_safety.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Read MOFA 0404 travel alerts through the hosted 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 main(argv=None):
+    parser = argparse.ArgumentParser(description="외교부 국가별 여행경보 조회")
+    parser.add_argument("--country-iso")
+    parser.add_argument("--country-name")
+    parser.add_argument("--page", type=int, default=1)
+    parser.add_argument("--per-page", type=int, default=10)
+    parser.add_argument("--text", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--proxy-base-url", default=os.getenv("KSKILL_PROXY_BASE_URL", DEFAULT_PROXY))
+    args = parser.parse_args(argv)
+    if args.country_iso and args.country_name:
+        print("[error] use either --country-iso or --country-name", file=sys.stderr)
+        return 2
+    if not 1 <= args.page or not 1 <= args.per_page <= 100:
+        print("[error] invalid page or per-page", file=sys.stderr)
+        return 2
+    params = {"page": args.page, "perPage": args.per_page}
+    if args.country_iso:
+        if len(args.country_iso) != 2 or not args.country_iso.isalpha():
+            print("[error] --country-iso must be two letters", file=sys.stderr)
+            return 2
+        params["country_iso_alp2"] = args.country_iso.upper()
+    if args.country_name:
+        params["country_nm"] = args.country_name
+    url = f"{args.proxy_base_url.rstrip('/')}/v1/mofa-travel-safety/travel-alerts?{urllib.parse.urlencode(params)}"
+    if args.dry_run:
+        print(json.dumps({"url": url, "query": params}, ensure_ascii=False, indent=2))
+        return 0
+    try:
+        with urllib.request.urlopen(urllib.request.Request(url, headers={"accept": "application/json"}), timeout=30) as response:
+            payload = json.loads(response.read())
+    except (OSError, ValueError, urllib.error.HTTPError) as error:
+        print(f"[error] MOFA request failed: {error}", file=sys.stderr)
+        return 3
+    if args.text:
+        for item in payload.get("items", []):
+            print(f"{item.get('country_nm')} ({item.get('country_iso_alp2')}): level={item.get('alarm_lvl')} region={item.get('region_ty')}")
+    else:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/mofa-travel-safety/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "mofa-travel-safety",
+  "description": "외교부 0404 국가·지역별 여행경보 Open API를 k-skill-proxy 경유로 조회해 국가별 공식 경보 단계와 원문 정보를 제공한다. 조회 전용.",
+  "profiles": [
+    "proxy",
+    "lookup"
+  ],
+  "frontmatter": "name: mofa-travel-safety\ndescription: 외교부 0404 국가·지역별 여행경보 Open API를 k-skill-proxy 경유로 조회해 국가별 공식 경보 단계와 원문 정보를 제공한다. 조회 전용.\nlicense: MIT\nmetadata:\n  category: travel\n  locale: ko-KR\n  phase: v1"
+}

package/skills/seoul-weather-risk/instruction.md

@@ -51,6 +51,8 @@ npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.p
 
 `--filter`가 필요하거나 게시 계약을 점검해야 할 때는 `--fast`를 빼고 full-contract query를 사용한다. fast query가 `product_not_ready` 또는 계약 오류를 반환하면 fixture나 추정값으로 대체하지 말고 아래 진단 흐름을 수행한다.
 
+`--from`/`--to`에 날짜만 넣으면 그날 `00:00:00`–`23:59:59`로 확장한다. ASK 서울 serving window가 자정부터 열려 있지 않아 `422 query_window_unavailable`이 오면 helper는 요청 구간과 `available_from_at`/`available_to_at`의 교집합으로 한 번만 재시도한다. 교집합이 없으면 그 에러의 available window를 보여주고 중단한다. 없는 시간대를 추정 데이터로 채우지 않는다.
+
 ### Contract diagnostics (only when needed)
 
 1. 환경 설정만 확인한다. 이 명령은 네트워크를 호출하지 않는다.
@@ -99,6 +101,7 @@ npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.p
 - `location_mapping_invalid`: bundled 행정동 reference의 버전·스키마·행 수 계약 오류
 - `proxy_disabled`, `invalid_proxy_base_url`: proxy 환경 설정 오류
 - `unauthorized`/`api_key_missing`(401), `forbidden`/`api_key_forbidden`(403), `unknown_product`(404)
-- `cursor_expired`(409), `rate_limited`(429), `product_not_ready`(503)
+- `cursor_expired`(409), `query_window_unavailable`(422), `rate_limited`(429), `product_not_ready`(503)
+- `query_window_unavailable`: 요청한 `--from`/`--to`가 현재 제공 가능한 예보 window와 겹치지 않음. `details.available_from_at`/`available_to_at`를 확인한다. 겹치는 구간이면 helper가 이미 한 번 재시도한 뒤의 결과다.
 - `upstream_not_configured`(503): proxy 운영 환경에 ASK Seoul 전용 서비스 키 또는 origin이 설정되지 않음
 - `response_contract_invalid`, `malformed_response`: 단일 제품 계약 또는 API 응답 계약 drift

package/skills/seoul-weather-risk/scripts/seoul_weather_risk.py

@@ -33,9 +33,18 @@ STATUS_CODES = {
     403: "forbidden",
     404: "unknown_product",
     409: "cursor_expired",
+    422: "query_window_unavailable",
     429: "rate_limited",
     503: "product_not_ready",
 }
+WINDOW_INSTANT_LENGTH = len("YYYY-MM-DD HH:MM:SS")
+QUERY_WINDOW_DETAIL_FIELDS = (
+    "requested_from_at",
+    "requested_to_at",
+    "available_from_at",
+    "available_to_at",
+    "publication_id",
+)
 
 
 class SkillError(RuntimeError):
@@ -89,13 +98,20 @@ def _error_payload(raw: bytes) -> dict[str, Any]:
 def _problem_error(status: int, raw: bytes, headers: Any) -> SkillError:
     problem = _error_payload(raw)
     code = problem.get("code") if isinstance(problem.get("code"), str) else STATUS_CODES.get(status, "api_error")
-    message = problem.get("detail") if isinstance(problem.get("detail"), str) else problem.get("title")
+    raw_detail = problem.get("detail")
+    message = raw_detail if isinstance(raw_detail, str) else problem.get("title")
     if not isinstance(message, str) or not message:
         message = f"ASK Seoul API가 HTTP {status} 응답을 반환했습니다."
-    details = {"status": status}
+    details: dict[str, Any] = {"status": status}
     for name in ("type", "title", "product_id", "blockers", "request_id"):
         if name in problem:
             details[name] = problem[name]
+    if isinstance(raw_detail, dict):
+        details["detail"] = raw_detail
+        for name in QUERY_WINDOW_DETAIL_FIELDS:
+            value = raw_detail.get(name)
+            if isinstance(value, str) and value:
+                details[name] = value
     retry_after = headers.get("Retry-After") if headers else None
     if retry_after:
         details["retry_after"] = retry_after
@@ -238,6 +254,72 @@ def _time_bound(value: str, edge: str) -> str:
     return value
 
 
+def _window_sort_key(value: str) -> str | None:
+    text = " ".join(value.strip().replace("T", " ", 1).split())
+    if len(text) < WINDOW_INSTANT_LENGTH:
+        return None
+    key = text[:WINDOW_INSTANT_LENGTH]
+    if (
+        key[4] == "-"
+        and key[7] == "-"
+        and key[10] == " "
+        and key[13] == ":"
+        and key[16] == ":"
+        and key[:4].isdigit()
+        and key[5:7].isdigit()
+        and key[8:10].isdigit()
+        and key[11:13].isdigit()
+        and key[14:16].isdigit()
+        and key[17:19].isdigit()
+    ):
+        return key
+    return None
+
+
+def _intersect_query_window(
+    requested_from: str,
+    requested_to: str,
+    available_from: str,
+    available_to: str,
+) -> tuple[str, str] | None:
+    req_from = _window_sort_key(requested_from)
+    req_to = _window_sort_key(requested_to)
+    avail_from = _window_sort_key(available_from)
+    avail_to = _window_sort_key(available_to)
+    if req_from is None or req_to is None or avail_from is None or avail_to is None:
+        return None
+    clipped_from = max(req_from, avail_from)
+    clipped_to = min(req_to, avail_to)
+    if clipped_from > clipped_to:
+        return None
+    return clipped_from, clipped_to
+
+
+def _query_window_bounds(query: dict[str, str], error: SkillError) -> tuple[str, str, str, str] | None:
+    if error.details.get("status") != 422:
+        return None
+    available_from = error.details.get("available_from_at")
+    available_to = error.details.get("available_to_at")
+    requested_from = error.details.get("requested_from_at") or query.get("from")
+    requested_to = error.details.get("requested_to_at") or query.get("to")
+    if not all(isinstance(value, str) and value for value in (requested_from, requested_to, available_from, available_to)):
+        return None
+    return requested_from, requested_to, available_from, available_to
+
+
+def _retry_query_after_unavailable_window(query: dict[str, str], error: SkillError) -> dict[str, str] | None:
+    bounds = _query_window_bounds(query, error)
+    if bounds is None or query.get("cursor"):
+        return None
+    clipped = _intersect_query_window(*bounds)
+    if clipped is None:
+        return None
+    clipped_from, clipped_to = clipped
+    if query.get("from") == clipped_from and query.get("to") == clipped_to:
+        return None
+    return {**query, "from": clipped_from, "to": clipped_to}
+
+
 def _normalize_location_name(value: str) -> str:
     return " ".join(unicodedata.normalize("NFC", value).strip().split())
 
@@ -358,7 +440,21 @@ def _detail(config: ApiConfig, product_id: str) -> dict[str, Any]:
 
 def _data(config: ApiConfig, product_id: str, query: dict[str, str], limit: int) -> dict[str, Any]:
     _validate_product_id(product_id)
-    return _validate_data(_request_json(config, f"{PROXY_ROUTE_ROOT}/data", query), product_id, limit)
+    try:
+        payload = _request_json(config, f"{PROXY_ROUTE_ROOT}/data", query)
+    except SkillError as exc:
+        retry_query = _retry_query_after_unavailable_window(query, exc)
+        if retry_query is None:
+            bounds = _query_window_bounds(query, exc)
+            if bounds is not None and _intersect_query_window(*bounds) is None:
+                raise SkillError(
+                    "query_window_unavailable",
+                    "요청한 조회 구간이 현재 제공 가능한 예보 window와 겹치지 않습니다.",
+                    exc.details,
+                ) from exc
+            raise
+        payload = _request_json(config, f"{PROXY_ROUTE_ROOT}/data", retry_query)
+    return _validate_data(payload, product_id, limit)
 
 
 def _parser() -> argparse.ArgumentParser:

package/templates/browser.md

@@ -1,4 +1,4 @@
 <!-- mode:dolshoi -->
 - Use the built-in browser tool backed by CloakBrowser first. Fall back to `k-skill-browser-runtime` providers only when CloakBrowser is unavailable.
 <!-- mode:generic -->
-- Use `k-skill-browser-runtime` (provider `auto`: BrowserOS CDP, then Aside CLI, then user-launched Chrome CDP) for logged-in or rendered-page automation. Do not launch or close the user's browser, and never solve CAPTCHA, identity proofing, or e-signature flows.
+- Use `k-skill-browser-runtime` (provider `auto`) for logged-in or rendered-page automation. On macOS it tries Aside Browser first, then BrowserOS CDP, then user-launched Chrome/Chromium CDP; on other platforms it tries BrowserOS CDP, then Aside Browser, then user-launched Chrome/Chromium CDP. Do not launch or close the user's browser, and never solve CAPTCHA, identity proofing, or e-signature flows.