@nomadamas/k-skill 0.2.3 → 0.2.5

package/package.json

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

package/skills/k-skill-cleaner/instruction.md

@@ -36,7 +36,7 @@ npx -y @nomadamas/k-skill@0 exec k-skill-cleaner scripts/k_skill_cleaner.py -- \
   --skills-root . \
   --scan-default-logs \
   --days 90 \
-  --never-use blue-ribbon-nearby,lotto-results \
+  --never-use lotto-results,market-kurly-search \
   --keep k-skill-setup,k-skill-cleaner
 ```
 

package/skills/k-skill-setup/instruction.md

@@ -2,184 +2,164 @@
 
 ## Purpose
 
-전체 `k-skill` 설치가 끝난 뒤, 공통 후속 작업을 처리한다.
+`k-skill` 스킬 설치부터 CLI 런타임, credential, 환경 검증까지 한 번에 정리한다.
+이미 설치된 항목은 확인만 하고 건너뛴다.
 
-- credential 확보 (에이전트 vault 또는 기본 secrets.env)
-- 런타임 환경변수 확인
-- 선택 사항: 주기적인 업데이트 확인 자동화
-- 선택 사항: GitHub star 여부 확인 및 동의 시 실행
+기본 원칙:
 
-이 스킬의 기본 정책:
+- Node.js 18 이상과 `npx`를 사용한다.
+- credential은 환경변수, agent vault, `~/.config/k-skill/secrets.env` 순으로 확인한다.
+- Dolshoi credential mode에서는 평문 credential을 요청하거나 파일에 직접 저장하지 않는다.
+- 설치, 예약 작업, GitHub star처럼 외부 상태를 바꾸는 작업은 실행 전에 동의를 받는다.
+- 사용자가 승인한 범위만 실행하고 별도 helper, 요약, AI/CLI 예약 작업을 추가하지 않는다.
 
-- 시크릿이 없으면 필요한 값 이름을 사용자에게 정확히 알려준다
-- credential resolution order에 따라 확보한다
-- 필요한 패키지가 없으면 대체 구현을 찾기보다 전역 설치를 먼저 시도한다
-- `cron`, `launchd`, `schtasks`, `gh` 같은 지속성/외부 상태 변경은 자동으로 하지 말고 먼저 사용자 동의를 받는다
-- GitHub star는 사용자가 명시적으로 동의했을 때만 실행한다
+## 1. Install the skills
 
-## Dolshoi-first runtime policy
+일반적인 Claude Code, Codex, OpenCode, OpenClaw 등에서는 `skills` CLI로 전체 스킬을
+전역 설치하는 경로를 권장한다.
 
-돌쇠는 credential, browser, action을 서로 독립적인 capability로 감지한다.
-
-1. `DOLSHOI_ACTION_BROKER_URL`과 실행 가능한 `vault-run`이 모두 있으면 credential action mode다.
-2. 필요한 login capability가 이미 provision되어 있으면 `vault-run <capability_id> <action> [args...]`를 사용한다.
-3. capability가 없으면 username/password/key를 채팅으로 묻지 말고 `request_vault_credential` tool로 앱 vault 입력 UI를 호출한다.
-4. 내장 browser tool이 CloakBrowser를 제공하거나 `CLOAKBROWSER_PEEK_TOKEN`이 있으면 browser action은 CloakBrowser를 우선한다.
-5. 조회 결과가 실제 action의 입력이면 공식 표면에서 장바구니, 예약, 신청서 작성, 연락 초안 등 가역적 단계를 이어서 수행한다.
-6. 결제, 실제 메시지/메일 전송, 최종 제출, 취소 같은 비가역 효과 직전에만 `clarify`로 대상·금액/payload·효과를 승인받고, 승인되면 같은 turn에 실행한다.
+```bash
+npx --yes skills add NomaDamas/k-skill --all -g
+```
 
-## Generic credential resolution order
+목록을 먼저 보거나 일부 스킬만 설치하려면:
 
-돌쇠 credential mode가 아닐 때만 아래 portable fallback을 따른다.
+```bash
+npx --yes skills add NomaDamas/k-skill --list
+npx --yes skills add NomaDamas/k-skill --skill <skill-name> -g
+```
 
-1. **이미 환경변수에 있으면** 그대로 사용한다.
-2. **에이전트가 자체 secret vault(1Password CLI, Bitwarden CLI, macOS Keychain 등)를 사용 중이면** 거기서 꺼내 환경변수로 주입해도 된다.
-3. **`~/.config/k-skill/secrets.env`** (기본 fallback) — plain dotenv 파일, 퍼미션 `0600`.
-4. **아무것도 없으면** 유저에게 물어서 2 또는 3에 저장한다.
+Claude Code에서는 marketplace plugin으로 전체 번들을 설치하는 경로도 지원한다.
+Claude Code 안에서 다음 명령을 실행한다.
 
-기본 경로에 저장하는 것은 fallback일 뿐, 강제가 아니다.
+```text
+/plugin marketplace add NomaDamas/k-skill
+/plugin install k-skill@k-skill
+```
 
-## Standard file location
+plugin으로 설치한 스킬은 `/k-skill:<스킬 이름>`으로 호출한다.
+예: `/k-skill:k-skill-setup`, `/k-skill:lotto-results`.
 
-- secrets file (기본 fallback): `~/.config/k-skill/secrets.env`
+두 설치 방식을 중복 실행할 필요는 없다. 현재 agent에서 스킬이 이미 보이면 설치를
+다시 하지 말고 다음 단계로 진행한다.
 
-## Install
+## 2. Use the k-skill CLI
 
-이 스킬은 `k-skill` 전체 스킬 설치가 끝난 뒤 실행하는 것을 기본으로 한다.
+설치되는 `SKILL.md`는 스킬 선택과 최소 안전 규칙을 담은 adapter다. 전체 instruction
+조립과 bundled `scripts/`, `references/` 접근은 `@nomadamas/k-skill` CLI가 담당한다.
 
-예:
+기본 경로는 `npx`이며 CLI를 별도로 설치할 필요는 없다.
 
 ```bash
