@nomadamas/k-skill 0.1.0

package/skills/seoul-subway-arrival/instruction.md

@@ -0,0 +1,85 @@
+# Seoul Subway Arrival
+
+## What this skill does
+
+서울 열린데이터 광장의 실시간 지하철 도착정보 Open API를 `k-skill-proxy` 경유로 조회해 역 기준 도착 예정 열차 정보를 요약한다.
+
+## When to use
+
+- "강남역 지금 몇 분 뒤 도착해?"
+- "서울역 1호선 도착 정보 보여줘"
+- "잠실역 곧 들어오는 열차 정리해줘"
+
+## Prerequisites
+
+- optional: `jq`
+- optional: `KSKILL_PROXY_BASE_URL` (self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted `https://k-skill-proxy.nomadamas.org` 를 사용한다.)
+
+## Required environment variables
+
+- 없음. `KSKILL_PROXY_BASE_URL` 은 선택 사항이며, 비우면 기본 hosted `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+
+사용자가 개인 서울 열린데이터 광장 OpenAPI key를 직접 발급할 필요는 없다. `/v1/seoul-subway/arrival` route는 기본 hosted proxy에서 호출하고, upstream key는 proxy 서버 쪽에만 보관한다. 별도 proxy를 쓰는 경우에만 `KSKILL_PROXY_BASE_URL` 을 설정한다.
+
+### Proxy resolution order
+
+1. **`KSKILL_PROXY_BASE_URL` 이 있으면** 그 값을 사용한다.
+2. **없거나 빈 값이면** 기본 hosted proxy `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+3. **직접 proxy를 운영하는 경우에만** proxy 서버 upstream key를 서버 쪽에만 설정한다.
+
+클라이언트/사용자 쪽에서 upstream key를 직접 다루지 않는다.
+
+## Inputs
+
+- 역명
+- 선택 사항: 가져올 건수
+
+## Workflow
+
+### 1. Resolve the proxy base URL
+
+`KSKILL_PROXY_BASE_URL` 이 있으면 그 값을 사용하고, 없거나 비어 있으면 기본 hosted proxy `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+
+### 2. Query the official station arrival endpoint
+
+proxy는 서울 실시간 지하철 API key를 서버에서 주입하고, 역명 기준 실시간 도착정보만 공개 read-only endpoint로 노출한다.
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "${BASE}/v1/seoul-subway/arrival" \
+  --data-urlencode 'stationName=강남'
+```
+
+필요하면 `startIndex`, `endIndex` 로 응답 범위를 조정할 수 있다.
+
+### 3. Summarize the response
+
+가능하면 아래 항목만 먼저 요약한다.
+
+- 호선
+- 상/하행 또는 외/내선
+- 첫 번째 도착 메시지
+- 두 번째 도착 메시지
+- 도착 예정 시간(있으면 초 단위)
+
+### 4. Be conservative about live data
+
+실시간 데이터는 몇 초 단위로 바뀔 수 있으므로, 답변에는 조회 시점을 같이 적는다.
+
+## Done when
+
+- 요청 역의 도착 예정 열차가 정리되어 있다
+- live data 기준 시점이 명시되어 있다
+- upstream key가 클라이언트에 노출되지 않았다
+
+## Failure modes
+
+- proxy upstream key 미설정
+- quota 초과
+- 역명 표기 불일치
+
+## Notes
+
+- 서울 열린데이터 광장 가이드는 실시간 지하철 Open API에 일일 호출 제한이 있을 수 있다고 안내한다
+- proxy 운영/환경변수 설정은 `docs/features/k-skill-proxy.md` 를 참고한다
+- endpoint path는 API 버전 변경 가능성이 있으므로 실패 시 dataset console의 최신 샘플 URL을 다시 확인한다

package/skills/seoul-subway-arrival/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "seoul-subway-arrival",
+  "description": "Look up Seoul real-time subway arrival information with the official Seoul Open Data API. Use when the user asks when a train arrives, which trains are approaching a station, or how crowded Seoul subway timing looks right now.",
+  "profiles": [
+    "proxy",
+    "lookup"
+  ],
+  "frontmatter": "name: seoul-subway-arrival\ndescription: Look up Seoul real-time subway arrival information with the official Seoul Open Data API. Use when the user asks when a train arrives, which trains are approaching a station, or how crowded Seoul subway timing looks right now.\nlicense: MIT\nmetadata:\n  category: transit\n  locale: ko-KR\n  phase: v1"
+}

