@nomadamas/k-skill 0.1.0

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

@@ -0,0 +1,194 @@
+# Korean Stock Search
+
+## What this skill does
+
+기본적으로 `https://k-skill-proxy.nomadamas.org/v1/korean-stock/...` 로 요청해서 KRX 상장 종목 검색, 종목 기본정보, 일별 시세를 조회한다.
+
+upstream 설계 참고는 [`jjlabsio/korea-stock-mcp`](https://github.com/jjlabsio/korea-stock-mcp) 이지만, 사용자는 `KRX_API_KEY` 를 발급받거나 로컬 MCP 서버를 설치할 필요가 없다. `KRX_API_KEY` 는 proxy 서버에서만 관리한다.
+
+## When to use
+
+- "삼성전자 종목코드랑 시장구분 찾아줘"
+- "005930 기본정보 보여줘"
+- "SK하이닉스 20260408 종가/거래량 알려줘"
+- "KOSDAQ 에서 알테오젠 시세 확인해줘"
+
+## When not to use
+
+- 미국/일본/가상자산 같은 비한국 주식 조회
+- 실시간 체결/호가/분봉 조회
+- 재무제표/공시 원문 분석 (이 스킬 범위 밖)
+- 투자 자문/매수 추천
+
+## Inputs
+
+- `q`: 종목명 또는 종목코드 검색어 (`search` endpoint)
+- `market`: `KOSPI` | `KOSDAQ` | `KONEX`
+- `code`: 종목코드 (보통 6자리 단축코드, 예: `005930`)
+- `bas_dd`: 기준일 `YYYYMMDD` (없으면 KST 오늘 날짜 기본값, 휴장일이면 최근 영업일로 다시 시도)
+- `limit`: 검색 결과 수 (기본 10, 최대 20)
+
+## Prerequisites
+
+없음. 사용자는 `KRX_API_KEY` 를 준비할 필요가 없다. upstream key는 proxy 서버에서만 주입한다.
+
+## Default path
+
+추가 client API 레이어는 불필요하다. 그냥 프록시 서버에 HTTP 요청만 넣으면 된다.
+
+`KSKILL_PROXY_BASE_URL` 환경변수가 있으면 그 값을 사용하고, 없으면 기본 경로 `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+
+## Supported endpoints
+
+### 종목 검색
+
+```http
+GET /v1/korean-stock/search?q={검색어}&bas_dd={YYYYMMDD}
+```
+
+### 종목 기본정보
+
+```http
+GET /v1/korean-stock/base-info?market={KOSPI|KOSDAQ|KONEX}&code={종목코드}&bas_dd={YYYYMMDD}
+```
+
+### 종목 일별 시세
+
+```http
+GET /v1/korean-stock/trade-info?market={KOSPI|KOSDAQ|KONEX}&code={종목코드}&bas_dd={YYYYMMDD}
+```
+
+## Example requests
+
+종목 검색:
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-stock/search' \
+  --data-urlencode 'q=삼성전자' \
+  --data-urlencode 'bas_dd=20260408'
+```
+
+종목 기본정보:
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-stock/base-info' \
+  --data-urlencode 'market=KOSPI' \
+  --data-urlencode 'code=005930' \
+  --data-urlencode 'bas_dd=20260408'
+```
+
+종목 일별 시세:
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-stock/trade-info' \
+  --data-urlencode 'market=KOSPI' \
+  --data-urlencode 'code=005930' \
+  --data-urlencode 'bas_dd=20260408'
+```
+
+## Response shape
+
+### 검색 응답
+
+```json
+{
+  "items": [
+    {
+      "market": "KOSPI",
+      "code": "005930",
+      "standard_code": "KR7005930003",
+      "name": "삼성전자",
+      "short_name": "삼성전자",
+      "english_name": "Samsung Electronics",
+      "listed_at": "1975-06-11"
+    }
+  ],
+  "query": { "q": "삼성전자", "bas_dd": "20260408", "limit": 10 },
+  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
+}
+```
+
+### 기본정보 응답
+
+```json
+{
+  "item": {
+    "market": "KOSPI",
+    "code": "005930",
+    "standard_code": "KR7005930003",
+    "name": "삼성전자",
+    "short_name": "삼성전자",
+    "english_name": "Samsung Electronics",
+    "security_group": "주권",
+    "section_type": "대형주",
+    "stock_certificate_type": "보통주",
+    "par_value": 100,
+    "listed_shares": 5969782550
+  },
+  "query": { "market": "KOSPI", "code": "005930", "bas_dd": "20260408" },
+  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
+}
+```
+
+### 일별 시세 응답
+
+```json
+{
+  "item": {
+    "market": "KOSPI",
+    "code": "005930",
+    "standard_code": "KR7005930003",
+    "base_date": "20260408",
+    "name": "삼성전자",
+    "close_price": 84000,
+    "change_price": 1000,
+    "fluctuation_rate": 1.2,
+    "open_price": 83000,
+    "high_price": 84500,
+    "low_price": 82800,
+    "trading_volume": 12345678,
+    "trading_value": 1030000000000,
+    "market_cap": 500000000000000
+  },
+  "query": { "market": "KOSPI", "code": "005930", "bas_dd": "20260408" },
+  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
+}
+```
+
+## Response policy
+
+- 종목명이 모호하면 먼저 `search` 로 시장/종목코드를 좁힌 뒤 `base-info` 또는 `trade-info` 로 들어간다.
+- 일부 시장 upstream 이 실패하면 `upstream.degraded=true` 와 `failed_markets` 를 보고 부분 장애 여부를 함께 설명한다.
+- `trade-info` 결과는 일별 snapshot 이다. 실시간 호가/체결처럼 말하지 않는다.
+- 휴장일/장마감 이전이면 해당 `bas_dd` 에 데이터가 없을 수 있으니 최근 영업일로 재시도한다. 이 경우 `trade-info` 는 502 대신 `not_found` 로 끝날 수 있다.
+- 숫자는 사람이 읽기 쉬운 단위(원, 주, 억/조)로 짧게 풀어주되 원본 숫자도 유지한다.
+- 답변 말미에 "KRX 공식 데이터 기준 / 투자 조언 아님" 을 짧게 남긴다.
+
+## Keep the answer compact
+
+- 종목명 / 시장 / 종목코드
+- 기준일
+- 종가 / 등락률 / 거래량 / 시가총액
+- 필요할 때만 상장일 / 상장주식수 / 액면가
+- 여러 후보가 나오면 상위 3~5개만 보여주고 사용자가 고르게 한다
+
+## Failure modes
+
+- `q`, `market`, `code`, `bas_dd` 형식이 잘못되면 400 응답
+- 프록시 서버에 `KRX_API_KEY` 가 없으면 503 응답
+- 검색 중 일부 시장 upstream 이 실패하면 200 응답이지만 `upstream.degraded=true` 와 `failed_markets` 를 함께 반환할 수 있다.
+- 모든 요청 시장에서 upstream KRX 조회가 실패하면 502 응답
+- 해당 기준일/시장에 종목이 없으면 404 `not_found`
+
+## Done when
+
+- 검색어가 모호하면 `search` 로 후보를 먼저 좁혔다.
+- 필요한 경우 `base-info` 와 `trade-info` 를 호출해 핵심 수치를 정리했다.
+- 사용자가 `KRX_API_KEY` 없이도 조회 가능하다는 점을 유지했다.
+- KRX 공식 데이터 기준임을 짧게 남겼다.
+
+## Notes
+
+- 원본 참고: `https://github.com/jjlabsio/korea-stock-mcp`
+- 공식 데이터 출처: KRX Open API (`https://openapi.krx.co.kr/contents/OPP/MAIN/main/index.cmd`)
+- 이 스킬은 read-only 조회 전용이다.

package/skills/korean-stock-search/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "korean-stock-search",
+  "description": "Use k-skill-proxy to search Korean listed stocks, inspect KRX base information, and fetch daily trade snapshots without asking the user to issue a KRX API key.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: korean-stock-search\ndescription: Use k-skill-proxy to search Korean listed stocks, inspect KRX base information, and fetch daily trade snapshots without asking the user to issue a KRX API key.\nlicense: MIT\nmetadata:\n  category: finance\n  locale: ko-KR\n  phase: v1"
+}