-npx --yes skills add <owner/repo> --all -g
+npx -y @nomadamas/k-skill@0 instruct k-skill-setup
+npx -y @nomadamas/k-skill@0 list
 ```
 
-설치가 끝나면 이 스킬을 호출해 아래 setup 단계를 이어간다.
-
-## Setup steps
-
-### 1. Create the default secrets file (generic fallback only)
-
-돌쇠 credential mode나 다른 host vault를 쓰지 않는 경우에만 기본 fallback 파일을 만든다.
+반복 사용으로 전역 명령이 필요할 때만 선택적으로 설치한다.
 
 ```bash
-mkdir -p ~/.config/k-skill
-cat > ~/.config/k-skill/secrets.env <<'EOF'
-KSKILL_SRT_ID=replace-me
-KSKILL_SRT_PASSWORD=replace-me
-KSKILL_KTX_ID=replace-me
-KSKILL_KTX_PASSWORD=replace-me
-KSKILL_FORESTTRIP_ID=replace-me
-KSKILL_FORESTTRIP_PASSWORD=replace-me
-KSKILL_EV_CHARGER_API_KEY=replace-me
-KSKILL_BUILDING_REGISTER_API_KEY=replace-me
-KSKILL_RISS_API_KEY=replace-me
-LAW_OC=replace-me
-KIPRIS_PLUS_API_KEY=replace-me
-AIR_KOREA_OPEN_API_KEY=replace-me
-KSKILL_PROXY_BASE_URL=
-EOF
-chmod 0600 ~/.config/k-skill/secrets.env
+npm install -g @nomadamas/k-skill@0
+k-skill instruct k-skill-setup
 ```
 
-호스트가 제공하는 가장 안전한 입력 표면으로 실제 값을 받아 채운다. 돌쇠에서는 이 파일을 만들거나 평문 값을 묻지 않는다.
+bundled helper와 reference는 항상 CLI를 통해 사용한다.
 
-서울 지하철 도착정보, 서울 실시간 혼잡도 조회, 서울 따릉이 실시간 대여소 조회, 한국 날씨, 미세먼지, 한강 수위, 주유소 가격, 생활쓰레기 배출정보 조회, 학교 급식 식단 조회, 의약품 안전 체크, 식품 안전 체크는 `KSKILL_PROXY_BASE_URL` 을 비워 두면 기본 hosted path(`k-skill-proxy.nomadamas.org`)를 그대로 쓴다. 전기차 충전소와 건축물대장 표제부 조회도 같은 기본 hosted path를 쓴다. 별도 self-host proxy를 쓸 때만 `KSKILL_PROXY_BASE_URL` 을 채운다.
-
-한국 법령 검색은 기본 hosted proxy(`k-skill-proxy.nomadamas.org`)의 `/v1/korean-law/...` endpoint를 경유하므로 사용자 쪽 `LAW_OC` 가 불필요하다. self-host proxy 운영자만 서버 환경변수 `LAW_OC` 를 채운다(무료 발급: `https://open.law.go.kr`).
-
-한국 부동산 실거래가 조회는 기본 hosted proxy(`k-skill-proxy.nomadamas.org`)를 경유하므로 사용자 쪽 `DATA_GO_KR_API_KEY` 가 불필요하다.
+```bash
+npx -y @nomadamas/k-skill@0 exec <skill-name> scripts/<file> -- <args>
+npx -y @nomadamas/k-skill@0 read <skill-name> references/<file>
+```
 