package/skills/sh-notice-search/instruction.md

@@ -0,0 +1,150 @@
+# SH Notice Search
+
+## What this skill does
+
+서울주택도시개발공사(SH, `www.i-sh.co.kr`)의 **공고 및 공지** 공개 HTML 게시판을 직접 읽어 청약·주택 공고 목록과 상세 본문, 첨부파일 메타데이터를 JSON으로 정리한다.
+
+- 키워드로 SH 공고/공지 목록을 검색한다.
+- 공식 게시판 분류(주택임대, 주택분양, 주택매입/주거복지, 토지, 상가/공장 등)를 선택한다.
+- 상세 페이지에서 본문, 담당부서, 등록일, 조회수, 실제 첨부파일명을 추출한다.
+- 첨부는 아이콘 템플릿이 아니라 `existFile('N')` onclick이 달린 실제 첨부 앵커와 `downList` 메타데이터를 기준으로 추출한다.
+
+청약 신청, 서류 제출, 로그인 필요한 마이페이지 조회, 결제, 알림 발송은 하지 않는다.
+
+## When to use
+
+- "SH 행복주택 공고 찾아줘"
+- "서울주택도시개발공사 매입임대 공고 보여줘"
+- "SH 공고 seq 304371 상세와 첨부파일 알려줘"
+- "SH 분양 공고 최신 목록 조회"
+
+## Prerequisites
+
+- 인터넷 연결
+- Node.js 18+
+- 이 저장소의 `sh-notice-search` npm package 또는 동일 로직
+
+## Public access path discovered
+
+### Primary source: official SH public HTML board
+
+- default rent list: `https://www.i-sh.co.kr/app/lay2/program/S1T294C297/www/brd/m_247/list.do?multi_itm_seq=2`
+- default rent detail: `https://www.i-sh.co.kr/app/lay2/program/S1T294C297/www/brd/m_247/view.do?multi_itm_seq=2&seq=<seq>`
+- title keyword search: add `srchWord=<keyword>&srchTp=0`
+- content keyword search: add `srchWord=<keyword>&srchTp=1`
+- fixed board page size: 10 rows per page; use `page` for pagination.
+
+Discovery result: direct unauthenticated fetches from `www.i-sh.co.kr` return list/detail HTML. A live smoke on 2026-05-15 showed `srchWord=행복주택` without `srchTp` returned the full rent board count, while `srchTp=0` narrowed the result set. Therefore the client always sends `srchTp` when a keyword is present.
+
+No `k-skill-proxy` route is used because this upstream is public and does not require an API key.
+
+## Supported category aliases
+
+| Input aliases | Official tab |
+| --- | --- |
+| `rent`, `임대`, `주택임대` | 주택임대 (`multi_itm_seq=2`) |
+| `sale`, `분양`, `주택분양` | 주택분양 (`multi_itm_seq=1`) |
+| `purchase`, `매입`, `매입임대`, `welfare`, `주거복지` | 주택매입 (`multi_itm_seq=512`) |
+| `land`, `토지` | 토지 |
+| `commercial`, `상가`, `공장` | 상가/공장 |
+| `compensation`, `보상`, `이주` | 보상/이주 |
+| `design`, `현상설계` | 현상설계 |
+| `etc`, `기타` | 기타 |
+| `all`, `전체` | 전체 |
+
+`주거복지`는 SH 공고 및 공지의 공개 탭명이 아니라 사용자 친화 alias이며, 현재는 SH의 공개 `주택매입` 탭으로 매핑한다. 답변할 때는 이 매핑을 밝힌다.
+
+## Workflow
+
+### 1. Search notices
+
+```js
+const { searchNotices } = require("sh-notice-search")
+
+const result = await searchNotices({
+  keyword: "행복주택",
+  category: "임대",
+  page: 1,
+  limit: 5
+})
+
+console.log(result.items)
+```
+
+CLI:
+
+```bash
+node packages/sh-notice-search/src/cli.js 행복주택 --category 임대 --limit 5
+node packages/sh-notice-search/src/cli.js 매입임대 --category 주거복지 --status 진행
+```
+
+Returned list fields include:
+
+- `seq`
+- `title`
+- `department`
+- `registered_date`
+- `views`
+- `is_new`
+- `category`, `category_name`
+- `status`, `status_basis`
+- `detail_url`
+
+### 2. Fetch detail
+
+```js
+const { getNoticeDetail } = require("sh-notice-search")
+
+const detail = await getNoticeDetail({ seq: "304371", category: "임대" })
+console.log(detail.notice.content_text)
+console.log(detail.notice.attachments)
+```
+
+CLI:
+
+```bash
+node packages/sh-notice-search/src/cli.js --seq 304371 --category 임대
+```
+
+Attachment fields:
+
+- `filename`
+- `file_seq`
+- `file_size`
+- `file_type`
+- `preview_url` (official SH preview/converter URL)
+
+Direct download URLs are intentionally not returned. Hand off `detail_url` or `preview_url` to the user's browser.
+
+### 3. Interpret status conservatively
+
+The SH public board list does not expose a first-class status field like `접수중`/`마감`. The package can filter by `status`, but it is a title-text classifier:
+
+- `open`/`진행`: titles with 모집공고, 입주자 모집, 신청, 접수, 공고
+- `closed`/`마감`: titles with 마감, 계약결과, 결과, 완료, 종료
+- `announced`/`당첨자`: titles with 당첨, 발표
+
+When answering, disclose that status is inferred from the title unless the detailed 공고문 body states exact dates.
+
+## Done when
+
+- Official SH list/detail URLs were queried directly from the user machine.
+- Keyword searches include `srchTp` so `srchWord` is not ignored.
+- Pagination uses `page` and recognizes the fixed 10-row board page size.
+- Attachments are extracted from actual `existFile()` anchors/downList metadata, not extension icon templates.
+- Public source URLs are shown, and login/application automation is avoided.
+
+## Failure modes
+
+- SH can change board paths, table markup, JavaScript functions, or `downList` structure; parsing may become partial or fail.
+- IP-rate-limit, NetFunnel throttling, maintenance pages, or temporary 4xx/5xx responses can block live fetches. Do not bypass CAPTCHA/login/queue protections.
+- `srchWord` without `srchTp` is known to be ignored by the SH board; always send `srchTp=0` for title or `srchTp=1` for content.
+- `pageSize` larger than 10 does not make SH return more rows. Use `page` for additional results.
+- Attachment preview URLs may require browser handoff and can be governed by SH's current direct-link/download policy.
+- Status is inferred from title text because the public list lacks an explicit status column.
+
+## Notes
+
+- Read-only lookup only.
+- No proxy, no API key, no secrets.
+- Do not automate 청약 신청, 로그인, 서류 제출, payment, or 마이페이지 flows.

