@nomadamas/k-skill 0.4.2 → 0.4.3

package/package.json

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

package/skills/coupang-product-search/instruction.md

@@ -1,219 +1,90 @@
 # Coupang Product Search
 
-## What this skill does
+## Purpose
 
-[retention-corp/coupang_partners](https://github.com/retention-corp/coupang_partners) 저장소의 로컬 Coupang MCP 호환 레이어를 사용해 쿠팡 상품 조회 도구를 실행한다. 기존 유지보수형 HF Space MCP 엔드포인트 대신, 이 저장소의 `bin/coupang_mcp.py`가 제공하는 `local://coupang-mcp` 계약을 호출한다.
+`k-skill-proxy`의 공식 Coupang Partners API route로 쿠팡 상품을 검색한다.
+사용자에게 쿠팡 파트너스 access/secret key를 요구하지 않는다. 키와 HMAC
+서명은 proxy 서버에만 존재한다.
 
-- 키워드 상품 검색
-- 로켓배송 전용 필터 검색
-- 가격대 범위 검색
-- 상품 비교표 생성
-- 카테고리별 베스트 상품
-- 골드박스 당일 특가
-- 인기 검색어/계절 상품 추천
+## Endpoint
 
-## How it works
-
-```
-Claude Code / Codex
-  → coupang-product-search/scripts/coupang_partners_mcp.py
-    → git clone/update retention-corp/coupang_partners (user cache)
-      → python3 bin/coupang_mcp.py
-        → local://coupang-mcp compatible tool layer
-          ├─ Coupang Partners API client (operator keys present)
-          └─ hosted fallback → https://a.retn.kr/v1/public/assist (no keys)
-```
-
-Hard rules:
-
-- `COUPANG_MCP_ENDPOINT`는 호환성 knob로만 유지한다. 기본값은 `local://coupang-mcp`다.
-- 구형 HF Space hosted MCP 엔드포인트를 사용하거나 새로 지어내지 않는다.
-- upstream 저장소는 `https://github.com/retention-corp/coupang_partners.git`만 사용한다.
-- `tools`와 `init`은 로컬 MCP 계약 확인용으로 먼저 실행한다.
-
-## Execution paths
-
-`retention-corp/coupang_partners`는 하나의 CLI 뒤에서 두 가지 경로를 자동으로 선택한다. 래퍼(`coupang_partners_mcp.py`)는 두 경로 모두를 그대로 통과시킨다.
-
-1. **Operator (local HMAC) path** — `COUPANG_ACCESS_KEY`와 `COUPANG_SECRET_KEY`가 둘 다 설정된 경우. upstream이 Coupang Partners API를 HMAC 서명해 직접 호출한다. 키/시크릿은 절대 답변·문서·커밋에 노출하지 않는다.
-2. **Credentialless hosted fallback path** — 위 두 키 중 하나라도 없는 경우(또는 `OPENCLAW_SHOPPING_FORCE_HOSTED=1`). upstream이 자동으로 Retention Corp의 hosted 백엔드(`https://a.retn.kr/v1/public/assist`)로 떨어진다. 이 경로는 `X-OpenClaw-Client-Id` allowlist로 게이트되어 있으며, upstream이 기본으로 실어 보내는 `openclaw-skill` 값이 현재 Retention Corp allowlist에 등록된 값이다. k-skill 래퍼는 `OPENCLAW_SHOPPING_CLIENT_ID`를 별도로 설정하지 않고 이 upstream 기본값을 그대로 사용한다.
-
-두 경로 모두 JSON envelope(`ok`/`data.session_id`/`data.tool`/`data.payload`/`data.result`) 모양은 동일하므로, 답변 로직은 경로를 구별할 필요가 없다. short deeplink는 hosted fallback에서는 `https://a.retn.kr/s/...` 형태로, operator path에서는 `https://link.coupang.com/...` 형태로 온다.
-
-### 관련 환경변수
-
-| 환경변수 | 역할 | 기본값 |
-|---------|------|--------|
-| `COUPANG_ACCESS_KEY`, `COUPANG_SECRET_KEY` | 운영자 Coupang Partners API 크리덴셜. 둘 다 있을 때만 로컬 HMAC 경로가 활성화된다. | 없음 (없으면 hosted fallback) |
-| `OPENCLAW_SHOPPING_CLIENT_ID` | hosted fallback이 보낼 `X-OpenClaw-Client-Id`. upstream이 `openclaw-skill`을 기본으로 실어 보내며 이 값이 현재 Retention Corp allowlist에 등록되어 있다. k-skill 래퍼는 이 변수를 오버라이드하지 않는 것을 권장한다. | `openclaw-skill` |
-| `OPENCLAW_SHOPPING_FORCE_HOSTED` | `1`이면 키가 있어도 hosted 경로를 강제한다. | 비어있음 |
-| `OPENCLAW_SHOPPING_BASE_URL` | hosted 백엔드 base URL 오버라이드. 스테이징/로컬 backend 테스트용. | `https://a.retn.kr` |
-
-## MCP endpoint / contract
-
-```
-local://coupang-mcp
+```text
+GET ${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}/v1/coupang/products/search
 ```
 
-프로토콜 호환 버전: MCP `2025-03-26`. 네트워크로 붙는 Streamable HTTP 서버가 아니라, upstream 저장소의 로컬 MCP 호환 CLI가 같은 도구 이름과 JSON-RPC 모양의 payload를 반환한다.
+허용 query:
 
-## When to use
+| field | required | rule |
+| --- | --- | --- |
+| `keyword` 또는 `q` | yes | 2~100자 검색어 |
+| `limit` | no | 1~10, 기본 10 |
+| `subId` | no | 호출 분석용 식별자, 최대 100자 |
 
-- "쿠팡에서 생수 가격 좀 찾아줘"
-- "로켓배송 에어팟 찾아줘"
-- "20만원 이하 키보드 추천해줘"
-- "아이패드 vs 갤럭시탭 비교"
-- "오늘 쿠팡 특가 뭐 있어?"
-- "전자제품 베스트 보여줘"
+`COUPANG_ACCESS_KEY`와 `COUPANG_SECRET_KEY`를 caller 환경이나 명령 인자로
+넣지 않는다. 운영자가 proxy의 gpu01 runtime `.env`에만 설정한다.
 
-## When not to use
-
-- 돌쇠가 아니며 로그인, 장바구니, 결제 자동화가 필요한 경우
-- 돌쇠가 아니며 쿠팡 계정/session 접근이 필요한 경우
-- 실시간 재고/품절 여부를 100% 보장해야 하는 경우 (hosted fallback과 Partners API 모두 캐시·지연이 있을 수 있다)
+상품 링크를 안내할 때는 반드시 "쿠팡 파트너스 활동을 통해 일정액의 수수료를
+제공받을 수 있습니다."라고 고지한다.
 
 ## Workflow
 
-### 1. Clarify the need
-
-검색어가 너무 넓으면 먼저 의도를 좁힌다.
-
-- 권장 질문: `어떤 용도/예산/브랜드/용량을 우선할까요?`
-
-### 2. Bootstrap and check the tool contract
-
-래퍼는 기본적으로 `~/.cache/k-skill/coupang_partners`에 upstream 저장소를 clone한다. 이미 clone되어 있으면 그대로 사용하고, 최신화가 필요할 때만 `--update`를 붙인다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec coupang-product-search scripts/coupang_partners_mcp.py -- tools
-npx -y @nomadamas/k-skill@0 exec coupang-product-search scripts/coupang_partners_mcp.py -- init
-```
-
-기존 checkout을 명시하거나 CI/검증에서 네트워크 clone을 막으려면:
+1. 검색어가 넓으면 용도, 예산, 브랜드, 용량을 확인한다.
+2. 아래처럼 proxy를 호출한다.
 
 ```bash
-npx -y @nomadamas/k-skill@0 exec coupang-product-search scripts/coupang_partners_mcp.py -- \
-  --repo-dir /path/to/coupang_partners \
-  --no-clone \
-  tools
-npx -y @nomadamas/k-skill@0 exec coupang-product-search scripts/coupang_partners_mcp.py -- \
-  --repo-dir /path/to/coupang_partners \
-  --no-clone \
-  init
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "${BASE}/v1/coupang/products/search" \
+  --data-urlencode 'keyword=무선청소기' \
+  --data-urlencode 'limit=10' \
+  --data-urlencode 'subId=k-skill'
 ```
 
-### 3. Call tools
-
-구체적인 사용자 요청에 맞춰 upstream CLI 명령을 호출한다. 결과는 `ok`, `data.tool`, `data.payload`, `data.result`를 포함하는 JSON으로 반환된다.
-
-```bash
-# 일반 검색 (키 없이도 hosted fallback으로 작동)
-npx -y @nomadamas/k-skill@0 exec coupang-product-search scripts/coupang_partners_mcp.py -- search "32인치 4K 모니터"
-
-# 로켓배송 필터
-npx -y @nomadamas/k-skill@0 exec coupang-product-search scripts/coupang_partners_mcp.py -- rocket "에어팟"
+3. 응답의 `items`를 읽고 `is_rocket`에 따라 로켓배송과 일반배송으로 나눈다.
+4. 사용자의 예산이 있으면 `price`로 필터링하고 상위 3~5개만 비교한다.
+5. 가격, 품절, 배송 정보는 변할 수 있음을 명시한다.
+6. 상품 링크를 제공할 때 아래 affiliate 고지를 반드시 포함한다.
 
-# 가격대 검색
-npx -y @nomadamas/k-skill@0 exec coupang-product-search scripts/coupang_partners_mcp.py -- budget "키보드" --max-price 100000
-
-# 비교
-npx -y @nomadamas/k-skill@0 exec coupang-product-search scripts/coupang_partners_mcp.py -- compare "아이패드 vs 갤럭시탭"
-
-# 골드박스 (운영자 키가 필요한 upstream 경로)
-npx -y @nomadamas/k-skill@0 exec coupang-product-search scripts/coupang_partners_mcp.py -- goldbox
+```text
+쿠팡 파트너스 활동을 통해 일정액의 수수료를 제공받을 수 있습니다.
 ```
 
-### 4. (optional) hosted fallback 강제
+## Response fields
 
-운영자 키가 있는 상태에서도 hosted fallback 경로를 점검하고 싶으면 `OPENCLAW_SHOPPING_FORCE_HOSTED=1`만 추가하면 된다. `OPENCLAW_SHOPPING_CLIENT_ID`는 upstream이 보내는 기본값 `openclaw-skill`이 현재 Retention Corp allowlist에 등록된 값이므로 별도로 설정하지 않는다.
+각 상품은 다음 안정 필드를 제공한다.
 
-```bash
-export OPENCLAW_SHOPPING_FORCE_HOSTED=1
-npx -y @nomadamas/k-skill@0 exec coupang-product-search scripts/coupang_partners_mcp.py -- search "에어팟"
-```
+- `product_id`
+- `title`
+- `price`, `price_text`
+- `url`, `image_url`
+- `review_count`, `score`
+- `is_rocket`, `is_free_shipping`
 
-### 5. Continue from discovery to cart and checkout in Dolshoi
-
-사용자가 구매나 장바구니 담기를 요청했고 CloakBrowser mode라면 MCP 결과 링크에서 멈추지 않는다.
-
-1. 선택한 상품의 공식 쿠팡 URL을 CloakBrowser로 연다.
-2. 현재 상품명, 판매자, 옵션, 수량, 로켓배송 여부, 실시간 가격과 품절 여부를 다시 확인한다.
-3. 로그인이 필요하면 provisioned vault capability를 사용하고, 없으면 `request_vault_credential`로 쿠팡 login을 저장한 뒤 같은 turn에 재개한다.
-4. 옵션과 수량을 선택해 장바구니에 담는다. 장바구니 담기는 가역적이므로 별도 승인 없이 수행하고 실제 담김 상태를 확인한다.
-5. 구매 요청이면 배송지/쿠폰/결제수단 적용 후 최종 주문 직전까지 진행한다.
-6. `clarify`로 상품·옵션·수량·배송지 요약·최종 금액을 승인받고, 승인되면 주문/결제를 실행해 주문번호와 상태를 확인한다.
-
-CloakBrowser를 사용할 수 없는 generic runtime에서는 기존 검색/링크 제공 범위를 유지한다.
-
-## Available tools
-
-| 도구명 | CLI 명령 | 기능 | 파라미터 예시 |
-|--------|----------|------|-------------|
-| `search_coupang_products` | `search` | 일반 상품 검색 | `"생수"` |
-| `search_coupang_rocket` | `rocket` | 로켓배송만 필터링 | `"에어팟"` |
-| `search_coupang_budget` | `budget` | 가격대 범위 검색 | `"키보드" --max-price 100000` |
-| `compare_coupang_products` | `compare` | 상품 비교표 생성 | `"아이패드 vs 갤럭시탭"` |
-| `get_coupang_recommendations` | `recommendations` | 인기 검색어 제안 | `--category 전자제품` |
-| `get_coupang_seasonal` | `seasonal` | 계절/상황별 추천 | `"설날 선물"` |
-| `get_coupang_best_products` | `best` | 카테고리별 베스트 | `--category-id 1016` |
-| `get_coupang_goldbox` | `goldbox` | 당일 특가 정보 | `--limit 10` |
-
-주의: `get_coupang_goldbox`와 `get_coupang_best_products`는 upstream 기준 Coupang Partners API 권한이 필요한 경로이므로, 키가 없는 환경에서는 실패할 수 있다. 이런 경우 에러 메시지를 그대로 전달하고 hosted fallback이 커버하는 `search`/`rocket`/`budget`/`compare` 경로로 우회 제안한다.
-
-## Response format
-
-upstream CLI는 JSON을 출력한다. `data.result` 안의 상품 배열 또는 도구별 객체를 읽고, 답변에서는 로켓배송(rocket)과 일반배송(normal)을 구분한다.
-
-```json
-{
-  "ok": true,
-  "data": {
-    "session_id": "session-...",
-    "tool": "search_coupang_products",
-    "payload": {
-      "jsonrpc": "2.0",
-      "result": {
-        "content": [
-          {"type": "text", "text": "[...]"}
-        ]
-      }
-    },
-    "result": []
-  }
-}
-```
+## Failure modes
 
-사용자에게 보여줄 때는 다음처럼 짧게 정리한다.
+- `400 bad_request`: 검색어가 없거나 너무 짧음. 입력을 바로잡아 재호출한다.
+- `503 upstream_not_configured`: proxy 운영자가 Coupang key 두 개를 아직 설정하지 않음.
+- `502 upstream_forbidden`: 키가 거절되었거나 Partners API 권한이 없음.
+- `502 upstream_error` / `upstream_unavailable`: 쿠팡 upstream 장애. 실패를 숨기지 말고 나중 재시도를 안내한다.
 
-```
-## rocket (상위 후보)
-
-1) LG전자 4K UHD 모니터
-   가격: 397,750원 (참고용)
-   보러가기: https://a.retn.kr/s/...          # hosted fallback shortlink
-   또는:   https://link.coupang.com/a/...     # operator HMAC 경로 딥링크
+임의의 Coupang scraping, 구형 HF Space MCP, `a.retn.kr` hosted fallback,
+사용자 제공 API key로 우회하지 않는다.
 