-한국 주식 정보 조회는 기본 hosted proxy(`k-skill-proxy.nomadamas.org`)를 경유하므로 사용자 쪽 `KRX_API_KEY` 가 불필요하다. self-host proxy 운영자만 서버 환경변수 `KRX_API_KEY` 를 사용한다.
+설치된 스킬 디렉터리나 repository 상대 경로에서 helper를 직접 실행하지 않는다.
 
-도서관 도서 조회는 기본 hosted proxy(`k-skill-proxy.nomadamas.org`)를 경유하므로 사용자 쪽 `DATA4LIBRARY_AUTH_KEY` 가 불필요하다. self-host proxy 운영자만 서버 환경변수 `DATA4LIBRARY_AUTH_KEY` 를 사용한다.
+## 3. Resolve credentials
 
-생활쓰레기 배출정보 조회는 `k-skill-proxy`의 `/v1/household-waste/info` 라우트를 호출하고, `serviceKey`(`DATA_GO_KR_API_KEY`)는 proxy 서버에서 주입/관리하므로 사용자 쪽 `DATA_GO_KR_API_KEY` 가 불필요하다.
+각 스킬이 요구하는 값만 준비한다. 모든 credential을 미리 요구하지 않는다.
 
-학교 급식 식단 조회는 `k-skill-proxy`의 `/v1/neis/school-search`·`/v1/neis/school-meal`을 호출하고, `KEDU_INFO_KEY`는 프록시 서버에만 두므로 사용자 쪽에 둘 필요가 없다.
+credential resolution order:
 
-도서관 도서 조회는 `k-skill-proxy`의 `/v1/data4library/*` 라우트를 호출하고, `DATA4LIBRARY_AUTH_KEY`는 프록시 서버에만 두므로 사용자 쪽에 둘 필요가 없다.
+1. 현재 프로세스 환경변수
+2. agent가 제공하는 secret vault
+3. 기본 fallback `~/.config/k-skill/secrets.env`
+4. 필요한 값이 없으면 정확한 환경변수 이름과 발급처를 안내
 
-근처 가장 싼 주유소 찾기는 기본 hosted proxy를 경유하므로 사용자 쪽 `OPINET_API_KEY` 가 불필요하다.
+Dolshoi credential mode:
 
-의약품 안전 체크는 `k-skill-proxy`의 `/v1/mfds/drug-safety/lookup` 라우트를 호출하고, `DATA_GO_KR_API_KEY` 는 프록시 서버에서만 주입/관리하므로 사용자 쪽에 둘 필요가 없다.
+- `DOLSHOI_ACTION_BROKER_URL`과 usable `vault-run`이 모두 있을 때만 활성화한다.
+- plaintext credential을 묻거나 출력하거나 `secrets.env`를 만들지 않는다.
+- 필요한 credential이 없으면 `request_vault_credential`을 사용한다.
 
-식품 안전 체크는 `k-skill-proxy`의 `/v1/mfds/food-safety/search` 라우트를 호출하고, `DATA_GO_KR_API_KEY` 및 선택적 `FOODSAFETYKOREA_API_KEY` 는 프록시 서버에서만 주입/관리하므로 사용자 쪽에 둘 필요가 없다.
+Generic mode에서 fallback 파일이 필요하면:
 
-창업진흥원 K-Startup 조회는 `k-skill-proxy`의 `/v1/kstartup/*` 라우트를 호출하고, `ServiceKey`(`DATA_GO_KR_API_KEY`)는 프록시 서버에서만 주입/관리하므로 일반 조회는 사용자 쪽에 키가 필요 없다. `--direct` 호출을 쓸 때만 `KSKILL_KSTARTUP_API_KEY` 를 채운다.
+```bash
+mkdir -p ~/.config/k-skill
+touch ~/.config/k-skill/secrets.env
+chmod 0600 ~/.config/k-skill/secrets.env
+```
 
-전기차 충전소 조회는 `k-skill-proxy`의 `/v1/ev-charger/info`·`/v1/ev-charger/status`를 호출하므로 일반 사용자는 키가 필요 없다. `--direct`에서만 `KSKILL_EV_CHARGER_API_KEY` 또는 `DATA_GO_KR_API_KEY`를 사용하고, 데이터셋 `15076352` 활용신청은 별도로 해야 한다(자동승인).
+실제 값은 사용자가 이용 중인 가장 안전한 입력 표면으로 받는다. 대화에 평문 값을
+붙여 넣도록 요구하지 않는다.
 