package/skills/korean-transit-route/instruction.md

@@ -0,0 +1,113 @@
+# korean-transit-route
+
+## When to use
+
+- "강남에서 잠실 지하철로 어떻게 가?"
+- "서울역 → 인천공항 대중교통 경로"
+- "환승 가장 적은 경로", "최소 시간 경로"
+
+## Credentials
+
+- 환경변수 `ODSAY_API_KEY` 가 있으면 사용. 없으면 `~/.config/k-skill/secrets.env` 에서 로드.
+- ODsay Server 키는 호출 IP 화이트리스트 등록 필수. 발급은 https://lab.odsay.com
+- Kakao Local geocoding은 기본 hosted `k-skill-proxy` 경유로 호출하므로 사용자 쪽 `KAKAO_REST_API_KEY` 는 불필요하다. self-host proxy 운영자만 `KAKAO_REST_API_KEY` 를 서버에 설정한다.
+
+## Inputs
+
+자연어 입력에서 출발/도착을 추출. 좌표가 없으면 **반드시 geocoding 먼저** (ODsay는 좌표만 받음).
+
+### Geocoding (필수 선행 단계)
+
+기본 hosted proxy를 사용한다. Proxy가 Kakao Local REST API 키를 서버에서만 주입하고, caller `apiKey` 는 무시한다.
+
+1. `https://k-skill-proxy.nomadamas.org/v1/kakao-local/geocode?q=<주소/장소명>`
+2. proxy 내부 fallback: Kakao Local `address.json` → 결과 없으면 `keyword.json`
+
+응답 `documents[0].x`(경도), `.y`(위도) 사용.
+
+```python
+import os, urllib.parse, urllib.request, json
+PROXY=os.environ.get('KSKILL_PROXY_BASE_URL','https://k-skill-proxy.nomadamas.org').rstrip('/')
+def geocode(q):
+    url=PROXY+'/v1/kakao-local/geocode?q='+urllib.parse.quote(q)
+    with urllib.request.urlopen(url,timeout=10) as resp:
+        d=json.loads(resp.read())
+    if d.get('documents'):
+        doc=d['documents'][0]
+        return float(doc['x']), float(doc['y']), doc.get('place_name') or doc.get('address_name')
+    return None
+```
+
+지하철역명만 정확히 알 때는 ODsay `searchStation` 도 OK 하지만, 도어투도어 결과를 원하면 **실제 출발지/도착지 좌표**를 써야 첫/끝 도보 구간이 계산됨.
+
+## Core call
+
+```bash
+set -a; . ~/.config/k-skill/secrets.env; set +a
+KEY=$(python3 -c "import os,urllib.parse;print(urllib.parse.quote(os.environ['ODSAY_API_KEY'],safe=''))")
+curl -s "https://api.odsay.com/v1/api/searchPubTransPathT?apiKey=${KEY}&SX=${SX}&SY=${SY}&EX=${EX}&EY=${EY}&OPT=0&SearchPathType=${TYPE}"
+```
+
+Parameters:
+- `SX,SY` 출발 경도/위도, `EX,EY` 도착 경도/위도 (WGS84)
+- `OPT`: `0` 추천순(기본), `4` 최소시간, `5` 최소환승
+- `SearchPathType`: `0` 지하철+버스, `1` 지하철만, `2` 버스만
+
+## Response shape
+
+`result.path[]` 배열, 각 path:
+- `pathType`: 1=지하철, 2=버스, 3=지하철+버스
+- `info.totalTime`(분), `info.payment`(원), `info.subwayTransitCount`, `info.busTransitCount`, `info.totalWalk`(m), `info.firstStartStation`, `info.lastEndStation`
+- `subPath[]`: 구간별. `trafficType` 1=지하철 2=버스 3=도보. 지하철이면 `lane[0].name`, `startName`, `endName`, `passStopList.stations[]`(경유역)
+
+## Recommended output (door-to-door)
+
+`subPath` 의 각 구간을 `trafficType` 별로 표시. 첫/끝 도보 구간은 출발지·도착지에서 역까지 실제 도보를 의미하므로 **반드시 포함**.
+
+```
+🚇 범안로95번길 32 → SKT타워
+경로 1: 54분 · 1,950원 · 환승 2회 · 도보 688m
+  🚶 도보 1분
+  🚌 19번 부천범박힐스테이트 → 역곡역 (9분)
+  🚶 도보 2분
+  🚇 1호선 역곡 → 종각 (15정거장, 35분)
+  🚶 도보 7분
+```
+
+3개 이내 경로 비교 권장. `OPT=4`(최소시간) / `OPT=5`(최소환승) 옵션을 사용자가 선호 표시하면 그쪽으로 호출.
+
+## Done when
+
+- 출발지와 도착지가 geocoding 되었거나, 좌표/역명이 명확히 확인되었다.
+- ODsay 응답에서 1개 이상 경로가 정리되었다.
+- 각 경로의 총 소요시간, 요금, 환승 횟수, 총 도보 거리가 포함되었다.
+- 첫/끝 도보 구간이 포함된 door-to-door 요약을 보여줬다.
+- upstream API 키가 응답에 노출되지 않았다.
+
+## Helpers
+
+좌표 모르고 역명만 아는 경우 — `searchStation` 으로 변환:
+
+```bash
+curl -s "https://api.odsay.com/v1/api/searchStation?apiKey=${KEY}&stationName=강남&CID=1000"
+```
+
+`CID=1000` = 수도권. 결과 `result.station[].x,y` 가 좌표.
+
+## Limits
+
+- 현재 ODsay 공식 Basic 상품 기준 무료 체험은 일 1,000건(6개월)이다. `searchPubTransPathT` + `searchStation` 호출이 합산되니 한 질문당 호출 최소화.
+- 응답에 `error` 키 있으면 즉시 사용자에게 표시(ApiKey/IP 문제 진단에 유용).
+- 한국 외 좌표는 지원 안 함.
+
+## Failure modes
+
+- ODsay `error` 응답: `msg` 필드를 그대로 사용자에게 표시하고, ApiKey 미등록 또는 IP 화이트리스트 누락 가능성을 안내한다.
+- Kakao geocoding 결과 없음: 주소/장소명을 다시 확인하거나 더 구체적인 표현을 요청한다.
+- 좌표는 있으나 ODsay 경로 없음: 대중교통 미개통 지역, 도보 가능 거리, 또는 해상/공항 구간일 수 있다. 사용자에게 확인한다.
+- quota 초과: 일일 한도 도달 시 추가 호출을 중단하고 사용자에게 알린다.
+
+## Don'ts
+
+- 카카오맵/네이버지도 directions API로 대중교통 라우팅 시도하지 말 것 (둘 다 운전·도보만 공개).
+- 키를 절대 응답에 노출하지 말 것.