package/skills/sh-notice-search/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "sh-notice-search",
+  "description": "서울주택도시개발공사(SH) 공개 공고/공지 게시판에서 청약·주택 공고 목록, 상세 본문, 첨부 미리보기 메타데이터를 직접 조회한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "proxy",
+    "action:submission"
+  ],
+  "frontmatter": "name: sh-notice-search\ndescription: 서울주택도시개발공사(SH) 공개 공고/공지 게시판에서 청약·주택 공고 목록, 상세 본문, 첨부 미리보기 메타데이터를 직접 조회한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: housing\n  locale: ko-KR\n  phase: v1"
+}

package/skills/srt-booking/instruction.md

@@ -0,0 +1,181 @@
+# SRT Booking
+
+## What this skill does
+
+`SRTrain` 위에 `scripts/srt_booking.py` helper 를 얹어 SRT 조회와 호차별 좌석번호 확인을 처리하고, 예약과 취소는 고정된 열차/예약을 다시 식별한 뒤 `SRTrain`으로 진행한다.
+
+## When to use
+
+- "수서에서 부산 가는 SRT 찾아줘"
+- "내일 오전 SRT 빈자리 있으면 잡아줘"
+- "SRT 5호차 빈 좌석 확인해줘"
+- "SRT 11A 좌석이 비었는지 봐줘"
+- "창측 좌석을 우선해서 SRT 빈자리 보여줘"
+- "예약 내역 확인해줘"
+- "이 SRT 예약 취소해줘"
+
+## When not to use
+
+- 돌쇠가 아니며 결제까지 자동으로 끝내야 하는 경우
+- 비밀번호를 채팅창에 직접 보내려는 경우
+- SRT가 아니라 KTX/Korail 예매인 경우
+
+## Prerequisites
+
+- Python 3.10+
+- `python3 -m pip install SRTrain`
+
+## Required environment variables
+
+- `KSKILL_SRT_ID`
+- `KSKILL_SRT_PASSWORD`
+
+### Credential handling
+
+- 돌쇠 credential mode에서는 `vault-run` capability를 사용하고, 없으면 `request_vault_credential`을 호출한다. ID/PW 원문을 채팅이나 shell에 넣지 않는다.
+- 그 밖의 환경에서는 이미 주입된 환경변수 → host vault → `~/.config/k-skill/secrets.env` 순서로 사용한다.
+
+## Inputs
+
+- 출발역
+- 도착역
+- 날짜: `YYYYMMDD`
+- 희망 시작 시각: `HHMMSS`
+- 인원 수와 승객 유형
+- 좌석 선호: 일반실 / 특실
+- 좌석 상세 조건: 객실 등급, 호차 번호, 좌석 번호, 빈 좌석만 보기, 탐색 우선순위
+
+## Workflow
+
+### 0. Install the package globally when missing
+
+`python3 -c 'import SRT'` 가 실패하면 다른 구현으로 우회하지 말고 전역 Python 패키지 설치를 먼저 시도한다.
+
+```bash
+python3 -m pip install SRTrain
+```
+
+### 1. Ensure credentials are available
+
+돌쇠 credential mode에서는 `vault-run`의 SRT capability를 확인하고, 없으면 `request_vault_credential`로 앱 vault 입력 UI를 호출한다. generic fallback에서만 `KSKILL_SRT_ID`, `KSKILL_SRT_PASSWORD` 환경변수를 확인한다.
+
+시크릿이 없다는 이유로 웹사이트를 직접 긁거나 다른 비공식 경로를 찾지 않는다.
+
+### 2. Search first
+
+먼저 helper 로 조회해서 후보를 요약한다.
+
+```bash
+python3 scripts/srt_booking.py search 수서 부산 20260328 080000 --time-limit 120000 --limit 5
+```
+
+### 3. Summarize options before side effects
+
+예약 전에는 항상 아래를 짧게 정리한다.
+
+- 출발/도착 시각
+- 일반실/특실 가능 여부
+- 예상 운임
+
+### 4. Inspect detailed seats when the user asks for seat numbers
+
+`search` 의 좌석 가능 여부는 열차 단위 플래그다. 사용자가 "남은 좌석 번호", "호차별 좌석", "특정 좌석", "창측/순방향 자리", "예약 전에 자리 확인"처럼 구체적인 좌석을 물으면 예약 전에 `seats` 를 호출한다.
+
+```bash
+python3 scripts/srt_booking.py seats 수서 부산 20260328 080000 --train-id <train_id>
+```
+
+특정 호차의 빈 좌석만 확인하려면 `--car-no` 와 `--available-only` 를 쓴다.
+
+```bash
+python3 scripts/srt_booking.py seats 수서 부산 20260328 080000 --train-id <train_id> --car-no 5 --available-only
+```
+
+특정 좌석이 비었는지 확인하려면 `--seat` 를 붙인다.
+
+```bash
+python3 scripts/srt_booking.py seats 수서 부산 20260328 080000 --train-id <train_id> --car-no 5 --seat 11A
+```
+
+특정 호차를 지정하지 않으면 가운데 호차부터 탐색한다. `--car-priority center|low|high` 로 호차 탐색 순서를 바꾸고, `--seat-priority forward-window|window-forward|row-low` 로 좌석 정렬 우선순위를 바꾼다.
+
+상세 좌석 응답을 보여줄 때는 아래를 우선 요약한다.
+
+- 호차별 `available_seat_count`
+- 남은 좌석 번호 (`available_seats`)
+- 좌석별 `direction`, `position`
+- 특정 좌석 요청이면 `requested_seat_available`
+
+이 기능은 좌석을 선택/선점하지 않는다. 실제 예약은 다음 단계에서만 진행한다.
+
+### 5. Reserve only after the train is fixed
+
+예약은 부작용이 있으므로 정확한 열차를 고른 뒤에만 진행한다.
+
+```bash
+python3 - <<'PY'
+import os
+from SRT import Adult, SRT, SeatType
+
+srt = SRT(os.environ["KSKILL_SRT_ID"], os.environ["KSKILL_SRT_PASSWORD"])
+trains = srt.search_train("수서", "부산", "20260328", "080000", time_limit="120000")
+reservation = srt.reserve(
+    trains[0],
+    passengers=[Adult(1)],
+    special_seat=SeatType.GENERAL_FIRST,
+)
+print(reservation)
+PY
+```
+
+### 6. Continue to payment in Dolshoi
+
+예약이 성공하면 예약번호, 운임, 구입기한을 즉시 알려서 **좌석 확보는 완료되었다**고 명확히 말한다.
+
+돌쇠에서 사용자가 예매 완료를 요청했다면 여기서 멈추지 않는다.
+
+1. CloakBrowser의 공식 SRT 예약/결제 화면에서 방금 만든 예약을 다시 식별한다.
+2. vault-backed login을 사용하고 결제수단/할인/승객/예약 정보를 확인한다.
+3. 실제 결제 버튼 직전에 `clarify`로 열차, 날짜·시각, 승객, 좌석 등급, 총액을 보여주고 승인받는다.
+4. 승인되면 결제를 실행하고 결제 완료 화면, 예약번호, 영수증/결제 상태를 확인한다.
+
+돌쇠가 아니거나 공식 결제 표면을 사용할 수 없으면 예약번호와 구입기한을 제공하고 generic handoff로 종료한다.
+
+### 7. Inspect or cancel
+
+취소 전에는 대상 예약을 다시 식별한다.
+
+```bash
+python3 - <<'PY'
+import os
+from SRT import SRT
+
+srt = SRT(os.environ["KSKILL_SRT_ID"], os.environ["KSKILL_SRT_PASSWORD"])
+reservations = srt.get_reservations()
+print(reservations)
+PY
+```
+
+취소 실행 직전에 `clarify`로 예약번호, 열차, 날짜·시각, 승객, 환불/위약금 정보를 확인하고 승인받는다.
+
+## Done when
+
+- 조회 요청이면 후보 열차가 정리되어 있다
+- 좌석 상세 확인이면 호차별 남은 좌석번호나 특정 좌석 공석 여부가 정리되어 있다
+- 예약 요청이면 예약 결과, 운임, 구입기한이 확인되어 좌석 확보 완료를 안내했다
+- 돌쇠의 예매 완료 요청이면 `clarify` 승인 후 결제 완료 상태와 영수증/예약번호를 확인했다
+- 취소 요청이면 어떤 예약을 취소했는지 명확하다
+
+## Failure modes
+
+- 로그인 오류: 계정 정보나 SRT site policy 변경 가능성 확인
+- 매진: 다른 시간대나 좌석 타입으로 재조회
+- 좌석선택 페이지 형식 변경: helper 파서 업데이트 필요
+- 네트워크 오류: 짧게 재시도하되 aggressive polling은 피하기
+
+## Notes
+
+- 상세 좌석 확인은 SRT 웹 좌석선택 페이지를 조회 전용으로 읽는다
+- `SRTrain`은 SRT 전용 라이브러리라서 스킬 의도가 더 선명하다
+- 결제 자동화 금지는 generic fallback에만 적용한다. 돌쇠에서는 `clarify` 승인 후 공식 결제 표면으로 완료한다
+- 자동 재시도 루프는 계정 보호 차원에서 짧고 보수적으로 유지한다