-건축물대장 표제부 조회는 `k-skill-proxy`의 `/v1/building-register/title`을 호출하므로 일반 사용자는 키가 필요 없다. 주소 입력은 같은 proxy의 Kakao geocode를 먼저 사용한다. `--direct`에서만 `KSKILL_BUILDING_REGISTER_API_KEY` 또는 `DATA_GO_KR_API_KEY`를 사용하고 데이터셋 `15134735` 활용신청을 별도로 해야 한다(자동승인).
+`KSKILL_PROXY_BASE_URL`을 비워 두면 `k-skill-proxy` 기반 스킬은 기본 hosted endpoint를 사용한다.
+사용자가 직접 운영하는 proxy가 있을 때만 URL을 설정한다.
 
-KERIS/RISS 학술자료 검색은 RISS 검색 API가 기관 전용 키를 요구해 `k-skill-proxy`를 거치지 않는다. 사용자가 직접 발급받은 `KSKILL_RISS_API_KEY`(호환 `RISS_API_KEY`)를 설정해 상류를 호출한다. RISS 키는 비영리 기관/대학에만 발급되며 RISS 검색에는 `DATA_GO_KR_API_KEY`를 사용하지 않는다.
+```bash
+KSKILL_PROXY_BASE_URL=
+# KSKILL_PROXY_BASE_URL=https://your-proxy.example.com
+```
 
-한국 특허 정보 검색은 KIPRIS Plus Open API 경로를 쓸 때 `KIPRIS_PLUS_API_KEY` 를 채운다. helper는 이 값을 읽어 실제 요청에서 `ServiceKey` 쿼리 파라미터로 보낸다. 공공데이터포털에서 복사한 percent-encoded key도 그대로 넣어도 된다.
+무료 hosted proxy로 처리되는 기능에는 사용자 upstream API key를 요구하지 않는다.
+로그인 기반 스킬은 해당 스킬의 공식 로그인/browser 절차를 따르며 credential을
+`secrets.env`에 복사하도록 요구하지 않는다.
 
-### Missing secret response template
+Hosted proxy 기본 계약:
 
-인증 스킬에서 값이 빠졌을 때는 credential resolution order에 따라 확보한다.
+- 미세먼지, 한강 수위, 주유소 가격, 생활쓰레기 배출정보 조회, 학교 급식 식단 조회, 의약품 안전 체크, 식품 안전 체크는 `KSKILL_PROXY_BASE_URL`을 비워 두면 기본 hosted endpoint를 사용한다.
+- 서울 지하철: 사용자 시크릿 불필요 (기본 hosted proxy 사용, 운영자만 `SEOUL_OPEN_API_KEY`).
+- 생활쓰레기 배출정보 조회: 사용자 시크릿 불필요. `/v1/household-waste/info`와 운영자 서버의 `DATA_GO_KR_API_KEY`를 사용한다.
+- 학교 급식 식단 조회: 사용자 시크릿 불필요. `/v1/neis/school-search`, `/v1/neis/school-meal`과 운영자 서버의 `KEDU_INFO_KEY`를 사용한다.
+- 한국 법령 검색은 기본 hosted proxy를 사용하며, 운영자만 서버 환경변수 `LAW_OC`를 설정한다.
+- 한국 특허 정보 검색: `KIPRIS_PLUS_API_KEY`는 운영자 서버에만 둔다.
+- 한국 주식 정보 조회는 proxy가 운영자 `KRX_API_KEY`를 사용하므로 사용자 키가 불필요하다.
+- 부동산 실거래가 조회와 주유소 가격 조회도 hosted proxy 기본 경로에서는 사용자 upstream key가 불필요하다.
 
-필요한 값 예:
+## 4. Verify the setup
 
