@nomadamas/k-skill 0.1.0

package/skills/delivery-tracking/instruction.md

@@ -0,0 +1,358 @@
+# Delivery Tracking
+
+## What this skill does
+
+CJ대한통운과 우체국 공식 조회 표면을 사용해 송장 번호로 현재 배송 상태를 조회한다.
+
+- **CJ대한통운**: 공식 배송조회 페이지가 노출하는 JSON endpoint 사용
+- **우체국**: 공식 배송조회 페이지가 사용하는 HTML endpoint 사용
+- 결과는 공통 포맷(택배사 / 송장번호 / 현재 상태 / 최근 이벤트들)으로 짧게 정리
+
+## When to use
+
+- "CJ대한통운 송장 조회해줘"
+- "우체국 택배 지금 어디야"
+- "이 송장번호 배송완료인지 확인해줘"
+- "택배사별 조회 로직을 나중에 더 붙일 수 있게 정리해줘"
+
+## When not to use
+
+- 주문번호만 있고 송장번호가 없는 경우
+- 택배 예약/반품 접수까지 바로 해야 하는 경우
+- 비공식 통합 배송조회 서비스로 우회하고 싶은 경우
+
+## Prerequisites
+
+- 인터넷 연결
+- `python3`
+- `curl`
+- 선택 사항: `jq`
+
+## Inputs
+
+- 택배사 식별자: `cj` 또는 `epost`
+- 송장번호
+  - CJ대한통운: 숫자 10자리 또는 12자리
+  - 우체국: 숫자 13자리
+
+## Carrier adapter rule
+
+이 스킬은 택배사별 로직을 **carrier adapter** 단위로 나눈다.
+
+새 택배사를 붙일 때는 아래 필드를 먼저 정한다.
+
+- `carrier id`: 예) `cj`, `epost`
+- `validator`: 송장번호 자리수/패턴
+- `entrypoint`: 공식 조회 진입 URL
+- `transport`: JSON API / HTML form / CLI 중 무엇을 쓰는지
+- `parser`: 어떤 필드나 테이블에서 상태를 뽑는지
+- `status map`: 각 택배사의 원본 상태 코드를 공통 상태로 어떻게 줄일지
+- `retry policy`: timeout/retry 규칙
+
+현재 어댑터는 아래 둘이다.
+
+| carrier adapter | official entry | transport | validator | parser focus |
+| --- | --- | --- | --- | --- |
+| `cj` | `https://www.cjlogistics.com/ko/tool/parcel/tracking` | page GET + `tracking-detail` POST JSON | 10자리 또는 12자리 숫자 | `parcelDetailResultMap.resultList` |
+| `epost` | `https://service.epost.go.kr/trace.RetrieveRegiPrclDeliv.postal?sid1=` | form POST HTML | 13자리 숫자 | 기본정보 `table_col` + 상세 `processTable` |
+
+## Workflow
+
+### 0. Normalize the input first
+
+- 택배사 이름을 `cj` / `epost` 둘 중 하나로 정규화한다.
+- 송장번호에서 공백과 `-` 를 제거한다.
+- 자리수 검증이 먼저 실패하면 조회를 보내지 않는다.
+
+### 1. CJ대한통운: official JSON flow
+
+공식 진입 페이지에서 `_csrf` 를 읽고, 그 값을 `tracking-detail` POST에 같이 보낸다.
+
+- 진입 페이지: `https://www.cjlogistics.com/ko/tool/parcel/tracking`
+- 상세 endpoint: `https://www.cjlogistics.com/ko/tool/parcel/tracking-detail`
+- 필수 필드: `_csrf`, `paramInvcNo`
+
+기본 예시는 `curl` 로 `_csrf` 와 cookie를 유지하고, Python은 JSON 정리에만 쓴다.
+
+```bash
+tmp_body="$(mktemp)"
+tmp_cookie="$(mktemp)"
+tmp_json="$(mktemp)"
+invoice="1234567890"  # 공식 페이지 placeholder 성격의 smoke-test 값
+
+curl -sS -L -c "$tmp_cookie" \
+  "https://www.cjlogistics.com/ko/tool/parcel/tracking" \
+  -o "$tmp_body"
+
+csrf="$(python3 - <<'PY' "$tmp_body"
+import re
+import sys
+
+text = open(sys.argv[1], encoding="utf-8", errors="ignore").read()
+print(re.search(r'name="_csrf" value="([^"]+)"', text).group(1))
+PY
+)"
+
+curl -sS -L -b "$tmp_cookie" \
+  -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
+  --data-urlencode "_csrf=$csrf" \
+  --data-urlencode "paramInvcNo=$invoice" \
+  "https://www.cjlogistics.com/ko/tool/parcel/tracking-detail" \
+  -o "$tmp_json"
+
+python3 - <<'PY' "$tmp_json"
+import json
+import sys
+
+payload = json.load(open(sys.argv[1], encoding="utf-8"))
+events = payload["parcelDetailResultMap"]["resultList"]
+if not events:
+    raise SystemExit("조회 결과가 없습니다.")
+
+status_map = {
+    "11": "상품인수",
+    "21": "상품이동중",
+    "41": "상품이동중",
+    "42": "배송지도착",
+    "44": "상품이동중",
+    "82": "배송출발",
+    "91": "배달완료",
+}
+
+latest = events[-1]
+normalized_events = [
+    {
+        "timestamp": event.get("dTime"),
+        "location": event.get("regBranNm"),
+        "status_code": event.get("crgSt"),
+        "status": status_map.get(event.get("crgSt"), event.get("scanNm") or "알수없음"),
+    }
+    for event in events
+]
+print(json.dumps({
+    "carrier": "cj",
+    "invoice": payload["parcelDetailResultMap"]["paramInvcNo"],
+    "status_code": latest.get("crgSt"),
+    "status": status_map.get(latest.get("crgSt"), latest.get("scanNm") or "알수없음"),
+    "timestamp": latest.get("dTime"),
+    "location": latest.get("regBranNm"),
+    "event_count": len(events),
+    "recent_events": normalized_events[-min(3, len(normalized_events)):],
+}, ensure_ascii=False, indent=2))
+PY
+
+rm -f "$tmp_body" "$tmp_cookie" "$tmp_json"
+```
+
+#### CJ 공개 출력 예시
+
+아래 값은 2026-03-27 기준 live smoke test(`1234567890`)에서 확인한 정규화 결과다.
+
+```json
+{
+  "carrier": "cj",
+  "invoice": "1234567890",
+  "status_code": "91",
+  "status": "배달완료",
+  "timestamp": "2026-03-21 12:22:13",
+  "location": "경기광주오포",
+  "event_count": 3,
+  "recent_events": [
+    {
+      "timestamp": "2026-03-10 03:01:45",
+      "location": "청원HUB",
+      "status_code": "44",
+      "status": "상품이동중"
+    },
+    {
+      "timestamp": "2026-03-21 10:53:19",
+      "location": "경기광주오포",
+      "status_code": "82",
+      "status": "배송출발"
+    },
+    {
+      "timestamp": "2026-03-21 12:22:13",
+      "location": "경기광주오포",
+      "status_code": "91",
+      "status": "배달완료"
+    }
+  ]
+}
+```
+
+추가 smoke test 로는 `000000000000` 도 사용할 수 있다.
+
+CJ 응답은 `parcelResultMap.resultList` 가 비어 있어도 `parcelDetailResultMap.resultList` 쪽에 이벤트가 들어올 수 있으므로, 상세 이벤트 배열을 우선 본다. published 예시는 공통 결과 스키마(`carrier`, `invoice`, `status`, `timestamp`, `location`, `event_count`, `recent_events`, 선택적 `status_code`)에 맞춰 비식별 필드만 남기고, 담당자 이름·연락처가 섞일 수 있는 `crgNm` 원문은 그대로 보여주지 않는다.
+
+### 2. 우체국: official HTML flow
+
+우체국은 공식 entry page가 다시 `trace.RetrieveDomRigiTraceList.comm` 으로 `sid1` 을 POST하는 구조다.
+
+- 진입 페이지: `https://service.epost.go.kr/trace.RetrieveRegiPrclDeliv.postal?sid1=`
+- 실제 조회 endpoint: `https://service.epost.go.kr/trace.RetrieveDomRigiTraceList.comm`
+- 필수 필드: `sid1`
+
+우체국은 로컬 Python HTTP client보다 `curl --http1.1 --tls-max 1.2` 경로가 더 안정적이므로 그 조합을 기본 예시로 쓴다.
+
+```bash
+tmp_html="$(mktemp)"
+python3 - <<'PY' "$tmp_html"
+import html
+import json
+import re
+import subprocess
+import sys
+
+invoice = "1234567890123"  # 공식 페이지 placeholder 성격의 smoke-test 값
+output_path = sys.argv[1]
+
+cmd = [
+    "curl",
+    "--http1.1",
+    "--tls-max",
+    "1.2",
+    "--silent",
+    "--show-error",
+    "--location",
+    "--retry",
+    "3",
+    "--retry-all-errors",
+    "--retry-delay",
+    "1",
+    "--max-time",
+    "30",
+    "-o",
+    output_path,
+    "-d",
+    f"sid1={invoice}",
+    "https://service.epost.go.kr/trace.RetrieveDomRigiTraceList.comm",
+]
+subprocess.run(cmd, check=True)
+
+page = open(output_path, encoding="utf-8", errors="ignore").read()
+
+summary = re.search(
+    r"<th scope=\"row\">(?P<tracking>[^<]+)</th>.*?"
+    r"<td>(?P<sender>.*?)</td>.*?"
+    r"<td>(?P<receiver>.*?)</td>.*?"
+    r"<td>(?P<delivered_to>.*?)</td>.*?"
+    r"<td>(?P<kind>.*?)</td>.*?"
+    r"<td>(?P<result>.*?)</td>",
+    page,
+    re.S,
+)
+if not summary:
+    raise SystemExit("기본정보 테이블을 찾지 못했습니다.")
+
+def clean(raw: str) -> str:
+    text = re.sub(r"<[^>]+>", " ", raw)
+    return " ".join(html.unescape(text).split())
+
+def clean_location(raw: str) -> str:
+    text = clean(raw)
+    return re.sub(r"\s*(TEL\s*:?\s*)?\d{2,4}[.\-]\d{3,4}[.\-]\d{4}", "", text).strip()
+
+events = re.findall(
+    r"<tr>\s*<td>(\d{4}\.\d{2}\.\d{2})</td>\s*"
+    r"<td>(\d{2}:\d{2})</td>\s*"
+    r"<td>(.*?)</td>\s*"
+    r"<td>\s*<span class=\"evtnm\">(.*?)</span>(.*?)</td>\s*</tr>",
+    page,
+    re.S,
+)
+
+normalized_events = [
+    {
+        "timestamp": f"{day} {time_}",
+        "location": clean_location(location),
+        "status": clean(status),
+    }
+    for day, time_, location, status, _detail in events
+]
+
+latest_event = normalized_events[-1] if normalized_events else None
+
+print(json.dumps({
+    "carrier": "epost",
+    "invoice": clean(summary.group("tracking")),
+    "status": clean(summary.group("result")),
+    "timestamp": latest_event["timestamp"] if latest_event else None,
+    "location": latest_event["location"] if latest_event else None,
+    "event_count": len(normalized_events),
+    "recent_events": normalized_events[-min(3, len(normalized_events)):],
+}, ensure_ascii=False, indent=2))
+PY
+rm -f "$tmp_html"
+```
+
+#### 우체국 공개 출력 예시
+
+아래 값은 2026-03-27 기준 live smoke test(`1234567890123`)에서 확인한 정규화 결과다.
+
+```json
+{
+  "carrier": "epost",
+  "invoice": "1234567890123",
+  "status": "배달완료",
+  "timestamp": "2025.12.04 15:13",
+  "location": "제주우편집중국",
+  "event_count": 2,
+  "recent_events": [
+    {
+      "timestamp": "2025.12.04 15:13",
+      "location": "제주우편집중국",
+      "status": "배달준비"
+    },
+    {
+      "timestamp": "2025.12.04 15:13",
+      "location": "제주우편집중국",
+      "status": "배달완료"
+    }
+  ]
+}
+```
+
+우체국 기본정보 테이블은 `등기번호`, `보내는 분/접수일자`, `받는 분`, `수령인/배달일자`, `취급구분`, `배달결과` 순서를 사용하고, 상세 이벤트는 `processTable` 아래 `날짜 / 시간 / 발생국 / 처리현황` 행을 읽으면 된다. published 예시는 CJ와 같은 공통 결과 스키마(`carrier`, `invoice`, `status`, `timestamp`, `location`, `event_count`, `recent_events`)에 맞춰 배송 상태에 필요한 값만 남기고, 이벤트 location에 섞일 수 있는 `TEL` 번호 조각도 제거한 뒤 수령인/상세 메모 원문은 그대로 노출하지 않는다.
+
+### 3. Normalize for humans
+
+응답 원문을 그대로 붙이지 말고 아래 공통 결과 스키마로 요약한다.
+
+#### 공통 결과 스키마
+
+- `carrier`: 택배사 식별자 (`cj` 또는 `epost`)
+- `invoice`: 정규화된 송장번호
+- `status`: 현재 배송 상태
+- `timestamp`: 마지막 이벤트 시각
+- `location`: 마지막 이벤트 위치
+- `event_count`: 전체 이벤트 수
+- `recent_events`: 최근 최대 3개 이벤트 목록
+- `status_code`: 필요할 때만 남기는 원본 상태 코드 (현재는 CJ 예시에서만 사용)
+
+### 4. Retry and fallback policy
+
+- 자리수 오류면 바로 멈추고 올바른 형식을 다시 받는다.
+- CJ는 `_csrf` 재취득 후 한 번 더 시도한다.
+- 우체국은 `curl --retry 3 --retry-all-errors --retry-delay 1` 을 유지한다.
+- 다른 택배사로 우회하지 않는다.
+
+## Done when
+
+- 택배사와 송장번호가 올바르게 식별되어 있다
+- 현재 상태와 최근 이벤트가 정리되어 있다
+- 어느 official surface를 썼는지 설명할 수 있다
+- 다른 택배사 확장 시 어떤 carrier adapter 필드를 추가해야 하는지 남아 있다
+
+## Failure modes
+
+- CJ: `_csrf` 추출 실패 또는 `tracking-detail` 응답 스키마 변경
+- CJ: 송장번호 길이가 10자리 또는 12자리가 아님
+- 우체국: `sid1` 이 13자리가 아님
+- 우체국: HTML 마크업 변경으로 테이블 추출 규칙이 깨짐
+- 우체국: `curl` 없이 다른 client로 붙다가 timeout/reset 발생
+
+## Notes
+
+- 조회형 스킬이다.
+- 기본 표면은 공식 carrier endpoint만 사용한다.
+- 다른 택배사 추가는 새 carrier adapter 1개를 같은 포맷으로 붙이는 방식으로 확장한다.

