@nomadamas/k-skill 0.1.0

package/skills/k-skill-setup/skill.json

@@ -0,0 +1,11 @@
+{
+  "name": "k-skill-setup",
+  "description": "After installing the full k-skill bundle, configure and verify the shared cross-platform setup, then optionally wire update checks and GitHub starring with explicit user consent.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "browser",
+    "local"
+  ],
+  "frontmatter": "name: k-skill-setup\ndescription: After installing the full k-skill bundle, configure and verify the shared cross-platform setup, then optionally wire update checks and GitHub starring with explicit user consent.\nlicense: MIT\nmetadata:\n  category: setup\n  locale: ko-KR\n  phase: v1"
+}

package/skills/kakao-bar-nearby/instruction.md

@@ -0,0 +1,76 @@
+# Kakao Bar Nearby
+
+## What this skill does
+
+유저가 알려준 현재 위치를 기준으로 **카카오맵 기준 근처 술집**을 찾아준다.
+
+- 위치는 자동으로 추정하지 않는다.
+- **반드시 먼저 현재 위치를 질문**한다.
+- `서울역`, `강남`, `사당`, `신논현`, `논현` 같은 역명/동네/랜드마크 질의를 그대로 받을 수 있다.
+- 결과에는 현재 영업 상태, 대표 메뉴, 좌석 옵션(단체석/바테이블 등), 전화번호를 포함한다.
+
+## When to use
+
+- "서울역 근처 술집 찾아줘"
+- "강남에서 지금 영업중인 와인바 뭐 있어?"
+- "논현 근처 4명 갈만한 술집 알려줘"
+- "사당에서 전화번호 있는 이자카야 몇 군데만 보여줘"
+
+## Mandatory first question
+
+위치 정보 없이 바로 검색하지 말고 반드시 먼저 물어본다.
+
+- 권장 질문: `현재 위치를 알려주세요. 서울역/강남/사당 같은 역명이나 동네명으로 보내주시면 카카오맵 기준 근처 술집을 찾아볼게요.`
+- 위치가 애매하면: `가까운 역명이나 동 이름으로 한 번만 더 알려주세요.`
+
+## Official Kakao Map surfaces
+
+- 모바일 검색: `https://m.map.kakao.com/actions/searchView?q=<query>`
+- 장소 패널 JSON: `https://place-api.map.kakao.com/places/panel3/<confirmId>`
+- 장소 상세 페이지: `https://place.map.kakao.com/<confirmId>`
+
+## Workflow
+
+1. 유저에게 반드시 현재 위치를 묻는다.
+2. 받은 위치 문자열을 카카오맵 검색으로 anchor 후보(역/랜드마크)로 해석한다.
+3. 같은 위치 문자열에 `술집` 키워드를 붙여 nearby 술집 검색 결과를 가져온다.
+4. 상위 후보의 panel3 JSON 을 조회해 현재 영업 상태, 메뉴, 좌석 옵션, 전화번호를 정규화한다.
+5. **영업 중인 술집을 먼저** 보여주고, 필요하면 곧 열 곳도 함께 보여준다.
+
+## Responding
+
+보통 3~5개만 짧게 정리한다.
+
+- 술집명
+- 카테고리
+- 영업 상태 (`영업 중`, `영업 전`, `휴무일` 등)
+- 대표 메뉴 2~3개
+- 좌석/인원 수용 힌트 (`단체석`, `바테이블` 등)
+- 전화번호
+- 거리(가능하면)
+
+## Node.js example
+
+```js
+const { searchNearbyBarsByLocationQuery } = require("kakao-bar-nearby");
+
+async function main() {
+  const result = await searchNearbyBarsByLocationQuery("서울역", {
+    limit: 5
+  });
+
+  console.log(result.anchor);
+  console.log(result.items);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+```
+
+## Done when
+
+- 유저의 현재 위치를 먼저 확인했다.
+- 카카오맵 기준 술집 결과를 최소 1개 이상 찾았거나, 찾지 못한 이유와 다음 질문을 제시했다.
+- 영업 상태/메뉴/좌석 옵션/전화번호가 포함된 요약을 보여줬다.