-- SRT: `KSKILL_SRT_ID`, `KSKILL_SRT_PASSWORD`
-- KTX: `KSKILL_KTX_ID`, `KSKILL_KTX_PASSWORD`
-- 자연휴양림 빈 객실 조회: `KSKILL_FORESTTRIP_ID`, `KSKILL_FORESTTRIP_PASSWORD`
-- 한국 법령 검색: 사용자 시크릿 불필요 (기본 hosted proxy 사용, 운영자만 `LAW_OC`)
-- 한국 부동산 실거래가 조회: 사용자 시크릿 불필요 (기본 hosted proxy 사용)
-- 한국 특허 정보 검색: `KIPRIS_PLUS_API_KEY`
-- 한국 주식 정보 조회: 사용자 시크릿 불필요 (기본 hosted proxy 사용, 운영자만 `KRX_API_KEY`)
-- 생활쓰레기 배출정보 조회: 사용자 시크릿 불필요 (`serviceKey`는 proxy 서버 주입, 호출 시 `pageNo=1`·`numOfRows=100` 필수)
-- 학교 급식 식단 조회: 사용자 시크릿 불필요 (`KEDU_INFO_KEY`는 proxy 서버만)
-- 도서관 도서 조회: 사용자 시크릿 불필요 (`DATA4LIBRARY_AUTH_KEY`는 proxy 서버만)
-- 의약품 안전 체크: 사용자 시크릿 불필요 (`DATA_GO_KR_API_KEY`는 proxy 서버만)
-- 식품 안전 체크: 사용자 시크릿 불필요 (`DATA_GO_KR_API_KEY`와 선택적 `FOODSAFETYKOREA_API_KEY`는 proxy 서버만)
-- 창업진흥원 K-Startup 조회: 사용자 시크릿 불필요 (`DATA_GO_KR_API_KEY`는 proxy 서버만; `--direct` 호출 때만 `KSKILL_KSTARTUP_API_KEY`)
-- 전기차 충전소 위치·상태 조회: 사용자 시크릿 불필요 (hosted proxy 사용; `--direct` 때만 `KSKILL_EV_CHARGER_API_KEY` 또는 `DATA_GO_KR_API_KEY`)
-- 건축물대장 표제부 조회: 사용자 시크릿 불필요 (hosted proxy 사용; `--direct` 때만 `KSKILL_BUILDING_REGISTER_API_KEY` 또는 `DATA_GO_KR_API_KEY`)
-- KERIS/RISS 학술자료 검색: 사용자 본인 `KSKILL_RISS_API_KEY`(호환 `RISS_API_KEY`) 필요 (RISS 검색 API는 비영리 기관/대학 전용 키로 직접 호출, proxy 미사용)
-- 근처 가장 싼 주유소 찾기: 사용자 시크릿 불필요 (기본 hosted proxy 사용)
-- 서울 지하철: 사용자 시크릿 불필요 (기본 hosted proxy 사용, 운영자만 `SEOUL_OPEN_API_KEY`)
-- 서울 실시간 혼잡도: 사용자 시크릿 불필요 (기본 hosted proxy 사용, 운영자만 `SEOUL_OPEN_API_KEY`)
-- 한국 날씨: 사용자 시크릿 불필요 (기본 hosted proxy 사용, 운영자만 `KMA_OPEN_API_KEY`)
-- 사용자 위치 미세먼지 조회: `KSKILL_PROXY_BASE_URL` 또는 `AIR_KOREA_OPEN_API_KEY`
+bundled 검증 helper를 CLI로 실행한다.
 
-시크릿이 비어 있다는 이유로 다른 서비스나 비공식 우회 경로를 자동 선택하지 않는다.
+```bash
+npx -y @nomadamas/k-skill@0 exec k-skill-setup scripts/check-setup.sh --
+```
 
-### 2. Verify runtime environment
+Generic mode에서 `secrets.env`가 필요하지 않은 구성이라면 파일 부재 자체를 전체 설치
+실패로 단정하지 않는다. 실제 사용할 스킬의 필수 환경변수와 CLI 실행 가능 여부를 함께
+확인한다.
 
-이 스킬은 `SKILL.md` 단일 파일로 설치될 수 있으므로 별도 스크립트 파일에 의존하지 않고 아래 검증을 직접 실행한다.
+최소 확인:
 
 ```bash
-secrets_file="$HOME/.config/k-skill/secrets.env"
-if [ ! -f "$secrets_file" ]; then
-  echo "missing secrets file: $secrets_file"
-  echo "next steps:"
-  echo "  1. create ~/.config/k-skill/secrets.env with your credentials"
-  echo "  2. chmod 0600 ~/.config/k-skill/secrets.env"
-else
-  perms=$(stat -f '%Lp' "$secrets_file" 2>/dev/null || stat -c '%a' "$secrets_file" 2>/dev/null)
-  if [ "$perms" != "600" ]; then
-    echo "insecure permissions on $secrets_file: $perms (expected 600)"
-    echo "run: chmod 0600 $secrets_file"
-  else
-    echo "k-skill setup looks usable"
-  fi
-fi
+node --version
+npx -y @nomadamas/k-skill@0 list
+npx -y @nomadamas/k-skill@0 instruct k-skill-setup
 ```
 
-repo 전체를 clone받은 경우에는 같은 검증을 `npx -y @nomadamas/k-skill@0 exec k-skill-setup scripts/check-setup.sh --` 로 실행해도 된다.
+확인이 끝나면 다음만 짧게 보고한다.
 
-### 3. Offer scheduled update checks
+- 사용한 스킬 설치 방식 (`skills` 또는 Claude Code plugin)
+- CLI 사용 방식 (`npx` 기본 또는 선택적 global install)
+- 준비된 credential과 아직 필요한 환경변수 이름
+- 검증 성공/실패와 사용자가 해야 할 다음 한 단계
 