-## normal (상위 후보)
-
-1) 삼성전자 QHD 오디세이 G5 게이밍 모니터
-   가격: 283,000원 (참고용)
-   보러가기: https://a.retn.kr/s/...
-```
+## Continue to cart or purchase
 
-## Response policy
+사용자가 장바구니 또는 구매를 요청했고 CloakBrowser mode라면 결과 링크에서
+멈추지 않는다.
 
-- 후보가 여러 개면 상위 3~5개만 짧게 비교한다.
-- 로켓배송/일반배송 구분을 명시한다.
-- 가격/품절/배송 정보는 실시간 변동될 수 있음을 안내한다.
-- upstream checkout, 권한, Coupang Partners 환경변수 문제로 실패하면 실패 원인과 재시도/설정 방법을 짧게 안내한다.
-- **Affiliate 고지(필수)**: 응답에 포함되는 shortlink(`https://a.retn.kr/s/...`)와 직접 coupang 딥링크(`link.coupang.com/...?lptag=AF...`)는 Retention Corp의 쿠팡 파트너스(affiliate) 채널로 트래킹된다. upstream이 돌려주는 `disclosure` 문자열(`"파트너스 활동을 통해 일정액의 수수료를 제공받을 수 있음"`)이 있으면 그대로 노출하고, 없으면 같은 취지의 고지를 답변 말미에 덧붙인다.
+1. 선택 상품의 공식 쿠팡 URL을 열어 상품명, 판매자, 옵션, 수량, 실시간 가격,
+   로켓배송 여부와 품절 상태를 다시 확인한다.
+2. 로그인이 필요하면 provisioned vault capability를 사용하고, 없으면
+   `request_vault_credential`로 쿠팡 login을 저장한 뒤 재개한다.
+3. 장바구니 담기는 가역적이므로 수행 후 실제 담김을 확인한다.
+4. 구매는 배송지, 쿠폰, 결제수단 적용 후 최종 주문 직전에 정확한 대상과 금액을
+   `clarify`로 승인받고 실행한다.
 
 ## Done when
 