package/skills/kakao-bar-nearby/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "kakao-bar-nearby",
+  "description": "Use when the user asks for nearby bars or 근처 술집. Always ask the user's current location first, then use Kakao Map search + place detail panels to find open-now bars with menu, seating, and phone hints. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "action:booking"
+  ],
+  "frontmatter": "name: kakao-bar-nearby\ndescription: Use when the user asks for nearby bars or 근처 술집. Always ask the user's current location first, then use Kakao Map search + place detail panels to find open-now bars with menu, seating, and phone hints. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: food\n  locale: ko-KR\n  phase: v1"
+}

package/skills/kakao-map/instruction.md

@@ -0,0 +1,176 @@
+# Kakao Map
+
+## What this skill does
+
+Kakao Developers의 두 API를 `k-skill-proxy` 경유로 묶어 다음 두 종류 질문에 답한다:
+
+1. **장소 검색** — 키워드/카테고리/좌표 기준으로 가게·시설·랜드마크를 찾고, 좌표↔주소·행정구역을 변환한다 (Kakao Local REST API).
+2. **자동차 길찾기** — 출발지·목적지 좌표를 받아 거리·소요시간·통행료·예상 택시 요금을 조회한다 (Kakao Mobility Directions API).
+
+- 운영자 `KAKAO_REST_API_KEY` 를 proxy 서버에만 보관한다. 사용자는 키 발급 필요 없음.
+- 두 API 모두 같은 Kakao REST API key (KakaoAK 헤더) 로 인증한다.
+- 본 스킬은 **조회 전용**이다. 예약·결제·운전 자동화는 하지 않는다.
+
+## When to use
+
+- "강남역 근처 스타벅스 찾아줘" → keyword 검색 (x,y 중심)
+- "역삼동 카페 카테고리로 보여줘" → category 검색 (FD6/CE7 등)
+- "이 좌표가 어느 동/도로명 주소야?" → coord2address / coord2region
+- "강남역에서 시청까지 자동차로 얼마나 걸려?" → Kakao Mobility directions
+- "통행료 회피 경로로 알려줘" → avoid=toll (필요 시 priority=DISTANCE 병행)
+
+## When NOT to use
+
+- 대중교통(지하철·버스) 경로 → Kakao Mobility는 **자동차 전용**. 대중교통은 `korean-transit-route`(ODsay) 사용
+- 도보·자전거 경로 (Kakao Mobility에 정식 API 없음)
+- 실시간 교통 상황을 1분 단위로 추적 (proxy cache 가 있음)
+- 카카오맵 외부 임베드/렌더링 (본 스킬은 데이터 조회만 함)
+- 대량 인덱싱/스크래핑 (Kakao 약관 위반 + 일일 quota 초과 위험)
+
+## Prerequisites
+
+- Python 3 표준 라이브러리만 사용 가능. JS/curl 호출도 동일하게 지원.
+- optional: `KSKILL_PROXY_BASE_URL` (self-host·별도 프록시 사용 시. 비우면 hosted `https://k-skill-proxy.nomadamas.org` 기본).
+
+## Required environment variables
+
+사용자 머신에는 **필요 없다.** 운영자 proxy 서버에 다음을 둔다:
+
+- `KAKAO_REST_API_KEY` — Kakao Developers REST API 키 (Local + Mobility 공용)
+
+키가 없으면 모든 `/v1/kakao-map/*` 및 `/v1/kakao-mobility/*` 라우트가 `503 upstream_not_configured` 를 돌려준다.
+
+## Proxy routes
+
+| endpoint | 용도 | 주요 입력 |
+|---|---|---|
+| `GET /v1/kakao-map/search/keyword` | 키워드 장소 검색 | `q`, optional `x`,`y`(중심좌표), `radius`(0~20000m), `category_group_code`, `sort`(accuracy\|distance), `page`(1~45), `size`(1~15) |
+| `GET /v1/kakao-map/search/category` | 카테고리 장소 검색 (좌표 중심 필수) | `category_group_code`(예: FD6 음식점, CE7 카페), `x`, `y`, `radius`(기본 500), `sort`, `page`, `size` |
+| `GET /v1/kakao-map/coord2address` | 좌표 → 도로명/지번 주소 | `x`, `y`, optional `input_coord`(WGS84 기본) |
+| `GET /v1/kakao-map/coord2region` | 좌표 → 행정구역(시/도/시군구/동) | `x`, `y`, optional `input_coord` |
+| `GET /v1/kakao-mobility/directions` | 자동차 길찾기 | `origin=x,y`, `destination=x,y`, optional `waypoints`(최대 5, `\|` 구분), `priority`(RECOMMEND\|TIME\|DISTANCE), `car_fuel`(GASOLINE\|DIESEL\|LPG), `car_hipass`(true\|false), `alternatives`(true\|false), `avoid`(ferries\|toll\|motorway\|schoolzone\|uturn; `\|` 구분) |
+
+**Kakao 카테고리 그룹 코드** (자주 쓰는 것):
+
+| 코드 | 의미 |
+|---|---|
+| MT1 | 대형마트 |
+| CS2 | 편의점 |
+| PK6 | 주차장 |
+| OL7 | 주유소/충전소 |
+| SW8 | 지하철역 |
+| BK9 | 은행 |
+| CT1 | 문화시설 |
+| AT4 | 관광명소 |
+| AD5 | 숙박 |
+| FD6 | 음식점 |
+| CE7 | 카페 |
+| HP8 | 병원 |
+| PM9 | 약국 |
+
+## Workflow
+
+### 1. 키워드 검색
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "${BASE}/v1/kakao-map/search/keyword" \
+  --data-urlencode 'q=스타벅스' \
+  --data-urlencode 'x=127.0276' \
+  --data-urlencode 'y=37.4979' \
+  --data-urlencode 'radius=500' \
+  --data-urlencode 'sort=distance'
+```
+
+응답의 `documents[]` 에서 `place_name`, `road_address_name`, `phone`, `place_url`, `distance` 를 추출해 사용자에게 보여준다.
+
+### 2. 카테고리 검색
+
+```bash
+curl -fsS --get "${BASE}/v1/kakao-map/search/category" \
+  --data-urlencode 'category_group_code=FD6' \
+  --data-urlencode 'x=127.0276' \
+  --data-urlencode 'y=37.4979' \
+  --data-urlencode 'radius=300'
+```
+
+### 3. 좌표 → 주소
+
+```bash
+curl -fsS --get "${BASE}/v1/kakao-map/coord2address" \
+  --data-urlencode 'x=127.0276' \
+  --data-urlencode 'y=37.4979'
+```
+
+`documents[0].road_address.address_name`, `documents[0].address.address_name` 사용.
+
+### 4. 좌표 → 행정구역
+
+```bash
+curl -fsS --get "${BASE}/v1/kakao-map/coord2region" \
+  --data-urlencode 'x=127.0276' \
+  --data-urlencode 'y=37.4979'
+```
+
+응답에 `region_type`(B=법정동, H=행정동) 별 결과가 들어있다.
+
+### 5. 자동차 길찾기
+
+```bash
+curl -fsS --get "${BASE}/v1/kakao-mobility/directions" \
+  --data-urlencode 'origin=126.9706,37.5559' \
+  --data-urlencode 'destination=127.0276,37.4979' \
+  --data-urlencode 'priority=RECOMMEND' \
+  --data-urlencode 'avoid=toll'
+```
+
+응답에서 `routes[0].summary` 를 읽는다:
+
+- `distance` (meter) → km 환산
+- `duration` (second) → 분 환산
+- `fare.taxi`, `fare.toll` → 원
+- `priority` (요청한 값 echo)
+- `avoid` 요청 시 `toll` 등 회피 옵션 적용
+
+### 6. 출력 포맷
+
+장소 검색:
+
+```text
+강남역 근처 스타벅스 5곳 (반경 500m, 가까운 순)
+1) 스타벅스 강남R점 — 강남구 테헤란로 ... (120m, 02-...)
+2) ...
+```
+
+자동차 길찾기:
+
+```text
+자동차 경로: (126.9706,37.5559) → (127.0276,37.4979)
+- 거리: 12.3km / 예상 소요시간: 25분
+- 통행료: 1,200원 / 예상 택시요금: 18,500원
+- 옵션: RECOMMEND, avoid=toll
+- 조회 시각: 2026-05-23T14:00:00.000Z
+```
+
+## Failure modes
+
+- `KAKAO_REST_API_KEY` 미설정 → `503 upstream_not_configured`
+- Kakao 인증 실패(401/403) → proxy가 `503` 으로 변환 (key revoke / 쿼터 초과 신호)
+- 좌표/파라미터 형식 오류 → `400 bad_request`
+- 출발지=도착지가 너무 가까움 (`result_code=104` 등) → `502 upstream_semantic_error` + `result_msg`
+- Kakao 일일 쿼터 초과 → `502` 또는 `503` (proxy cache 가 있는 만큼 호출 빈도를 줄임)
+- 네트워크 실패 → `502 upstream_error`
+
+## Done when
+
+- 사용자 질문에 맞는 endpoint 1~2개를 선택해 호출했고, 응답을 사람-읽기 좋게 정리했다.
+- 좌표나 주소는 출처 endpoint를 함께 명시한다 (Kakao Local vs Kakao Mobility).
+- secret/token/.env 원문은 노출되지 않았다.
+- 자동차 외 이동 수단을 요청받으면 본 스킬의 범위 외임을 명시하고 `korean-transit-route` 등 대체 안내.
+
+## Notes
+
+- Kakao Mobility는 **자동차 전용** API다. 대중교통 길찾기는 별도 ODsay 기반 `korean-transit-route` 스킬을 쓴다.
+- 무료 일일 쿼터(2026년 기준 Local 300,000건 / Mobility 1,000건) 안에서 proxy cache(기본 TTL 5분) + rate-limit(기본 60req/분) 으로 보호한다.
+- proxy 운영/환경변수는 [k-skill 프록시 서버 가이드](../docs/features/k-skill-proxy.md) 참고.
+- `/v1/kakao-local/geocode` (기존)도 같은 키를 쓰며 여전히 사용 가능하다 (address → keyword 자동 fallback). 본 스킬은 그 위에 keyword/category/coord 계열을 명시적으로 노출한다.

package/skills/kakao-map/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "kakao-map",
+  "description": "Kakao Local (장소 검색·주소-좌표 변환) + Kakao Mobility (자동차 길찾기) 를 k-skill-proxy 경유로 조회한다. 사용자 키 불필요. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "action:booking"
+  ],
+  "frontmatter": "name: kakao-map\ndescription: Kakao Local (장소 검색·주소-좌표 변환) + Kakao Mobility (자동차 길찾기) 를 k-skill-proxy 경유로 조회한다. 사용자 키 불필요. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: transit\n  locale: ko-KR\n  phase: v1"
+}

package/skills/kakaotalk-mac/instruction.md

@@ -0,0 +1,189 @@
+# KakaoTalk katok Search
+
+## What this skill does
+
+`katok` CLI를 유일한 실행 표면으로 사용해 macOS 카카오톡 대화를 로컬 아카이브와 검색 인덱스로 동기화하고, keyword/BM25/semantic 검색과 chunk 조회를 수행한다.
+
+이 스킬은 기존 `kakaotalk-mac` 설치 경로를 유지하지만 내부 동작은 `katok` 기반이다. 메시지 전송, 삭제, UI 자동화, 직접 DB 읽기, 인증 캐시 처리, 복호화 material 처리는 이 스킬의 범위가 아니다.
+
+## Privacy Rules
+
+- Do not inspect local database internals from this skill.
+- Do not directly read KakaoTalk DB files.
+- Do not handle auth caches or decryption material.
+- Use `katok sync --source macos --json` for live macOS KakaoTalk ingestion.
+- Search commands should return snippets and chunk ids first.
+- Retrieve full chunk content only when the user explicitly asks to open a result or provides a chunk id.
+
+## When to use
+
+- "카카오톡에서 특정 키워드 검색해줘"
+- "카톡에서 지난 회의/계약/약속 이야기 찾아줘"
+- "이 검색 결과 chunk를 열어줘"
+- "최근 대화가 반영됐는지 확인하고 검색해줘"
+
+## When not to use
+
+- macOS가 아닌 환경
+- Intel Mac에서 로컬 EmbeddingGemma semantic index가 필요한 경우
+- 카카오톡 메시지를 보내거나 삭제해야 하는 경우
+- 카카오톡 DB 파일, 인증 캐시, 복호화 material을 직접 다루라는 요청
+- 서버-투-서버 공식 Kakao API 연동 요청
+
+## Prerequisites
+
+- Apple Silicon macOS
+- KakaoTalk for Mac 설치
+- Homebrew 또는 Cargo
+- `katok` CLI 설치
+- 현재 터미널 앱에 Full Disk Access 권한
+
+## Install katok
+
+Homebrew:
+
+```bash
+brew tap NomaDamas/katok https://github.com/NomaDamas/katok.git
+brew install katok
+```
+
+Cargo:
+
+```bash
+cargo install katok
+export PATH="$HOME/.cargo/bin:$PATH"
+```
+
+설치 후 CLI가 보이는지 확인한다.
+
+```bash
+katok --help
+katok doctor --json
+```
+
+## Workflow
+
+### 1. Check readiness without prompting for app data
+
+```bash
+katok doctor --json
+```
+
+`doctor --json`의 `freshness` 섹션에서 마지막 sync/index 상태를 확인한다. 이 기본 doctor는 macOS app-data probe를 실행하지 않으므로 권한 prompt를 띄우지 않는 준비 상태 점검에 적합하다.
+
+### 2. Open macOS permission settings when needed
+
+Full Disk Access 설정이 필요하면 사용자가 직접 허용할 수 있도록 설정 화면을 연다.
+
+```bash
+katok permissions macos
+```
+
+KakaoTalk UI 자동화는 이 스킬 범위가 아니지만, upstream 진단을 위해 Accessibility 설정 화면까지 열어야 하는 경우에만 다음 명령을 쓴다.
+
+```bash
+katok permissions macos --accessibility
+```
+
+### 3. Run explicit macOS setup diagnostics only when needed
+
+카카오톡 앱 설치, container, DB 파일 접근 같은 macOS source adapter 상태를 확인해야 할 때만 probe를 실행한다. 이 명령은 macOS가 app-data 접근 prompt를 띄울 수 있다.
+
+```bash
+katok doctor --macos-probe --json
+```
+
+### 4. Sync local KakaoTalk archives
+
+최신 대화가 중요하거나 `freshness.recommendation.sync_before_search`가 true이면 검색 전에 sync한다.
+
+```bash
+katok sync --source macos --json
+```
+
+설정 파일의 기본 source adapter를 쓰는 경우:
+
+```bash
+katok sync --json
+```
+
+### 5. Build or refresh the semantic index
+
+semantic search 전 `freshness.recommendation.index_before_semantic_search`가 true이거나 방금 sync한 내용을 semantic 검색에 반영해야 하면 index를 만든다.
+
+```bash
+katok index --json
+```
+
+`katok index`는 기본적으로 로컬 `embeddinggemma-300m-q4` embedder를 사용한다. Python, Jina, TEI, 별도 HTTP embedding server를 요구하지 않는다.
+
+### 6. Search with the narrowest useful mode
+
+정확한 문자열, 이름, 계좌번호, 고유명사는 keyword search를 먼저 쓴다.
+
+```bash
+katok search keyword "검색어" --json
+```
+
+여러 단어가 섞인 일반 질의는 BM25를 쓴다.
+
+```bash
+katok search bm25 "지난주 미팅 자료" --json
+```
+
+표현이 정확히 기억나지 않는 의미 기반 질의는 semantic search를 쓴다.
+
+```bash
+katok search semantic "최근에 논의한 세금 신고 일정" --json
+```
+
+### 7. Retrieve explicit chunks only when needed
+
+검색 결과는 먼저 snippet과 chunk id 중심으로 요약한다. 사용자가 특정 결과를 열어 달라고 하거나 chunk id를 제공했을 때만 원문 chunk를 조회한다.
+
+```bash
+katok chunk get <chunk-id> --json
+katok chunk context <chunk-id> --json
+katok chunk parent <chunk-id> --json
+```
+
+- `katok chunk get <chunk-id> --json`: 해당 chunk 원문 조회
+- `katok chunk context <chunk-id> --json`: 같은 채팅방의 직전/직후 micro chunk 조회
+- `katok chunk parent <chunk-id> --json`: semantic search parent window 조회
+
+## Synthetic QA only
+
+실제 카카오톡 설치 없이 upstream fixture로 테스트할 때만 fixture source와 deterministic embedder를 사용한다.
+
+```bash
+katok sync --source fixture tests/fixtures/kakao/replies.jsonl --json
+KATOK_EMBEDDER=local-test katok index --json
+KATOK_EMBEDDER=mock katok index --json
+```
+
+실사용 경로에서는 fixture, mock embedder, 원격 embedding endpoint를 사용하지 않는다.
+
+## Done when
+
+- readiness 요청이면 `katok doctor --json` 결과와 freshness 권장사항을 요약했다.
+- 최신 검색 요청이면 필요한 경우 `katok sync --source macos --json`과 `katok index --json` 실행 여부를 명확히 했다.
+- 검색 요청이면 keyword/BM25/semantic 중 선택한 이유와 JSON 검색 결과 요약을 제공했다.
+- chunk 조회 요청이면 사용자가 지정한 chunk id에 대해서만 `katok chunk get/context/parent` 결과를 요약했다.
+
+## Failure modes
+
+- `katok` 미설치 또는 Cargo binary PATH 누락
+- Apple Silicon macOS가 아님
+- KakaoTalk for Mac 미설치
+- Full Disk Access 미부여
+- `katok doctor --macos-probe --json`에서 container 또는 DB 파일 접근 실패
+- sync 전이라 local archive가 비어 있음
+- semantic index가 오래되었거나 아직 생성되지 않음
+- 검색 결과가 snippet/chunk id만으로 충분하지 않아 명시적 chunk 조회가 필요함
+
+## Notes
+
+- 이 스킬은 read/search/retrieve 전용이다.
+- 메시지 전송과 삭제는 지원하지 않는다.
+- DB 내부 구조, auth cache, decryption material은 직접 다루지 않는다.
+- 기존 설치 이름은 `kakaotalk-mac`이지만 실행 표면은 `katok`이다.

package/skills/kakaotalk-mac/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "kakaotalk-mac",
+  "description": "Search local KakaoTalk archives on Apple Silicon macOS through the katok CLI. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "action:communication"
+  ],
+  "frontmatter": "name: kakaotalk-mac\ndescription: Search local KakaoTalk archives on Apple Silicon macOS through the katok CLI. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: messaging\n  locale: ko-KR\n  phase: v2"
+}

package/skills/kbl-results/instruction.md

@@ -0,0 +1,89 @@
+# KBL Results
+
+## What this skill does
+
+공식 KBL JSON 표면으로 특정 날짜의 한국프로농구 경기 일정/결과를 조회하고, 필요하면 특정 팀(예: `서울 SK`, `부산 KCC`, 팀 코드 `55`)만 필터링한 뒤 현재 팀 순위까지 함께 정리한다.
+
+## When to use
+
+- "오늘 KBL 경기 결과 알려줘"
+- "2026-04-01 서울 SK 경기 결과 보여줘"
+- "KBL 현재 팀 순위 알려줘"
+
+## Prerequisites
+
+- Node.js 18+
+- `npm install -g kbl-results`
+
+## Inputs
+
+- 날짜: `YYYY-MM-DD`
+- 선택 사항: 팀명, 풀네임, 팀 코드
+
+## Workflow
+
+### 0. Install the package globally when missing
+
+`npm root -g` 아래에 `kbl-results` 가 없으면 HTML scraping 으로 우회하지 말고 먼저 전역 Node 패키지 설치를 시도한다.
+
+```bash
+npm install -g kbl-results
+```
+
+### 1. Fetch the official KBL JSON
+
+공식 KBL 웹앱은 `https://api.kbl.or.kr` JSON API를 사용한다. 따라서 브라우저 크롤링 전에 아래 표면을 우선 사용한다.
+
+- 일정/결과: `https://api.kbl.or.kr/match/list`
+- 팀 순위: `https://api.kbl.or.kr/league/rank/team`
+
+```bash
+GLOBAL_NPM_ROOT="$(npm root -g)" node --input-type=module - <<'JS'
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const entry = pathToFileURL(
+  path.join(process.env.GLOBAL_NPM_ROOT, "kbl-results", "src", "index.js"),
+).href;
+const { getKBLSummary } = await import(entry);
+
+const summary = await getKBLSummary("2026-04-01", {
+  team: "부산 KCC",
+  includeStandings: true,
+});
+
+console.log(JSON.stringify(summary, null, 2));
+JS
+```
+
+### 2. Normalize for humans
+
+원본 JSON을 그대로 던지지 말고 아래 기준으로 정리한다.
+
+- 홈팀 vs 원정팀
+- 경기 시간 / 종료 여부 / LIVE 여부
+- 스코어
+- 현재 순위
+- 요청 팀이 있으면 해당 팀 경기만 필터링
+
+### 3. Keep the answer compact
+
+요청이 scoreboard 면 경기별 한 줄 요약부터 준다. 특정 팀 요청이면 그 팀 경기와 현재 순위만 먼저 보여준다.
+
+## Done when
+
+- 날짜 기준 경기 요약이 있다
+- 팀 요청이면 해당 팀 경기만 남아 있다
+- 현재 순위가 같이 정리되어 있다
+
+## Failure modes
+
+- KBL가 `api.kbl.or.kr` 응답 구조를 바꾸면 패키지 수정이 필요하다
+- 경기 전 날짜면 결과 대신 예정 상태가 반환될 수 있다
+- 크롤링 fallback은 공식 JSON이 막혔을 때만 검토한다
+
+## Notes
+
+- 이 스킬은 조회 전용이다
+- 사용자의 "오늘/어제" 요청은 항상 절대 날짜(`YYYY-MM-DD`)로 변환해서 실행한다
+- 자세한 사용 예시는 `docs/features/kbl-results.md` 와 `packages/kbl-results/README.md` 를 따른다