-setup이 끝나면 사용자에게 주기적인 업데이트 확인 자동화를 원하는지 먼저 묻는다. 원하지 않으면 건너뛴다.
+## 5. Optional update checks
 
-기본 정책:
+주기적인 업데이트 확인을 원하는지 먼저 묻는다. 원하지 않으면 건너뛴다.
 
-- 자동 설치가 아니라 `업데이트 확인` 만 기본으로 제안한다
-- 지속성 있는 시스템 변경(`crontab`, `launchd`, `schtasks`)은 동의 없이 적용하지 않는다
-- 기본 확인 명령은 `npx --yes skills check`
-- 사용자가 명시적으로 `자동 업데이트` 를 원할 때만 `npx --yes skills update` 기반 스케줄을 별도로 제안한다
-- 주의: `skills` CLI 버전에 따라 `check`에 `-g` 같은 옵션을 붙이면 확인을 넘어 설치본을 덮어쓸 수 있다. 자동화 스크립트에는 옵션 없는 `npx --yes skills check` 만 사용하고, 실제 업데이트 적용은 사용자가 검토 후 직접 실행하도록 안내한다
+정책:
+
+- 기본 명령은 설치를 변경하지 않는 `npx --yes skills check`다.
+- `check`에 `-g` 같은 추가 옵션을 붙이지 않는다.
+- 자동 업데이트는 사용자가 명시적으로 요청한 경우에만 별도로 논의한다.
+- 사용자가 승인한 확인 작업만 생성한다.
+- 별도 요약 작업, helper script, `claude -p` 같은 AI/CLI 작업을 함께 만들지 않는다.
 
 macOS / Linux 예시:
 
@@ -210,44 +190,21 @@ npx --yes skills check >> "$HOME/.config/k-skill/logs/skills-check.log" 2>&1
 schtasks /Create /SC DAILY /TN "k-skill-update-check" /TR "\"$HOME/.config/k-skill/bin/check-skill-updates.cmd\"" /ST 09:00 /F
 ```
 
-설정 후에는 로그 위치를 짧게 알려준다:
-
-- `~/.config/k-skill/logs/skills-check.log`
+사용자가 이 확인 작업 하나만 승인했다면 `k-skill-update-check` 외의 예약 작업이나
+추가 스크립트를 만들지 않는다.
 
-### 4. Offer GitHub starring with explicit consent
+## 6. Optional GitHub star
 
-setup 마지막에는 다음처럼 짧게 묻는다.
+마지막에 한 번만 묻는다.
 
 ```text
 k-skill 저장소(NomaDamas/k-skill)에 GitHub star를 눌러드릴까요?
-원하시면 `gh` 로 바로 처리하고, 원하지 않으면 건너뜁니다.
 ```
 
-규칙:
-
-- 사용자가 명시적으로 동의하기 전에는 star API를 호출하지 않는다
-- `gh` 가 없거나 인증되지 않았으면 설치/로그인 안내만 하고 자동 우회하지 않는다
-- star 대상 저장소는 `NomaDamas/k-skill` 이다
-
-동의했고 `gh auth status` 가 정상이면 GitHub API로 star를 실행한다. (`gh` CLI에는 `repo star` 서브커맨드가 없다.)
+동의한 경우에만 실행한다.
 
 ```bash