package/skills/delivery-tracking/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "delivery-tracking",
+  "description": "Track CJ대한통운 and 우체국 parcels by invoice number with official carrier endpoints, and structure the workflow around a carrier adapter that can grow to more couriers later.",
+  "profiles": [
+    "lookup"
+  ],
+  "frontmatter": "name: delivery-tracking\ndescription: Track CJ대한통운 and 우체국 parcels by invoice number with official carrier endpoints, and structure the workflow around a carrier adapter that can grow to more couriers later.\nlicense: MIT\nmetadata:\n  category: logistics\n  locale: ko-KR\n  phase: v1"
+}

package/skills/donation-place-search/instruction.md

@@ -0,0 +1,129 @@
+# 기부처 조회 / Donation Place Search
+
+## What this skill does
+
+사용자가 “어디에 기부하면 좋을지”, “서울 아동 기부처”, “동물보호 기부처 추천”처럼 묻는 경우 **장소와 카테고리 기준으로 기부처 후보를 추천**한다.
+
+- 기부를 대신 실행하지 않는다.
+- 결제, 개인정보 입력, 자동 후원 신청은 하지 않는다.
+- 추천은 의사결정 보조이며, 최종 기부 전 공식 페이지와 1365 기부포털에서 최신 등록·모금기간·기부금영수증 가능 여부를 확인한다.
+- 위치는 사용자가 제공한 행정구역/동네/랜드마크 텍스트만 사용한다. 자동 위치 추적을 하지 않는다.
+
+## When to use
+
+- “기부처 조회해줘”
+- “서울 마포구에서 동물보호 기부할 만한 곳 추천해줘”
+- “부산 노인 복지 기부처 알려줘”
+- “아동/재난 분야 기부처 비교해줘”
+- “어디에 기부하는 곳이 좋을지 장소와 카테고리별로 추천해줘”
+
+## Inputs
+
+- `location`: 선택. 예: `서울 마포구`, `부산 해운대구`, `제주`, `온라인`
+- `category`: 선택. 예: `아동`, `동물보호`, `환경`, `재난 구호`, `장애`, `노인`, `생계`, `의료`, `해외구호`
+- `limit`: 선택. 기본 5개
+
+위치나 카테고리가 없으면 보수적으로 `전국`·`일반/종합` 후보와 1365 공식 확인 보조 링크를 제공한다. 비대화형 자동화에서는 임의로 좁히지 말고 “입력 없음”을 명시한다.
+
+## Public access path discovered
+
+### Primary official verification surface
+
+- Legacy `https://www.nanumkorea.go.kr/` currently returns a notice that 1365 기부포털 has moved/integrated into 1365 자원봉사.
+- The notice links to `https://www.1365.go.kr/dntn/main.do`.
+- The skill therefore uses `https://www.1365.go.kr/dntn/main.do` as the official public verification entry point.
+
+### Search-link strategy
+
+1365 pages can be slow or unavailable to headless HTTP clients, so the package does not depend on brittle screen scraping. It builds a best-effort official-entry/search-assist link with the user’s location/category keywords, then ranks a curated fallback list locally. The package does not assert that 1365 has already verified each returned candidate:
+
+```js
+const { recommendDonationPlaces } = require("donation-place-search");
+
+const result = recommendDonationPlaces({
+  location: "서울 마포구",
+  category: "동물",
+  limit: 3
+});
+
+console.log(result.items);
+console.log(result.officialSearchUrl);
+```
+
+The returned `officialSearchUrl` is a best-effort verification assist: open it as an official 1365 entry point, then confirm current registration and campaign status before giving the final answer.
+
+## Workflow
+
+1. Extract `location`, `category`, and optional `limit` from the user request.
+2. Run the helper:
+
+```bash
+node - <<'NODE'
+const {
+  recommendDonationPlaces,
+  formatDonationRecommendationReport
+} = require("donation-place-search");
+
+const result = recommendDonationPlaces({
+  location: "서울 마포구",
+  category: "동물",
+  limit: 3
+});
+
+console.log(formatDonationRecommendationReport(result));
+NODE
+```
+
+3. Open or cite the returned best-effort 1365 verification-assist URL for latest verification when fresh browsing is available.
+4. Summarize 3–5 candidates, including:
+   - 기부처명
+   - 분야/카테고리
+   - 지역 일치 여부 또는 전국 단위 여부
+   - 왜 맞는지 한 줄
+   - 공식 홈페이지
+   - 1365 확인 보조 링크
+5. Add a caution that campaign status, donation receipt eligibility, and designated-use options must be checked on official pages before donating.
+
+## Output fields
+
+The npm helper returns:
+
+```json
+{
+  "location": { "raw": "서울 마포구", "province": "서울", "district": "마포구" },
+  "category": "animals",
+  "items": [
+    {
+      "name": "동물권행동 카라",
+      "categories": ["animals"],
+      "coverage": "local",
+      "homepageUrl": "https://www.ekara.org/",
+      "officialSearchUrl": "https://www.1365.go.kr/dntn/main.do?...",
+      "match": { "category": true, "local": true, "nationwide": false }
+    }
+  ],
+  "officialSearchUrl": "https://www.1365.go.kr/dntn/main.do?...",
+  "meta": { "source": "curated-fallback-plus-1365-search-assist" }
+}
+```
+
+## Done when
+
+- 장소/카테고리 조건을 반영해 후보를 3–5개 이내로 정리했다.
+- 각 후보마다 공식 홈페이지 또는 1365 확인 보조 링크를 제공했다.
+- 최종 기부 전 등록 상태, 모금 기간, 기부금영수증 가능 여부를 확인하라고 안내했다.
+- 자동 결제/후원 신청을 시도하지 않았다.
+
+## Failure modes
+
+- 1365 사이트가 느리거나 headless HTTP에서 timeout/empty page를 반환할 수 있다. 이 경우 확인 보조 URL과 후보 홈페이지를 제공하고 “최신 상태는 직접 확인 필요”라고 명시한다.
+- 위치 문자열이 행정구역으로 파싱되지 않으면 전국 후보 위주로 제안한다.
+- 지역·카테고리 모두 정확히 맞는 후보가 없으면 전국 단위 후보를 fallback으로 보여준다.
+- 특정 단체의 모금 캠페인, 지정기부 가능 여부, 기부금영수증 처리는 수시로 바뀌므로 package 내 curated 설명만으로 확정하지 않는다.
+- 로그인, 결제, CAPTCHA, 후원 신청서 제출은 자동화하지 않는다.
+
+## Notes
+
+- 이 스킬은 read-only 추천/조회 스킬이다.
+- 기부는 금전 의사결정이므로 최신 공식 근거를 우선한다.
+- 공개 표면만 사용하므로 `k-skill-proxy`와 API key가 필요 없다.