-- `tools`와 `init` 또는 실제 명령으로 retention-corp/coupang_partners 로컬 MCP 계약을 확인했다.
-- 검색 결과가 로켓배송/일반배송으로 구분되어 정리되었다.
-- 사용자 니즈에 맞는 추천 TOP 3이 제시되었다.
-- 가격/배송 정보와 변동 가능성 안내가 포함되었다.
-- affiliate 고지(disclosure)가 답변에 포함되었다.
-- 돌쇠의 장바구니 요청이면 선택 옵션/수량이 실제 장바구니에 담긴 것을 확인했다.
-- 돌쇠의 구매 요청이면 `clarify` 승인 후 주문번호와 결제 상태를 확인했다.
+- proxy 응답을 실제로 받았다.
+- 로켓배송/일반배송과 가격을 구분해 후보를 정리했다.
+- 가격·배송 변동 가능성과 affiliate 고지를 포함했다.
+- 액션 요청이면 해당 표면의 실제 완료 상태를 확인했다.

package/skills/coupang-product-search/skill.json

@@ -1,10 +1,14 @@
 {
   "name": "coupang-product-search",
-  "description": "retention-corp/coupang_partners의 로컬 Coupang MCP 호환 레이어로 쿠팡 상품 검색, 로켓배송 필터, 가격대 검색, 상품 비교, 베스트 상품, 골드박스 특가를 조회한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "description": "k-skill-proxy의 공식 Coupang Partners API 경로로 쿠팡 상품을 검색하고 로켓배송·가격 후보를 비교한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
   "profiles": [
     "vault",
     "browser",
     "action:commerce"
   ],
-  "frontmatter": "name: coupang-product-search\ndescription: retention-corp/coupang_partners의 로컬 Coupang MCP 호환 레이어로 쿠팡 상품 검색, 로켓배송 필터, 가격대 검색, 상품 비교, 베스트 상품, 골드박스 특가를 조회한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: retail\n  locale: ko-KR\n  phase: v2"
+  "stub_notice": {
+    "heading": "Affiliate disclosure (required)",
+    "body": "상품 링크를 안내할 때는 반드시 \"쿠팡 파트너스 활동을 통해 일정액의 수수료를 제공받을 수 있습니다.\"라고 고지한다."
+  },
+  "frontmatter": "name: coupang-product-search\ndescription: k-skill-proxy의 공식 Coupang Partners API 경로로 쿠팡 상품을 검색하고 로켓배송·가격 후보를 비교한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: retail\n  locale: ko-KR\n  phase: v2"
 }