-# 이미 star 여부 확인: 204 = 이미 star, 404 = 아직
-gh api user/starred/NomaDamas/k-skill >/dev/null 2>&1 && echo "already starred" || echo "not starred yet"
-
-# star 실행
-gh api -X PUT user/starred/NomaDamas/k-skill
+gh api -X PUT /user/starred/NomaDamas/k-skill
 ```
 
-성공하면 짧게 완료만 알린다.
-
-## Completion checklist
-
-- `~/.config/k-skill/secrets.env` exists with permission `0600` (또는 에이전트가 자체 vault로 credential을 관리 중)
-- 필요한 환경변수가 설정되어 있다
-- 사용자가 원한 경우에만 업데이트 확인 자동화 또는 GitHub star가 설정되었다
-
-## Notes
-
-- 기본 흐름은 "전체 스킬 설치 → 이 setup skill 실행 → 개별 기능 사용" 이다
-- 저장소 안에는 secret file을 두지 않는다
+동의하지 않거나 `gh` 인증이 없으면 건너뛴다.

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

@@ -1,13 +1,13 @@
 {
   "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.",
+  "description": "Install the k-skill bundle, use the unified CLI, resolve credentials, verify the runtime, and optionally configure update checks and GitHub starring.",
   "profiles": [
     "proxy",
     "vault",
     "browser",
     "operations"
   ],
-  "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",
+  "frontmatter": "name: k-skill-setup\ndescription: Install the k-skill bundle, use the unified CLI, resolve credentials, verify the runtime, and optionally configure update checks and GitHub starring.\nlicense: MIT\nmetadata:\n  category: setup\n  locale: ko-KR\n  phase: v1",
   "bundle": [
     {
       "from": "scripts/check-setup.sh",

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

@@ -2,12 +2,13 @@
 
 ## What this skill does
 
-유저가 알려준 현재 위치를 기준으로 **카카오맵 기준 근처 술집**을 찾아준다.
+유저가 알려준 현재 위치를 기준으로 **카카오맵 공식 API에서 근처 술집 후보를 찾고**, 후보별 카카오맵 상세 링크로 핸드오프해 영업 상태·메뉴·좌석 정보를 확인한다.
 
 - 위치는 자동으로 추정하지 않는다.
 - **반드시 먼저 현재 위치를 질문**한다.
 - `서울역`, `강남`, `사당`, `신논현`, `논현` 같은 역명/동네/랜드마크 질의를 그대로 받을 수 있다.
-- 결과에는 현재 영업 상태, 대표 메뉴, 좌석 옵션(단체석/바테이블 등), 전화번호를 포함한다.
+- 장소 후보 검색과 거리 계산은 `k-skill-proxy`의 Kakao Local REST API를 우선 사용한다.
+- 공식 API에 없는 현재 영업 상태, 대표 메뉴, 좌석 옵션은 반환된 카카오맵 장소 상세 링크에서 확인한다.
 
 ## When to use
 
@@ -23,19 +24,67 @@
 - 권장 질문: `현재 위치를 알려주세요. 서울역/강남/사당 같은 역명이나 동네명으로 보내주시면 카카오맵 기준 근처 술집을 찾아볼게요.`
 - 위치가 애매하면: `가까운 역명이나 동 이름으로 한 번만 더 알려주세요.`
 
-## Official Kakao Map surfaces
+## Access path
 
-- 모바일 검색: `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>`
+### Primary: official Kakao Local API
+
+- hosted proxy: `https://k-skill-proxy.nomadamas.org`
+- anchor and bar search: `GET /v1/kakao-map/search/keyword`
+- user API key: 필요 없음
+- package function: `searchNearbyBarsByLocationQuery(locationQuery, options?)`
+
+패키지는 기준 장소를 공식 API로 찾은 뒤 같은 좌표를 중심으로 `<location> 술집`을 거리순 검색한다. 결과의 `sourceUrl`과 `detailLookup.url`은 Kakao Local 응답의 `place_url`을 사용하며, 누락 시 공식 장소 ID로 `https://place.map.kakao.com/<id>`를 구성한다.
+
+### Detail handoff: official Kakao Map place page
+
+- place detail: `https://place.map.kakao.com/<id>`
+- detail fields: `openStatus`, `menuSamples`, `seatingKeywords`, `capacityHint`
+
+내부 `place-api.map.kakao.com/places/panel3` JSON이나 모바일 검색 HTML을 기본 검색 경로로 사용하지 않는다. 장소 상세 정보가 필요할 때만 반환된 공식 장소 페이지를 브라우저로 연다.
 
 ## Workflow
 
 1. 유저에게 반드시 현재 위치를 묻는다.
-2. 받은 위치 문자열을 카카오맵 검색으로 anchor 후보(역/랜드마크)로 해석한다.
-3. 같은 위치 문자열에 `술집` 키워드를 붙여 nearby 술집 검색 결과를 가져온다.
-4. 상위 후보의 panel3 JSON 을 조회해 현재 영업 상태, 메뉴, 좌석 옵션, 전화번호를 정규화한다.
-5. **영업 중인 술집을 먼저** 보여주고, 필요하면 곧 열 곳도 함께 보여준다.
+2. `searchNearbyBarsByLocationQuery`로 공식 Kakao Local API 기반 후보를 가져온다.
+3. `items[]`에서 이름, 카테고리, 주소, 전화번호, 거리, `detailLookup.url`을 확인한다.
+4. 상위 3~5개 후보의 `detailLookup.url`을 브라우저로 열고 장소명이 후보와 일치하는지 먼저 확인한다.
+5. 상세 페이지에서 보이는 정보만 사용해 다음 필드를 보강한다.
+   - 현재 영업 상태와 오늘 영업시간
+   - 대표 메뉴 2~3개
+   - 단체석, 룸, 바테이블, 혼술 등 좌석/인원 힌트
+6. 상세 확인이 끝난 후보는 영업 중 우선, 그다음 거리순으로 정리한다.
+7. 상세 페이지가 차단되거나 해당 필드가 없으면 추정하지 않는다. 공식 API 결과와 장소 링크를 제공하고 `상세 정보 미확인`으로 표시한다.
+
+## Package output contract
+
+```js
+const { searchNearbyBarsByLocationQuery } = require("kakao-bar-nearby");
+
+const result = await searchNearbyBarsByLocationQuery("서울역", {
+  limit: 5,
+  radius: 3000
+});
+```
+
+주요 반환 필드:
+
+- `anchor`: 공식 API에서 선택한 기준 장소
+- `items[].name`, `category`, `address`, `phone`
+- `items[].distanceMeters`
+- `items[].sourceUrl`
+- `items[].detailLookup.status`: 상세 페이지 확인 전에는 `required`
+- `items[].detailLookup.url`: 영업·메뉴·좌석 확인에 사용할 카카오맵 장소 링크
+- `items[].detailLookup.fields`: 상세 페이지에서 확인할 필드 목록
+- `meta.source`: `kakao-local-rest-api`
+- `meta.detailLookupRequiredCount`
+
+공식 API 단계에서는 상세 필드를 임의로 채우지 않는다.
+
+- `isOpenNow`: `null`
+- `openStatus`: `null`
+- `menuSamples`: `[]`
+- `seatingKeywords`: `[]`
+- `capacityHint`: `null`
 
 ## Responding
 