package/skills/korean-transit-route/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "korean-transit-route",
+  "description": "Korean door-to-door public transit routing (subway + bus + walking) via ODsay LIVE API with Kakao geocoding for address-to-address queries. Use when the user asks for 지하철/버스/대중교통 길찾기, 환승 경로, 소요시간, or transit directions between two places in Korea.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: korean-transit-route\ndescription: Korean door-to-door public transit routing (subway + bus + walking) via ODsay LIVE API with Kakao geocoding for address-to-address queries. Use when the user asks for 지하철/버스/대중교통 길찾기, 환승 경로, 소요시간, or transit directions between two places in Korea.\nlicense: MIT\nmetadata:\n  category: transit\n  locale: ko-KR\n  phase: v1"
+}

package/skills/kosis-stats/instruction.md

@@ -0,0 +1,232 @@
+# KOSIS Stats
+
+## What this skill does
+
+국가데이터처(구 통계청)가 운영하는 KOSIS(국가통계포털) Open API `https://kosis.kr/openapi/` 로 한국 공식 통계 자료를 조회 자동화한다.
+
+이 스킬은 **조회 전용**이다. 통계 작성, 데이터 변경, 대시보드 등록, 사용자별 통계 자료 등록은 범위에 포함하지 않는다.
+
+지원 endpoint:
+
+- `statisticsSearch.do` — 키워드로 통계표 검색
+- `statisticsData.do?method=getMeta` — 통계표 메타데이터 (분류·항목·단위)
+- `statisticsParameterData.do` — 통계표 데이터 셀 조회 (기간/분류 필터)
+- `statisticsBigData.do` — 대용량 자료 (사전 등록한 `userStatsId` 필요)
+- `statisticsList.do` — 통계목록 카테고리 트리 탐색 (주제별/기관별/국제통계/북한통계 등)
+- `statisticsExplData.do` — 통계설명 (조사목적·주기·대상·법적근거·공표방법 등 27개 항목)
+- `pkNumberService.do` — 통계주요지표 (1,473개 핵심 지표의 개념·산정방법·출처)
+
+## When to use
+
+- "1인 가구 비율 통계 찾아줘"
+- "KOSIS에서 고령인구 비율 시도별 데이터 가져와"
+- "DT_1IN0001 표 메타데이터 보여줘"
+- "최근 5년치 소비자물가지수 KOSIS에서 뽑아줘"
+- "국내통계 주제별로 어떤 카테고리가 있어?" (`list`)
+- "인구총조사 조사목적·조사주기 알려줘" (`explain`)
+- "인구밀도 지표 산정방법 보여줘" (`indicator`)
+
+## When not to use
+
+- 실시간 시세나 거래소 데이터를 원하는 경우 (KOSIS는 공식 통계용)
+- 데이터 시각화·분석·보고서 작성이 주 목적인 경우 (이 스킬은 raw 데이터 조회만)
+- 통계 작성·등록·수정이 필요한 경우
+- 대용량 자료를 받기 위해 사용자별 자료(`userStatsId`)를 새로 등록해야 하는 경우 (KOSIS 웹에서 직접 등록)
+
+## Prerequisites
+
+- Python 3.9+ (stdlib only, 외부 패키지 없음)
+- 일반 `search`/`meta`/`data`/`list`/`explain`/`indicator`: `k-skill-proxy`의 KOSIS route가 있는 hosted/self-host 프록시에 접근 가능할 것
+- `bigdata` 또는 `--direct`: KOSIS Open API 인증키 (무료, https://kosis.kr/openapi/ 에서 회원가입 후 활용신청)
+
+```bash
+python3 kosis-stats/scripts/run_kosis_stats.py --help
+```
+
+### Supporting files (단일 SKILL.md 설치 복구)
+
+이 스킬은 `SKILL.md` 외에 helper(`scripts/run_kosis_stats.py`)와 레퍼런스 문서(`references/kosis-openapi-guide.md`)에 의존하는 **디렉터리 패키지형 스킬**이다. raw `SKILL.md` URL만 받는 설치 도구(Hermes 등)로 설치하면 `scripts/`·`references/`가 누락되어 helper 실행이 실패한다.
+
+helper 실행 전에 파일 존재를 확인하고, 없으면 아래로 복구한다. `<skill-dir>`은 이 `SKILL.md`가 설치된 디렉터리다.
+
+```bash
+skill_dir="<skill-dir>"   # 예: ~/.hermes/skills/kosis-stats, ~/.claude/skills/kosis-stats
+if [ ! -f "$skill_dir/scripts/run_kosis_stats.py" ]; then
+  mkdir -p "$skill_dir/scripts" "$skill_dir/references"
+  curl -fsSL https://raw.githubusercontent.com/NomaDamas/k-skill/main/kosis-stats/scripts/run_kosis_stats.py \
+    -o "$skill_dir/scripts/run_kosis_stats.py"
+  curl -fsSL https://raw.githubusercontent.com/NomaDamas/k-skill/main/kosis-stats/references/kosis-openapi-guide.md \
+    -o "$skill_dir/references/kosis-openapi-guide.md"
+fi
+python3 "$skill_dir/scripts/run_kosis_stats.py" --help
+```
+
+근본적으로는 디렉터리 단위로 설치하는 방식(`npx --yes skills add NomaDamas/k-skill --skill kosis-stats -g` 또는 repo clone)을 권장한다.
+
+## Required environment variables
+
+- 일반 `search`/`meta`/`data`/`list`/`explain`/`indicator`: 없음. 기본 hosted `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+- `KSKILL_PROXY_BASE_URL` — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted proxy를 사용한다.
+- `KSKILL_KOSIS_API_KEY` — `bigdata` 또는 `--direct`로 KOSIS를 직접 호출할 때만 필요하다.
+
+발급 절차와 호출 한도, 에러 코드 등 자세한 내용은 [`references/kosis-openapi-guide.md`](references/kosis-openapi-guide.md) 참고.
+
+### Credential resolution order (`bigdata` 또는 `--direct` 전용)
+
+1. 돌쇠 credential mode에서는 provisioned `vault-run` capability를 사용하고, 없으면 `request_vault_credential`로 KOSIS API key 입력 UI를 호출한다.
+2. 그 밖의 환경에서는 이미 주입된 환경변수 → host vault → `~/.config/k-skill/secrets.env` (`0600`) 순서로 사용한다.
+3. generic fallback에서 값이 없으면 호스트의 가장 안전한 입력 표면으로 받아 vault 또는 dotenv에 저장한다.
+
+일반 조회 helper는 proxy URL만 읽고, KOSIS 인증키는 proxy 서버에서만 주입한다. `bigdata`/`--direct` 호출만 `KSKILL_KOSIS_API_KEY` 환경변수와 위 secrets 파일을 읽는다.
+`list`/`explain`/`indicator`는 `search`/`meta`/`data`와 마찬가지로 proxy 경유로 동작한다.
+
+## Inputs
+
+서브커맨드: `search`, `meta`, `data`, `bigdata`, `list`, `explain`, `indicator`.
+
+공통 옵션:
+
+- `--text`: 사람용 요약
+- `--json`: 구조화 결과 (기본값)
+- `--dry-run`: 인증키 없이 요청 URL/파라미터만 출력
+- `--timeout N`: HTTP 타임아웃 초 단위 (기본 30)
+- `--proxy-base-url URL`: 기본 hosted proxy 대신 self-host/alternate proxy 사용
+- `--direct`: proxy를 우회하고 `KSKILL_KOSIS_API_KEY` 로 KOSIS 직접 호출
+
+서브커맨드별 입력:
+
+- `search`
+  - `--query "키워드"`
+  - `--result-count N` (1-5000, 기본 20)
+  - `--start-count N` (페이징 시작, 기본 1)
+- `meta`
+  - `--org-id 101` (기본 101=통계청)
+  - `--table-id DT_1IN0001`
+  - `--meta-type TBL|ITM|OBJ` (기본 TBL)
+- `data`
+  - `--org-id 101`
+  - `--table-id DT_1IN0001`
+  - `--prd-se M|Q|S|Y|F|IR` (수록 주기)
+  - `--start YYYY[MM|QQ|HH]`, `--end YYYY[MM|QQ|HH]`
+  - `--itm-id ALL` (항목 ID, 기본 ALL)
+  - `--obj-l 1=ALL --obj-l 2=00` (분류 필터, 반복 가능)
+- `bigdata`
+  - `--user-stats-id <KOSIS 등록 ID>`
+  - `--format json|sdmx|csv` (xls는 바이너리라 helper 미지원 — 필요 시 KOSIS 웹에서 직접 다운로드)
+  - `--prd-se`, `--new-est-prd-cnt` (선택)
+- `list`
+  - `--vw-cd MT_ZTITLE|MT_OTITLE|MT_GTITLE01|MT_GTITLE02|MT_CHOSUN_TITLE|MT_HANKUK_TITLE|MT_STOP_TITLE|MT_RTITLE|MT_BUKHAN|MT_TM1_TITLE|MT_TM2_TITLE|MT_ETITLE` (필수)
+  - `--parent-id <LIST_ID>` (하위 카테고리 탐색, 기본 빈 문자열=최상위)
+- `explain`
+  - `--stat-id <통계조사ID>` (단독) 또는 `--org-id 101 --table-id DT_1IN0001` (조합, 둘 중 하나 필수)
+  - `--meta-itm All|statsNm|statsKind|...` (기본 All, 한 번에 단일 필드 또는 All)
+- `indicator`
+  - `--jipyo-id 160` (필수, 지표ID)
+  - `--service 1|2|3` (기본 1: 1=개념, 2=산정방법·출처, 3=전체설명)
+  - `--page-no N`, `--num-of-rows N` (페이징)
+
+## Workflow
+
+### 1. Ensure proxy access is available
+
+일반 `search`/`meta`/`data` 는 기본 hosted `k-skill-proxy`를 사용하므로 사용자 KOSIS 키가 필요 없다. self-host를 쓰면 `KSKILL_PROXY_BASE_URL`을 설정한다.
+
+`bigdata` 또는 `--direct`가 필요할 때만 `KSKILL_KOSIS_API_KEY` 를 credential resolution order에 따라 확보한다. 시크릿이 없다는 이유로 다른 통계 사이트나 비공식 경로를 찾지 않는다.
+
+### 2. Search for candidate tables
+
+질문을 먼저 한국어 키워드로 좁히고 `search` 로 후보 통계표를 본다.
+
+```bash
+python3 kosis-stats/scripts/run_kosis_stats.py search --query "1인 가구" --text
+```
+
+출력에서 `[ORG_ID/TBL_ID]`를 골라 다음 단계에 사용한다.
+
+### 3. Inspect the table meta before fetching data
+
+데이터를 받기 전에 분류/단위/주기를 확인한다.
+
+```bash
+python3 kosis-stats/scripts/run_kosis_stats.py meta --table-id DT_1JC1501 --text
+```
+
+### 4. Fetch a small bounded slice first
+
+`--prd-se`, `--start`, `--end`, `--obj-l` 으로 범위를 좁혀 작은 슬라이스를 먼저 조회한다.
+
+```bash
+python3 kosis-stats/scripts/run_kosis_stats.py data \
+  --table-id DT_1JC1501 --prd-se Y --start 2020 --end 2022 \
+  --obj-l 1=ALL --json
+```
+
+표마다 필수 분류 차원 수가 다르다. **default `--obj-l 1=ALL` 만으로는 부족한 표가 많다.** KOSIS가 코드 `20` (필수요청변수값 누락 objL)을 돌려주면, `meta --table-id <ID> --meta-type ITM --json` 으로 ITM 안에 들어 있는 `OBJ_ID`(분류 차원)와 코드를 확인한 뒤 `--obj-l 1=<코드> --obj-l 2=<코드>` 형태로 필요한 차원을 모두 지정한다. (많은 표가 OBJ 메타는 비어 있고 분류가 ITM 안에 들어 있음.)
+
+40,000셀을 초과하면 KOSIS는 에러 코드 `31` 또는 `41` 을 반환한다. 기간을 좁히거나(예: 5년→1년) 분류 필터의 ALL 을 특정 코드로 바꿔(예: `--obj-l 1=11` 서울만) 호출을 분할한다. 그래도 부족하면 사용자별 통계자료(`userStatsId`)를 등록해 `bigdata` 서브커맨드를 사용한다.
+
+행정구역 코드 관례: `C1` 코드는 보통 시도가 2자리(`11` 서울, `26` 부산 등), 시군구가 5자리다. `data --json` 응답의 `C1` 필드를 확인해 원하는 단위만 후속 처리에서 필터한다.
+
+### 5. (Optional) Use bigdata for large datasets
+
+`bigdata` 는 KOSIS 웹에서 미리 등록한 `userStatsId` 가 필요하다. 미등록 상태면 사용자에게 등록 안내만 하고 멈춘다.
+
+```bash
+python3 kosis-stats/scripts/run_kosis_stats.py bigdata \
+  --user-stats-id "openapisample/101/DT_1IN1502/2/1/20191106094026_1" \
+  --format json --new-est-prd-cnt 5
+```
+
+### 6. Cite the source
+
+응답을 요약할 때는 `org_id`, `tbl_id`, 기간, 단위(`UNIT_NM`), 그리고 endpoint URL을 함께 적는다.
+
+## Done when
+
+- 사용자 질문에 대응하는 통계표 ID(`org_id`/`tbl_id`)가 명확하다.
+- 메타데이터를 1회 이상 조회해 분류·단위·주기를 확인했다.
+- 작은 슬라이스부터 단계적으로 데이터를 받았다.
+- 결과에 출처(table id, 기간, 단위, endpoint)를 명시했다.
+- 한도 초과 시 분할 또는 `bigdata` 안내로 처리했다.
+
+## Failure modes
+
+- `KSKILL_KOSIS_API_KEY` 누락: `bigdata` 또는 `--direct` 호출에서만 발급 안내 메시지와 함께 종료(exit 1)
+- KOSIS 에러 코드 `10`/`11`: 인증키 누락/만료 → 키 점검. `bigdata` 에서 `11` 이 나오면 `userStatsId` 가 본인 KOSIS 계정에 등록된 것이 아닐 가능성이 크다.
+- 코드 `20`: 필수 분류 누락 → `meta --meta-type OBJ` (또는 비어 있으면 `ITM`) 으로 필요한 차원 수와 코드를 확인하고 `--obj-l 1=... --obj-l 2=...` 모두 지정 후 재시도
+- 코드 `21`: 잘못된 요청 변수 → `org_id`/`tbl_id`/기간 형식 재확인. tblId 의심 시 `search` 로 정확한 ID 다시 찾기
+- 코드 `30`: 결과 없음 → 키워드를 더 짧게 또는 다른 표현으로 바꾸거나 기간/분류 완화. **meta 호출에서 30 이 나오면** 표가 해당 메타 타입을 지원하지 않는 경우이므로 다른 `--meta-type` 시도
+- 코드 `31`/`41`: 한도 초과 → 기간 좁히기, 분류 ALL 을 특정 코드로 바꾸기, 또는 `bigdata` 사용
+- 코드 `40`: 분당 1,000건 호출 한도 → 잠시 대기
+- 코드 `50`: KOSIS 서버 오류 → 1~2초 후 재시도
+- 비표준 JSON: KOSIS는 따옴표 없는 키를 가끔 반환한다. helper는 자동 보정한다.
+- 응답에 `UNIT_NM` 누락: 일부 표는 KOSIS 응답에 단위가 비어 있다. helper text 출력의 `[summary]` 라인에 `unit=(KOSIS 응답에 UNIT_NM 미포함)` 으로 명시되며, 단위는 `meta` 응답이나 KOSIS 웹 화면에서 별도 확인한다.
+- HTTPS 전용 (2026-03-05 이후): URL은 항상 `https://`. HTTP 요청은 차단된다.
+
+### 회복 시나리오 예시
+
+- 코드 20 회복: `data --table-id DT_1J22001 --prd-se M --start 202401 --end 202401` → 코드 20 → `meta --table-id DT_1J22001 --meta-type ITM --json` 으로 차원 확인 → `data ... --obj-l 1=T10 --obj-l 2=0` 재호출 → 성공
+- 코드 31 회복: `data --table-id DT_1B26001 --prd-se Y --start 2020 --end 2024 --obj-l 1=ALL --obj-l 2=ALL --obj-l 3=ALL` → 코드 31 → `... --start 2024 --end 2024 --obj-l 1=11 --obj-l 2=ALL --obj-l 3=ALL` (서울만) 재호출 → 성공
+
+## Maintainer review notes
+
+메인테이너가 이 스킬을 검토하기 위해 KOSIS 인증키를 새로 발급받을 필요는 없다.
+일반 조회는 `k-skill-proxy`가 KOSIS 인증키를 서버 쪽에서 주입한다. `bigdata` 와 `--direct`만 개인 KOSIS 키가 필요하다.
+
+키 없이 가능한 검증:
+
+- `./scripts/validate-skills.sh`
+- `python3 -m py_compile kosis-stats/scripts/run_kosis_stats.py kosis-stats/tests/test_run_kosis_stats.py`
+- `python3 kosis-stats/scripts/run_kosis_stats.py --help`
+- `python3 kosis-stats/scripts/run_kosis_stats.py search --query 인구 --dry-run` (URL/파라미터 출력만)
+- `PYTHONPATH=kosis-stats/scripts python3 -m unittest discover -s kosis-stats/tests -p 'test_*.py' -v`
+- `npm run ci`
+
+실제 direct live smoke는 기여자 또는 이미 KOSIS 키가 있는 사용자가 선택적으로 수행한다. Proxy live smoke는 배포 proxy에 `KOSIS_API_KEY`가 설정된 뒤 수행한다. PR에는 호출 endpoint, 파라미터, 응답 행 수 같은 비민감 요약만 남기고 인증키와 개인 조회 세부 내역은 공유하지 않는다.
+
+## Safety notes
+
+- 조회 전용 스킬이다.
+- 사용자별 통계자료(`userStatsId`) 등록, 데이터 수정, KOSIS 웹 자동화는 하지 않는다.
+- 일반 조회 인증키는 proxy 서버에서만 다룬다. direct/bigdata 인증키는 환경변수 또는 `~/.config/k-skill/secrets.env` 로만 다룬다.
+- 응답 JSON에 인증키가 echo 되지 않도록 helper는 `--dry-run` 시에도 키를 `<DRY-RUN>` 으로 대체한다.