package/skills/daiso-product-search/instruction.md

@@ -26,7 +26,16 @@
 
 - 인터넷 연결
 - `node` 18+
-- 이 저장소의 `daiso-product-search` package 또는 동일 로직
+- `daiso-product-search` npm package
+
+설치:
+
+```bash
+npm install daiso-product-search
+```
+
+이 저장소에서 개발할 때는 루트에서 `npm install` 후 `packages/daiso-product-search`를 쓴다.
+package 설치가 막히면 표면을 직접 호출해 우회하지 말고 설치를 먼저 해결한다. 직접 호출은 실패가 성공처럼 보이는 응답을 준다(Failure modes 참고).
 
 ## Required inputs
 
@@ -161,6 +170,7 @@ console.log(result.pickupStock)
 - 현재 확인된 공식 표면은 **매장 내 aisle/진열 위치**를 직접 주지 않을 수 있다.
 - `selStrPkupStck` 403 → `/api/auth/request` 재호출 후 Bearer를 새로 빌드해 재시도한다.
 - Bearer 재시도 후에도 401/403이면 재고 수량은 `retrievalStatus: "blocked"` 로 표시하고, `selPkupStr` 기반 `pickupEligibility`(픽업 가능 여부)만 보조 정보로 제공한다.
+- **package 없이 표면을 직접 호출하면 조용히 틀린다.** `SearchGoods`는 검색어 파라미터명이 틀려도 400이 아니라 200에 전체 카탈로그를 돌려준다. 검색어는 JSON 바디가 아니라 쿼리스트링 `searchTerm`으로 보내야 하고, `selStr`도 바디 키가 틀리면 무관한 매장 1건만 준다. 둘 다 실패가 성공처럼 보이므로 반드시 package를 경유한다.
 
 ## Notes
 