@@ -43,34 +92,27 @@
 
 - 술집명
 - 카테고리
-- 영업 상태 (`영업 중`, `영업 전`, `휴무일` 등)
+- 영업 상태 (`영업 중`, `영업 전`, `휴무일`, `상세 정보 미확인`)
 - 대표 메뉴 2~3개
 - 좌석/인원 수용 힌트 (`단체석`, `바테이블` 등)
 - 전화번호
-- 거리(가능하면)
-
-## Node.js example
+- 거리
+- 카카오맵 상세 링크
 
-```js
-const { searchNearbyBarsByLocationQuery } = require("kakao-bar-nearby");
-
-async function main() {
-  const result = await searchNearbyBarsByLocationQuery("서울역", {
-    limit: 5
-  });
+공식 API에서 확인한 값과 상세 페이지에서 확인한 값을 혼동하지 않는다. 메뉴·영업·좌석 정보는 상세 페이지에서 실제로 확인한 후보에만 표시한다.
 
-  console.log(result.anchor);
-  console.log(result.items);
-}
+## Failure modes
 
-main().catch((error) => {
-  console.error(error);
-  process.exitCode = 1;
-});
-```
+- `429 rate_limited`: 잠시 후 재시도가 필요함을 알리고 반복 호출하지 않는다.
+- `502 upstream_error` / `503 upstream_not_configured`: 공식 Kakao API 경로가 현재 사용 불가하므로 원인을 그대로 설명한다.
+- 기준 장소가 모호함: 가까운 역명이나 동 이름을 한 번 더 묻는다.
+- 술집 후보 없음: 반경을 넓히거나 `와인바`, `이자카야`, `호프`처럼 키워드를 구체화한다.
+- 장소 상세 페이지 차단, CAPTCHA, 빈 화면, 구조 변경: 우회하지 않고 공식 API 후보와 링크까지만 제공한다.
+- 메뉴·좌석·영업 정보가 페이지에 없음: 추정하지 않고 `상세 정보 미확인`으로 표시한다.
 
 ## Done when
 
 - 유저의 현재 위치를 먼저 확인했다.
-- 카카오맵 기준 술집 결과를 최소 1개 이상 찾았거나, 찾지 못한 이유와 다음 질문을 제시했다.
-- 영업 상태/메뉴/좌석 옵션/전화번호가 포함된 요약을 보여줬다.
+- 공식 Kakao Local API로 술집 후보를 최소 1개 이상 찾았거나 실패 이유를 설명했다.
+- 각 후보의 카카오맵 상세 링크를 확보했다.
+- 상위 후보의 상세 링크에서 영업 상태·메뉴·좌석 정보를 확인했거나, 확인하지 못한 이유를 명시했다.

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

@@ -1,8 +1,10 @@
 {
   "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. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "description": "Use when the user asks for nearby bars or 근처 술집. Ask for the user's location, search with the official Kakao Local API, then follow returned Kakao Map detail links for open-now, menu, and seating hints. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
   "profiles": [
+    "proxy",
+    "browser",
     "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"
+  "frontmatter": "name: kakao-bar-nearby\ndescription: Use when the user asks for nearby bars or 근처 술집. Ask for the user's location, search with the official Kakao Local API, then follow returned Kakao Map detail links for open-now, menu, and seating hints. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: food\n  locale: ko-KR\n  phase: v1"
 }