package/skills/kbl-results/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "kbl-results",
+  "description": "KBL 한국프로농구 경기 결과와 현재 팀 순위를 날짜/팀 기준으로 조회한다. 공식 JSON 엔드포인트와 kbl-results npm 패키지를 사용한다.",
+  "profiles": [
+    "browser",
+    "lookup"
+  ],
+  "frontmatter": "name: kbl-results\ndescription: KBL 한국프로농구 경기 결과와 현재 팀 순위를 날짜/팀 기준으로 조회한다. 공식 JSON 엔드포인트와 kbl-results npm 패키지를 사용한다.\nlicense: MIT\nmetadata:\n  category: sports\n  locale: ko-KR\n  phase: v1"
+}

package/skills/kbo-results/instruction.md

@@ -0,0 +1,82 @@
+# KBO Results
+
+## What this skill does
+
+`kbo-game` 패키지로 특정 날짜 KBO 경기 정보를 가져와 경기 일정, 스코어, 상태를 요약한다.
+
+## When to use
+
+- "오늘 KBO 경기 결과 알려줘"
+- "어제 한화 경기 스코어 보여줘"
+- "2026-04-01 KBO 일정 정리해줘"
+
+## Prerequisites
+
+- Node.js 18+
+- `npm install -g kbo-game`
+
+## Inputs
+
+- 날짜: `YYYY-MM-DD`
+- 선택 사항: 특정 팀명
+
+## Workflow
+
+### 0. Install the package globally when missing
+
+`npm root -g` 아래에 `kbo-game` 이 없으면 다른 구현으로 우회하지 말고 전역 Node 패키지 설치를 먼저 시도한다.
+
+```bash
+npm install -g kbo-game
+```
+
+패키지가 없다는 이유로 다른 비공식 scoreboard 소스를 자동 채택하지 않는다.
+
+### 1. Fetch the date
+
+```bash
+GLOBAL_NPM_ROOT="$(npm root -g)" node --input-type=module - <<'JS'
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const entry = pathToFileURL(
+  path.join(process.env.GLOBAL_NPM_ROOT, "kbo-game", "dist", "index.js"),
+).href;
+const { getGame } = await import(entry);
+
+const date = "2026-03-25";
+const games = await getGame(new Date(`${date}T00:00:00+09:00`));
+console.log(JSON.stringify(games, null, 2));
+JS
+```
+
+`kbo-game@0.0.2` 기준 실제 export는 `getGame` 하나이며, 문자열 날짜(`"2026-03-25"`)를 직접 넘기면 실패한다. 항상 `Date` 객체로 변환해서 호출한다. 전역 설치를 기본으로 쓰므로 inline snippet에서는 전역 npm root 아래 entry file을 직접 import 한다.
+
+### 2. Normalize for humans
+
+원본 데이터를 그대로 던지지 말고 아래 기준으로 정리한다.
+
+- 홈팀 vs 원정팀
+- 진행 상태 또는 경기 종료 여부
+- 스코어
+- 필요한 경우 특정 팀만 필터링
+
+### 3. Keep the answer compact
+
+사용자가 scoreboard를 원하면 경기별 한 줄 요약부터 준다.
+
+## Done when
+
+- 날짜 기준 전체 경기 요약이 있다
+- 팀 필터 요청이면 해당 팀 경기만 남아 있다
+- raw JSON이 필요하면 별도로 제공할 수 있다
+
+## Failure modes
+
+- KBO 사이트 변경으로 패키지 응답이 깨질 수 있다
+- 비시즌 날짜는 빈 결과가 올 수 있다
+
+## Notes
+
+- 이 스킬은 조회 전용이다
+- 사용자 기준 "오늘/어제" 같은 상대 날짜는 항상 절대 날짜로 변환해서 실행한다

package/skills/kbo-results/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "kbo-results",
+  "description": "Fetch KBO game schedules and results for a specific date with the kbo-game npm package. Use when the user asks for today's KBO games, yesterday's scores, or a date-specific scoreboard.",
+  "profiles": [
+    "lookup"
+  ],
+  "frontmatter": "name: kbo-results\ndescription: Fetch KBO game schedules and results for a specific date with the kbo-game npm package. Use when the user asks for today's KBO games, yesterday's scores, or a date-specific scoreboard.\nlicense: MIT\nmetadata:\n  category: sports\n  locale: ko-KR\n  phase: v1"
+}