package/skills/fsc-corporate-info/instruction.md

@@ -48,7 +48,8 @@ npx -y @nomadamas/k-skill@0 exec fsc-corporate-info scripts/fsc_corporate_info.p
 - `400 bad_request`: 법인명을 주지 않음.
 - `503 upstream_not_configured`: 프록시 서버에 `DATA_GO_KR_API_KEY` 없음.
 - `502 upstream_forbidden`: 프록시 키가 15043184에 활용신청되지 않음.
-- 빈 결과: 법인명 불일치 — 표기를 바꿔 재시도.
+- `coverage`: 기업기본정보 데이터셋 범위, 법인명 후보 및 선택적 사업자번호 교차검증 기준, 제외 범위, 0건의 의미, 조회시각(`checked_at`)을 구조화해 제공한다.
+- 빈 결과: 이 데이터셋에서 입력 법인명 후보가 없음. 법인이 존재하지 않는다는 뜻이 아니며 표기 차이 가능성이 있다.
 
 ## Official surfaces
 

package/skills/fsc-corporate-info/scripts/test_fsc_corporate_info.py

@@ -0,0 +1,42 @@
+import unittest
+
+import fsc_corporate_info as subject
+
+
+class CoveragePassthroughTest(unittest.TestCase):
+    def test_zero_result_keeps_proxy_coverage(self):
+        payload = {
+            "candidate_count": 0,
+            "candidates": [],
+            "coverage": {"scope": "fsc-corporate-outline-dataset"},
+        }
+
+        response = subject.query_corp_outline("없는법인", read_json=lambda _request: payload)
+
+        self.assertIs(response, payload)
+        self.assertEqual(response["coverage"]["scope"], "fsc-corporate-outline-dataset")
+
+    def test_matched_result_keeps_proxy_coverage(self):
+        payload = {
+            "candidate_count": 1,
+            "candidates": [{"corpNm": "테스트"}],
+            "coverage": {
+                "match_basis": "corporate-name-candidates-with-optional-business-number-cross-check"
+            },
+        }
+
+        response = subject.query_corp_outline(
+            "테스트",
+            "123-45-67890",
+            read_json=lambda _request: payload,
+        )
+
+        self.assertIs(response, payload)
+        self.assertEqual(
+            response["coverage"]["match_basis"],
+            "corporate-name-candidates-with-optional-business-number-cross-check",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/g2b-sanctioned-supplier/instruction.md

@@ -51,7 +51,8 @@ npx -y @nomadamas/k-skill@0 exec g2b-sanctioned-supplier scripts/g2b_sanctioned_
 - `400 bad_request`: 사업자번호가 10자리가 아님.
 - `503 upstream_not_configured`: 프록시 서버에 `DATA_GO_KR_API_KEY` 없음.
 - `502 upstream_forbidden`: 프록시 키가 15129466에 활용신청되지 않음.
-- `total_count = 0`: 조회시점 현재 유효한 제재 없음 (만료·미등록업체는 미제공임에 유의).
+- `coverage`: 현재 유효 제재 범위, 사업자번호 정확 일치 기준, 과거·미등록 제외 범위, 0건의 의미, 조회시각(`checked_at`)을 구조화해 제공한다.
+- `total_count = 0`: 조회시점 현재 유효한 제재가 조회되지 않음. 만료·해제된 과거 제재가 없다는 뜻은 아니다.
 
 ## Official surfaces
 

package/skills/g2b-sanctioned-supplier/scripts/test_g2b_sanctioned_supplier.py

@@ -0,0 +1,33 @@
+import unittest
+
+import g2b_sanctioned_supplier as subject
+
+
+class CoveragePassthroughTest(unittest.TestCase):
+    def test_zero_result_keeps_proxy_coverage(self):
+        payload = {
+            "total_count": 0,
+            "active_sanctions": [],
+            "coverage": {"scope": "currently-effective-g2b-sanctions"},
+        }
+
+        response = subject.query_sanctions("123-45-67890", read_json=lambda _request: payload)
+
+        self.assertIs(response, payload)
+        self.assertEqual(response["coverage"]["scope"], "currently-effective-g2b-sanctions")
+
+    def test_matched_result_keeps_proxy_coverage(self):
+        payload = {
+            "total_count": 1,
+            "active_sanctions": [{"bizno": "1234567890"}],
+            "coverage": {"match_basis": "exact-business-number"},
+        }
+
+        response = subject.query_sanctions("1234567890", read_json=lambda _request: payload)
+
+        self.assertIs(response, payload)
+        self.assertEqual(response["coverage"]["match_basis"], "exact-business-number")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/market-kurly-search/instruction.md

@@ -27,7 +27,15 @@
 
 - 인터넷 연결
 - `node` 18+
-- 이 저장소의 `market-kurly-search` package 또는 동일 로직
+- `market-kurly-search` npm package
+
+설치:
+
+```bash
+npm install market-kurly-search
+```
+
+이 저장소에서 개발할 때는 루트에서 `npm install` 후 `packages/market-kurly-search`를 쓴다.
 
 ## Required inputs
 

package/skills/nts-tax-delinquency/instruction.md

@@ -47,7 +47,8 @@ npx -y @nomadamas/k-skill@0 exec nts-tax-delinquency scripts/nts_tax_delinquency
 ## Failure modes
 
 - `unavailable` + 안내: 상호 미입력, 네트워크 오류, 페이지 구조 변경 추정 — 수동 확인 URL 제공.
-- 0건: 두 명단 모두 매치 없음 (`match_count: 0`).
+- `coverage`: 조회한 공개 명단 범위, 상호·법인명 문자열 대조 기준, 제외 범위, 0건의 의미, 조회시각(`checked_at`)을 구조화해 제공한다.
+- 0건: 두 명단 모두 공개 명단에서 문자열 매치가 없음 (`match_count: 0`). 모든 국세 체납이 없다는 뜻은 아니다.
 
 ## Official surfaces
 

package/skills/nts-tax-delinquency/scripts/nts_tax_delinquency.py

@@ -36,6 +36,18 @@ INDIV_COLUMNS = ("no", "공개년도", "성명", "연령", "상호", "직업(업
 IDENTITY_NOTE = ("명단공개 자료에는 사업자등록번호가 수록되지 않아 입력 사업자번호와의 "
                  "동일성은 확인할 수 없다 — 상호·법인명 문자열 일치 후보의 공개 사실만 "
                  "나열하며, 동명 상호일 가능성은 사용자가 판단한다.")
+COVERAGE = {
+    "scope": "nts-high-amount-habitual-delinquent-disclosure",
+    "match_basis": "corporate-name-and-trade-name-string-match",
+    "exclusions": [
+        "명단공개 기준에 들지 않는 체납 및 비공개 체납",
+        "사업자등록번호 동일성 확인",
+    ],
+    "zero_result_meaning": (
+        "조회한 국세청 고액·상습체납자 공개 명단에서 법인명·상호 문자열 일치가 없다는 뜻이며, "
+        "모든 국세 체납이 없다는 뜻은 아니다."
+    ),
+}
 
 _HEADING_MARKER = "고액상습체납자"
 _ZERO_MARKER = "조회된 데이터가 없습니다"
@@ -50,13 +62,15 @@ def _now_iso() -> str:
 
 
 def _envelope(status: str, *, result: dict | None = None, note: str | None = None) -> dict:
+    looked_up_at = _now_iso()
     return {
         "source": SOURCE,
-        "looked_up_at": _now_iso(),
+        "looked_up_at": looked_up_at,
         "status": status,
         "result": result,
         "origin": "unauthenticated-public",
         "note": note,
+        "coverage": {**COVERAGE, "checked_at": looked_up_at} if status == "ok" else None,
     }
 
 

package/skills/nts-tax-delinquency/scripts/test_nts_tax_delinquency.py

@@ -0,0 +1,32 @@
+import unittest
+from unittest.mock import patch
+
+import nts_tax_delinquency as subject
+
+
+class CoverageTest(unittest.TestCase):
+    def test_zero_result_explains_disclosure_scope(self):
+        with patch.object(subject, "_search", side_effect=[[], []]):
+            response = subject.lookup("테스트상사")
+
+        self.assertEqual(response["status"], "ok")
+        self.assertEqual(response["result"]["corporate_list"]["match_count"], 0)
+        self.assertEqual(response["result"]["individual_list"]["match_count"], 0)
+        self.assertEqual(response["coverage"]["match_basis"], "corporate-name-and-trade-name-string-match")
+        self.assertTrue(response["coverage"]["zero_result_meaning"])
+        self.assertTrue(response["coverage"]["checked_at"])
+
+    def test_matched_result_keeps_same_coverage_contract(self):
+        corporate = [{"법인명": "테스트상사", "총체납액": "1억원"}]
+        individual = [{"상호": "테스트상사", "총체납액": "2억원"}]
+        with patch.object(subject, "_search", side_effect=[corporate, individual]):
+            response = subject.lookup("테스트상사")
+
+        self.assertEqual(response["result"]["corporate_list"]["matches"], corporate)
+        self.assertEqual(response["result"]["individual_list"]["matches"], individual)
+        self.assertEqual(response["coverage"]["scope"], "nts-high-amount-habitual-delinquent-disclosure")
+        self.assertIn("사업자등록번호 동일성 확인", response["coverage"]["exclusions"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/coupang-product-search/scripts/coupang_partners_mcp.py

@@ -1,146 +0,0 @@
-#!/usr/bin/env python3
-"""Bootstrap and run retention-corp/coupang_partners Coupang MCP tools.
-
-The k-skill repo intentionally does not vendor the third-party implementation.
-This wrapper keeps the skill pointed at the approved upstream repository, clones it
-into a user cache when needed, and then delegates to its local MCP-compatible CLI.
-"""
-
-from __future__ import annotations
-
-import argparse
-import os
-import pathlib
-import subprocess
-import sys
-from typing import Sequence
-
-UPSTREAM_REPO_URL = "https://github.com/retention-corp/coupang_partners.git"
-DEFAULT_MCP_ENDPOINT = "local://coupang-mcp"
-DEFAULT_REPO_DIR = pathlib.Path(os.getenv("COUPANG_PARTNERS_REPO_DIR", "~/.cache/k-skill/coupang_partners")).expanduser()
-UPSTREAM_CLI = pathlib.Path("bin") / "coupang_mcp.py"
-
-
-class BootstrapError(RuntimeError):
-    """Raised when the upstream checkout cannot be prepared."""
-
-
-def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description="Run the retention-corp/coupang_partners local Coupang MCP-compatible CLI.",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog=(
-            "Examples:\n"
-            "  coupang_partners_mcp.py tools\n"
-            "  coupang_partners_mcp.py init\n"
-            "  coupang_partners_mcp.py search 생수\n"
-            "  coupang_partners_mcp.py budget 키보드 --max-price 100000\n"
-            "\n"
-            "Honored upstream environment variables (forwarded as-is):\n"
-            "  COUPANG_ACCESS_KEY, COUPANG_SECRET_KEY\n"
-            "      Operator Coupang Partners API credentials. When set, upstream\n"
-            "      uses the local HMAC-signed Coupang Partners path.\n"
-            "  OPENCLAW_SHOPPING_CLIENT_ID\n"
-            "      Allowlisted client id for the hosted fallback. upstream sends\n"
-            "      openclaw-skill by default, which is the value currently on the\n"
-            "      Retention Corp allowlist; k-skill does not override this.\n"
-            "  OPENCLAW_SHOPPING_FORCE_HOSTED=1\n"
-            "      Force the hosted fallback even when Coupang keys are present.\n"
-            "  OPENCLAW_SHOPPING_BASE_URL\n"
-            "      Override the hosted backend base URL. Default upstream target\n"
-            "      is https://a.retn.kr and /v1/public/assist is the public entry.\n"
-            "\n"
-            "When both COUPANG_ACCESS_KEY and COUPANG_SECRET_KEY are missing,\n"
-            "upstream falls back to the hosted Retention Corp backend so this\n"
-            "skill keeps working without Coupang Partners credentials."
-        ),
-    )
-    parser.add_argument(
-        "--repo-dir",
-        default=str(DEFAULT_REPO_DIR),
-        help="Checkout directory for retention-corp/coupang_partners (default: %(default)s).",
-    )
-    parser.add_argument(
-        "--no-clone",
-        action="store_true",
-        help="Do not clone the upstream repository if it is missing; fail with setup guidance instead.",
-    )
-    parser.add_argument(
-        "--update",
-        action="store_true",
-        help="Run git pull --ff-only in an existing upstream checkout before delegating.",
-    )
-    parser.add_argument(
-        "upstream_args",
-        nargs=argparse.REMAINDER,
-        help="Arguments passed to bin/coupang_mcp.py, for example: tools, search 생수, rocket 에어팟.",
-    )
-    args = parser.parse_args(argv)
-    if args.upstream_args and args.upstream_args[0] == "--":
-        args.upstream_args = args.upstream_args[1:]
-    if not args.upstream_args:
-        parser.error("missing upstream command; try: tools, init, search <keyword>, rocket <keyword>, budget <keyword>")
-    return args
-
-
-def upstream_cli_path(repo_dir: pathlib.Path) -> pathlib.Path:
-    return repo_dir / UPSTREAM_CLI
-
-
-def ensure_repo(repo_dir: pathlib.Path, *, clone: bool = True, update: bool = False) -> pathlib.Path:
-    cli_path = upstream_cli_path(repo_dir)
-    if cli_path.exists():
-        if update:
-            run_checked(["git", "-C", str(repo_dir), "pull", "--ff-only"], "failed to update upstream checkout")
-        return cli_path
-
-    if repo_dir.exists():
-        raise BootstrapError(
-            f"{repo_dir} exists but does not look like retention-corp/coupang_partners "
-            f"(missing {UPSTREAM_CLI}). Recreate it with: git clone {UPSTREAM_REPO_URL} {repo_dir}"
-        )
-
-    if not clone:
-        raise BootstrapError(
-            f"Missing retention-corp/coupang_partners checkout at {repo_dir}. "
-            f"Create it with: git clone {UPSTREAM_REPO_URL} {repo_dir}"
-        )
-
-    repo_dir.parent.mkdir(parents=True, exist_ok=True)
-    run_checked(["git", "clone", "--depth", "1", UPSTREAM_REPO_URL, str(repo_dir)], "failed to clone upstream checkout")
-    if not cli_path.exists():
-        raise BootstrapError(f"Cloned {UPSTREAM_REPO_URL}, but {UPSTREAM_CLI} was not found in {repo_dir}")
-    return cli_path
-
-
-def run_checked(command: Sequence[str], context: str) -> None:
-    try:
-        subprocess.run(command, check=True)
-    except FileNotFoundError as exc:
-        raise BootstrapError(f"{context}: required executable not found: {command[0]}") from exc
-    except subprocess.CalledProcessError as exc:
-        raise BootstrapError(f"{context}: {exc}") from exc
-
-
-def build_command(cli_path: pathlib.Path, upstream_args: Sequence[str]) -> list[str]:
-    return [sys.executable, str(cli_path), *upstream_args]
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    args = parse_args(argv)
-    repo_dir = pathlib.Path(args.repo_dir).expanduser().resolve()
-
-    try:
-        cli_path = ensure_repo(repo_dir, clone=not args.no_clone, update=args.update)
-    except BootstrapError as exc:
-        print(f"coupang_partners_mcp.py: {exc}", file=sys.stderr)
-        return 2
-
-    env = os.environ.copy()
-    env.setdefault("COUPANG_MCP_ENDPOINT", DEFAULT_MCP_ENDPOINT)
-    completed = subprocess.run(build_command(cli_path, args.upstream_args), env=env)
-    return int(completed.returncode)
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())