package/skills/donation-place-search/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "donation-place-search",
+  "description": "Use when the user asks where to donate, 기부처 조회, or donation place recommendations by Korean location and category. Recommend recipients with best-effort 1365 verification-assist links and never execute donations. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "proxy",
+    "action:submission"
+  ],
+  "frontmatter": "name: donation-place-search\ndescription: Use when the user asks where to donate, 기부처 조회, or donation place recommendations by Korean location and category. Recommend recipients with best-effort 1365 verification-assist links and never execute donations. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: utility\n  locale: ko-KR\n  phase: v1"
+}

package/skills/emergency-room-beds/instruction.md

@@ -0,0 +1,82 @@
+# Emergency Room Beds
+
+## What this skill does
+
+사용자가 알려준 현재 위치를 기준으로 **근처 응급실**과 공개 E-Gen 응급실 상태 플래그를 찾는다.
+
+- 위치는 자동 추정하지 않는다.
+- 위치가 없으면 먼저 현재 위치를 묻는다.
+- 위치 문자열은 Kakao Map anchor 검색으로 좌표를 잡는다.
+- 응급실 목록은 E-Gen 공개 응급실 찾기 표면을 사용한다.
+- 응급실 운영 여부, 입원실/병상 운영 플래그, 권역외상센터/소아전문 여부, 데이터 갱신시각을 보여준다.
+- **정확한 실시간 잔여 병상 수나 병상 가동률을 확정해서 말하지 않는다.** 공개 E-Gen nearby 목록은 병상 수치가 아니라 운영 플래그를 제공한다.
+
+## When to use
+
+- "근처 응급실 찾아줘"
+- "응급실 병상 상태 확인해줘"
+- "광화문 주변 응급실 어디가 가까워?"
+- "현재 위치 근처 응급실 운영 여부 알려줘"
+
+## Mandatory first question
+
+위치 정보가 없으면 먼저 물어본다.
+
+`현재 위치를 알려주세요. 동네/역명/랜드마크/위도·경도 중 편한 형식으로 보내주시면 근처 응급실 상태를 찾아볼게요.`
+
+## Official/public surfaces
+
+- NEMC 모니터링: `https://dw.nemc.or.kr/nemcMonitoring/mainmgr/Main.do`
+- E-Gen 응급실 찾기: `https://www.e-gen.or.kr/egen/search_emergency_room.do`
+- E-Gen nearby list endpoint: `https://www.e-gen.or.kr/egen/retrieve_emergency_room_list.do`
+- Kakao Map 모바일 검색: `https://m.map.kakao.com/actions/searchView?q=<query>`
+- Kakao Map 장소 패널 JSON: `https://place-api.map.kakao.com/places/panel3/<confirmId>`
+
+## Workflow
+
+1. 사용자의 현재 위치를 확보한다.
+2. `emergency-room-beds` 패키지의 `searchNearbyEmergencyRoomsByLocationQuery()`를 사용한다.
+3. 보통 3~5개 이내로 거리순 결과를 정리한다.
+4. 반드시 "공개 E-Gen nearby 목록 기준이며 정확한 잔여 병상 수/가동률은 제공되지 않는다"고 밝힌다.
+5. 긴급 상황이면 119 또는 병원 전화 확인을 권한다.
+
+## Responding
+
+결과는 짧고 실용적으로 정리한다.
+
+- 병원명 / 거리
+- 응급의료기관 등급 / 병원 유형
+- 응급실 운영 여부
+- 입원실/병상 운영 플래그
+- 권역외상센터/소아전문 여부
+- 주소 / 대표전화
+- 갱신시각
+- 지도 링크
+
+## Node.js example
+
+```js
+const { searchNearbyEmergencyRoomsByLocationQuery } = require("emergency-room-beds");
+
+async function main() {
+  const result = await searchNearbyEmergencyRoomsByLocationQuery("광화문", {
+    limit: 3,
+    radius: 5
+  });
+
+  console.log(result.anchor);
+  console.log(result.items);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+```
+
+## Done when
+
+- 위치 기준 anchor를 확인했다.
+- 가까운 응급실을 찾았거나, 못 찾은 이유와 다음 검색 범위를 제시했다.
+- 공개 데이터의 한계(정확한 잔여 병상 수/가동률 미제공)를 명확히 밝혔다.
+- 긴급 상황에서는 119/전화 확인 안내를 포함했다.

package/skills/emergency-room-beds/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "emergency-room-beds",
+  "description": "Use when the user asks for nearby Korean emergency rooms, 응급실, ER, or emergency bed/병상 status near a location. Ask for the user's current location first unless a location was already provided.",
+  "profiles": [
+    "lookup"
+  ],
+  "frontmatter": "name: emergency-room-beds\ndescription: Use when the user asks for nearby Korean emergency rooms, 응급실, ER, or emergency bed/병상 status near a location. Ask for the user's current location first unless a location was already provided.\nlicense: MIT\nmetadata:\n  category: health\n  locale: ko-KR\n  phase: v1"
+}

package/skills/ev-charger-nearby/instruction.md

@@ -0,0 +1,80 @@
+# EV Charger Nearby
+
+## What this skill does
+
+환경부 전기차 충전소 API의 충전소 정보와 충전기 상태를 조회한다. 조회 전용이며 예약, 결제, 회원 인증, 충전 시작/중지는 자동화하지 않는다.
+
+기본 호출은 hosted `k-skill-proxy`를 사용하므로 사용자는 API 키가 필요 없다. `--direct`를 명시한 경우에만 사용자의 `KSKILL_EV_CHARGER_API_KEY`, 이후 `DATA_GO_KR_API_KEY`를 찾는다.
+
+## Official access path
+
+1. 실시간 충전소 정보: 공공데이터포털 데이터셋 `15076352`, `getChargerInfo`
+2. 실시간 충전기 상태: 같은 데이터셋의 `getChargerStatus`
+3. 정적/수동 fallback: 전국전기차충전소표준데이터 데이터셋 `15013115`의 포털 제공 파일
+
+`15013115`는 실시간 상태 API가 아니다. 포털 다운로드 화면에서 사용자가 직접 받은 표준 CSV를 정적 참고자료로만 사용하며, 문서화되지 않은 CSV URL을 추측하지 않는다.
+
+## Inputs and commands
+
+설치된 skill 디렉터리에서 실행한다.
+
+```bash
+python3 scripts/ev_charger.py info --location '서울 강남구' --num-of-rows 10
+python3 scripts/ev_charger.py status --stat-id ME000001 --num-of-rows 10
+python3 scripts/ev_charger.py status --zcode 11 --limit-yn Y --period 10 --json
+```
+
+공통 필터는 `zcode`, `zscode`, `statId`, `chgerId`다. hosted proxy의 `info`는 고유하게 식별되는 `location`을 행정구역 코드로 변환하며, 모호하거나 찾을 수 없는 위치와 충돌하는 명시적 코드는 거부한다. `status`는 `limitYn`과 `period`를 추가로 허용한다. 페이지 기본값은 `pageNo=1`, `numOfRows=10`이며 `numOfRows` 범위는 10~9999다.
+
+직접 호출:
+
+```bash
+python3 scripts/ev_charger.py info --zcode 11 --zscode 11680 --direct
+python3 scripts/ev_charger.py status --stat-id ME000001 --direct --dry-run
+```
+
+직접 호출은 위치 텍스트를 행정구역 코드로 변환하지 않으므로 `--location` 대신 `--zcode`/`--zscode`를 사용한다. `--dry-run`은 URL을 보여주되 키를 `REDACTED`로 가린다.
+
+## Credential rules
+
+- hosted proxy: 사용자 키 불필요
+- direct 환경변수 우선순위: `KSKILL_EV_CHARGER_API_KEY` -> `DATA_GO_KR_API_KEY`
+- dotenv fallback: `~/.config/k-skill/secrets.env`에서 같은 순서
+- 키를 로그, 답변, dry-run URL, 저장소 파일에 노출하지 않는다
+
+공공데이터포털 인증키를 이미 갖고 있어도 데이터셋 `15076352` 상세 페이지에서 **별도 활용신청**이 필요하다. 이 API는 자동승인 대상이지만 승인/활성화가 완료된 뒤 호출해야 한다.
+
+## Workflow and fallback order
+
+1. 위치/지역 요청은 `info`로 충전소 주소, 운영기관, 충전기 유형과 식별자를 찾는다.
+2. 찾은 `statId`/`chgerId`로 `status`를 호출해 현재 상태와 갱신시각을 확인한다.
+3. live info가 실패하면 동일 조건을 좁혀 한 번 재시도한다.
+4. live info는 성공했지만 status가 실패하면 정보 결과를 제공하면서 상태 확인 실패를 분리해 알린다.
+5. live API 전체가 불가능할 때만 데이터셋 `15013115`의 사용자가 직접 내려받은 표준 CSV를 정적/수동 fallback으로 안내한다.
+
+## Output
+
+기본은 한국어 요약, `--json`은 프록시/상류 JSON을 출력한다. 가능한 경우 다음 필드를 포함한다.
+
+- 충전소명, 주소, 위치 설명
+- 운영기관
+- `statId`, `chgerId`
+- 충전기 유형과 현재 상태
+- 상태 갱신시각
+
+상태 코드는 원문 값을 보존한다. 상태가 없거나 오래된 경우 추정하지 않는다.
+
+## Failure modes
+
+- `upstream_not_configured`: hosted/self-host 프록시에 `DATA_GO_KR_API_KEY`가 없음
+- key/auth rejection: 데이터셋 `15076352` 활용신청 승인 여부 확인
+- proxy down: 프록시 장애 메시지를 보여주고 잠시 후 재시도
+- empty result: 조건을 좁히거나 `zcode`/`zscode`/`statId`를 확인
+- invalid/non-JSON/XML response: upstream 응답 오류로 분리하고 결과로 캐시하지 않음
+- static CSV fallback: 실시간 상태로 표현하지 않고 파일 기준일을 함께 명시
+
+## Done when
+
+- 충전소 정보와 가능한 현재 상태를 각각 확인했다.
+- 정보 조회와 상태 조회의 시점/실패를 구분했다.
+- 키, 예약, 결제, 충전 제어를 노출하거나 자동화하지 않았다.