@nomadamas/k-skill 0.1.0

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

@@ -0,0 +1,219 @@
+# Coupang Product Search
+
+## What this skill does
+
+[retention-corp/coupang_partners](https://github.com/retention-corp/coupang_partners) 저장소의 로컬 Coupang MCP 호환 레이어를 사용해 쿠팡 상품 조회 도구를 실행한다. 기존 유지보수형 HF Space MCP 엔드포인트 대신, 이 저장소의 `bin/coupang_mcp.py`가 제공하는 `local://coupang-mcp` 계약을 호출한다.
+
+- 키워드 상품 검색
+- 로켓배송 전용 필터 검색
+- 가격대 범위 검색
+- 상품 비교표 생성
+- 카테고리별 베스트 상품
+- 골드박스 당일 특가
+- 인기 검색어/계절 상품 추천
+
+## 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
+```
+
+프로토콜 호환 버전: MCP `2025-03-26`. 네트워크로 붙는 Streamable HTTP 서버가 아니라, upstream 저장소의 로컬 MCP 호환 CLI가 같은 도구 이름과 JSON-RPC 모양의 payload를 반환한다.
+
+## When to use
+
+- "쿠팡에서 생수 가격 좀 찾아줘"
+- "로켓배송 에어팟 찾아줘"
+- "20만원 이하 키보드 추천해줘"
+- "아이패드 vs 갤럭시탭 비교"
+- "오늘 쿠팡 특가 뭐 있어?"
+- "전자제품 베스트 보여줘"
+
+## 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
+python3 coupang-product-search/scripts/coupang_partners_mcp.py tools
+python3 coupang-product-search/scripts/coupang_partners_mcp.py init
+```
+
+기존 checkout을 명시하거나 CI/검증에서 네트워크 clone을 막으려면:
+
+```bash
+python3 coupang-product-search/scripts/coupang_partners_mcp.py \
+  --repo-dir /path/to/coupang_partners \
+  --no-clone \
+  tools
+python3 coupang-product-search/scripts/coupang_partners_mcp.py \
+  --repo-dir /path/to/coupang_partners \
+  --no-clone \
+  init
+```
+
+### 3. Call tools
+
+구체적인 사용자 요청에 맞춰 upstream CLI 명령을 호출한다. 결과는 `ok`, `data.tool`, `data.payload`, `data.result`를 포함하는 JSON으로 반환된다.
+
+```bash
+# 일반 검색 (키 없이도 hosted fallback으로 작동)
+python3 coupang-product-search/scripts/coupang_partners_mcp.py search "32인치 4K 모니터"
+
+# 로켓배송 필터
+python3 coupang-product-search/scripts/coupang_partners_mcp.py rocket "에어팟"
+
+# 가격대 검색
+python3 coupang-product-search/scripts/coupang_partners_mcp.py budget "키보드" --max-price 100000
+
+# 비교
+python3 coupang-product-search/scripts/coupang_partners_mcp.py compare "아이패드 vs 갤럭시탭"
+
+# 골드박스 (운영자 키가 필요한 upstream 경로)
+python3 coupang-product-search/scripts/coupang_partners_mcp.py goldbox
+```
+
+### 4. (optional) hosted fallback 강제
+
+운영자 키가 있는 상태에서도 hosted fallback 경로를 점검하고 싶으면 `OPENCLAW_SHOPPING_FORCE_HOSTED=1`만 추가하면 된다. `OPENCLAW_SHOPPING_CLIENT_ID`는 upstream이 보내는 기본값 `openclaw-skill`이 현재 Retention Corp allowlist에 등록된 값이므로 별도로 설정하지 않는다.
+
+```bash
+export OPENCLAW_SHOPPING_FORCE_HOSTED=1
+python3 coupang-product-search/scripts/coupang_partners_mcp.py search "에어팟"
+```
+
+### 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": []
+  }
+}
+```
+
+사용자에게 보여줄 때는 다음처럼 짧게 정리한다.
+
+```
+## rocket (상위 후보)
+
+1) LG전자 4K UHD 모니터
+   가격: 397,750원 (참고용)
+   보러가기: https://a.retn.kr/s/...          # hosted fallback shortlink
+   또는:   https://link.coupang.com/a/...     # operator HMAC 경로 딥링크
+
+## normal (상위 후보)
+
+1) 삼성전자 QHD 오디세이 G5 게이밍 모니터
+   가격: 283,000원 (참고용)
+   보러가기: https://a.retn.kr/s/...
+```
+
+## Response policy
+
+- 후보가 여러 개면 상위 3~5개만 짧게 비교한다.
+- 로켓배송/일반배송 구분을 명시한다.
+- 가격/품절/배송 정보는 실시간 변동될 수 있음을 안내한다.
+- upstream checkout, 권한, Coupang Partners 환경변수 문제로 실패하면 실패 원인과 재시도/설정 방법을 짧게 안내한다.
+- **Affiliate 고지(필수)**: 응답에 포함되는 shortlink(`https://a.retn.kr/s/...`)와 직접 coupang 딥링크(`link.coupang.com/...?lptag=AF...`)는 Retention Corp의 쿠팡 파트너스(affiliate) 채널로 트래킹된다. upstream이 돌려주는 `disclosure` 문자열(`"파트너스 활동을 통해 일정액의 수수료를 제공받을 수 있음"`)이 있으면 그대로 노출하고, 없으면 같은 취지의 고지를 답변 말미에 덧붙인다.
+
+## Done when
+
+- `tools`와 `init` 또는 실제 명령으로 retention-corp/coupang_partners 로컬 MCP 계약을 확인했다.
+- 검색 결과가 로켓배송/일반배송으로 구분되어 정리되었다.
+- 사용자 니즈에 맞는 추천 TOP 3이 제시되었다.
+- 가격/배송 정보와 변동 가능성 안내가 포함되었다.
+- affiliate 고지(disclosure)가 답변에 포함되었다.
+- 돌쇠의 장바구니 요청이면 선택 옵션/수량이 실제 장바구니에 담긴 것을 확인했다.
+- 돌쇠의 구매 요청이면 `clarify` 승인 후 주문번호와 결제 상태를 확인했다.

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

@@ -0,0 +1,146 @@
+#!/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())

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

@@ -0,0 +1,10 @@
+{
+  "name": "coupang-product-search",
+  "description": "retention-corp/coupang_partners의 로컬 Coupang MCP 호환 레이어로 쿠팡 상품 검색, 로켓배송 필터, 가격대 검색, 상품 비교, 베스트 상품, 골드박스 특가를 조회한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "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"
+}

package/skills/court-auction-notice-search/instruction.md

@@ -0,0 +1,201 @@
+# Court Auction Notice Search
+
+## What this skill does
+
+대한민국 법원이 운영하는 공식 **법원경매정보** 사이트(`courtauction.go.kr`) 의 매각공고와 사건정보를 에이전트가 활용할 수 있는 JSON 형태로 변환해서 돌려준다.
+
+- 공식 OPEN API가 없어 사이트 내부의 WebSquare JSON XHR endpoint를 그대로 호출한다.
+- 1차 transport 는 직접 HTTP다. Workflow C 자유검색에서 raw-HTTP WAF성 HTTP 400이 날 때만 Playwright fallback 으로 전환하며, 명시적 차단(`BLOCKED`/`ipcheck=false`)은 기본적으로 중단한다 (`rebrowser-playwright` 또는 `playwright-core` 가 있을 때만).
+- **기본 조회는 실제 브라우저 없이 동작한다.** 매각공고/사건/물건 조회의 정상 경로는 직접 HTTP다. 브라우저는 Workflow C 자유검색이 WAF성 HTTP 400을 낼 때만 fallback으로 쓰이고, 그때 권장 순서는 사용자가 띄운 BrowserOS/runtime CDP → (닿지 않으면) Chrome CDP → 로컬 Playwright launch다.
+- 사이트는 **IP 단위 봇 차단** 이 매우 공격적이다 (16회/30초 정도면 1시간 차단). 이 패키지는 호출 간 최소 2초 jitter, 세션당 호출 budget(기본 10회), `data.ipcheck === false` 즉시 throw 로 보수적으로 동작한다.
+- **참고용 도구**다. 실제 입찰 전에는 반드시 법원 원문 매각공고를 다시 확인해야 한다.
+
+## When to use
+
+- "오늘/내일 어디서 부동산 경매 열려?"
+- "서울중앙지방법원 2026-04-27 매각공고 보여줘"
+- "기일입찰 vs 기간입찰만 나눠서 보여줘"
+- "이 매각공고 안의 사건번호/용도/주소/감정평가액 다 보여줘"
+- "사건번호 2024타경100001 진행 상황 알려줘"
+- "서울 강남구 아파트 최저가 5억 이하 유찰 1회 이상 물건 찾아줘"
+- "법원사무소 코드 표 줘"
+
+## When not to use
+
+- 동산(자동차·중기) 경매 (이번 v1 범위 밖)
+- 특정 매각기일 날짜의 모든 법원 일정을 한 번에 (Workflow D 별도 follow-up 이슈)
+- 매각물건 사진(전경/개황/내부) URL 노출 (별도 follow-up 이슈)
+- 매각물건명세서 / 현황조사서 / 감정평가서 PDF 다운로드 (별도 follow-up 이슈)
+- 입찰서 자동 작성·자동 제출 (지원하지 않는다, 입찰은 반드시 법원에서 사람이 직접)
+
+## Inputs
+
+- `date` — 매각기일 월(YYYY-MM 또는 YYYYMM) 또는 특정일(YYYY-MM-DD 또는 YYYYMMDD). 필수. 실제 사이트 검색 버튼은 월(YYYYMM) 단위로 조회하므로 특정일 입력은 월 조회 후 해당 일자만 필터링한다.
+- `courtCode` — 법원사무소코드 (예: `B000210` = 서울중앙지방법원). 비우면 전체. `getCourtCodes()` 또는 `codes courts` 로 받아온다.
+- `bidType` — `date` (= 기일입찰, code 000331) 또는 `period` (= 기간입찰, code 000332). 빈값이면 둘 다.
+- `caseNumber` — 사건번호. `2024타경100001` 형식 권장. `2024-100001` 도 받아서 `2024타경100001` 로 정규화한다.
+
+## Mandatory honest framing
+
+이 스킬은 사용자에게 다음 사실을 항상 알려야 한다.
+
+1. 데이터는 법원경매정보 사이트의 공개 정보를 그대로 옮긴 것이며 **실제 입찰 전에 법원 원문을 재확인**해야 한다.
+2. 사이트는 자동화 호출에 매우 민감해서 **빠른 연속 조회 시 IP가 1시간 차단**될 수 있다. 차단되면 같은 IP에서는 약 1시간을 기다려야 한다.
+3. 가격(감정평가액·최저매각가격)·매각기일·매각장소는 **공고 시점 기준** 이며 정정·취하·연기로 변경될 수 있다 (`correctionCount`, `cancellationCount` 필드를 참고).
+4. 본 스킬은 **read-only**다. 입찰 자체는 자동화하지 않는다.
+
+## Official surfaces
+
+- 법원경매정보 메인: `https://www.courtauction.go.kr`
+- 부동산매각공고 진입: `https://www.courtauction.go.kr/pgj/index.on?w2xPath=/pgj/ui/pgj100/PGJ143M01.xml&pgjId=143M01`
+- 경매사건검색 진입: `https://www.courtauction.go.kr/pgj/index.on?w2xPath=/pgj/ui/pgj100/PGJ159M00.xml&pgjId=159M00`
+- 직접 호출 endpoint (이 스킬이 사용하는 것):
+  - `POST /pgj/pgj143/selectRletDspslPbanc.on` — 매각공고 목록
+  - `POST /pgj/pgj143/selectRletDspslPbancDtl.on` — 매각공고 상세 (사건/물건 펼치기)
+  - `POST /pgj/pgj15A/selectAuctnCsSrchRslt.on` — 사건 단건 조회
+  - `POST /pgj/pgjsearch/searchControllerMain.on` — 물건 자유 조건검색 (PGJ151F00 → PGJ151M01)
+  - `POST /pgj/pgjComm/selectCortOfcCdLst.on` — 법원사무소코드 전체
+
+## Workflow A — 매각공고 → 사건/물건 펼치기
+
+1. 사용자에게 **매각기일(YYYY-MM-DD)** 과 (선택) 법원·입찰구분을 받는다.
+2. `searchSaleNotices({ date, courtCode, bidType })` 호출 → 그 날·그 법원의 매각공고 카드 목록.
+3. 사용자가 카드를 고르면 카드 객체(또는 `raw`)를 그대로 `getSaleNoticeDetail(notice)` 에 넘긴다.
+4. 응답의 `items[]` 가 `caseNumber`, `usage`, `address`, `appraisedPrice`, `minimumSalePrice`, `remarks` 를 가진다 (이슈 본문이 명시한 4필드 모두 포함).
+5. 가격은 원 단위 정수다. 사용자에게 보여줄 때는 한국식 천단위 콤마 + 억/만 단위 환산을 같이 제시한다.
+
+## Workflow B — 사건번호 직접 조회
+
+1. 사용자에게 **법원사무소코드** + **사건번호(2024타경100001)** 를 받는다.
+2. `getCaseByCaseNumber({ courtCode, caseNumber })` 호출.
+3. `found:false / status:204` 면 사건이 존재하지 않거나 비공개. 사건번호 형식·법원이 맞는지 사용자에게 다시 확인한다.
+4. `found:true` 면 `caseInfo`(사건명·접수일·청구액·재판부·진행상태), `items[]`(매각목적물 — 주소/배당요구종기), `schedule[]`(매각기일별 최저가/감정가/결과), `claimDeadline`, `relatedCases`, `stakeholders` 가 채워진다.
+
+## Workflow C — 부동산 물건 자유 조건검색
+
+1. 사용자의 조건을 `searchProperties()` 입력으로 매핑한다.
+   - `region: { sido, sigungu, dong }` — 코드 또는 대표 정적 sido 코드테이블의 한국어명. 지역을 주면 지번주소 검색(`cortStDvs:"2"`)으로, 지역이 없으면 매각공고 모드(`cortStDvs:"1"`)로 조회한다. 시군구/읍면동은 정적 표가 없으므로 코드로 직접 전달(예: `{ sido:"11", sigungu:"11680", dong:"11680101" }`)한다.
+   - `usage: { large, medium, small }` — 용도 대/중/소분류 코드(5자리, 예: 건물=`20000`) 또는 대분류 한국어명(`토지`/`건물`/`차량및운송장비`/`기타`).
+   - `priceRange` — 최저매각가격 원 단위 `{ min, max }` (실수 허용)
+   - `appraisedPriceRange` — 감정평가액 원 단위 `{ min, max }` (실수 허용)
+   - `saleDate` — `{ from, to }`
+   - `flbdCount` — 유찰횟수 `{ min, max }` **정수만**
+   - `area` — 면적(㎡) `{ min, max }` (실수 허용)
+   - `pageSize` — 페이지당 결과 수, upstream PGJ151 드롭다운에서 확인된 `10`/`20`/`50`/`100` 중 하나(기본 10). `1` 등 임의 값은 live endpoint 가 HTTP 400을 반환하므로 로컬에서 거부한다.
+2. `searchProperties({ ... })` 호출 → `POST /pgj/pgjsearch/searchControllerMain.on`.
+   - 1차로 direct HTTP 시도. Workflow C raw-HTTP WAF의 HTTP 400을 만나면 자동으로 Playwright fallback 으로 재시도한다. fallback 을 끄려면 `{ fallback: false }`. `BLOCKED`(`ipcheck=false`)는 사이트의 명시적 차단 신호이므로 기본적으로 즉시 중단하며, 사용자가 위험을 이해하고 명시적으로 `{ fallbackOnBlocked: true }` 를 준 경우에만 재시도한다.
+3. 응답의 `items[]` 는 핵심 raw 컬럼을 영문 키로 정규화한다:
+   - `saNo` → `caseNumber`, `srnSaNo`/`printCsNo` → `displayCaseNumber`
+   - `mokmulSer`/`maemulSer` → `itemNumber`
+   - `hjguSido + hjguSigu + hjguDong + daepyoLotno + buldNm` → `address`
+   - `gamevalAmt` → `appraisedPrice`, `minmaePrice` → `minimumSalePrice`
+   - `yuchalCnt` → `flbdCount`, `mulStatcd` → `statusCode`, `jinstatCd` → `progressStatusCode`
+   - `boCd` → `courtCode`, `jiwonNm` → `courtName`, `jpDeptNm` → `judgeDeptName`
+   - `lclsUtilCd/mclsUtilCd/sclsUtilCd` → `usageCodes.{large,medium,small}`
+   - `srchHjguSidoCd/SiguCd/DongCd` → `regionCodes.{sido,sigungu,dong}`
+   - `xCordi/yCordi` → `coordinates`, `wgs84Xcordi/Ycordi` → `coordinatesWgs84`
+   - `buldList/areaList/jimokList` → `buildingList/areaList/landCategoryList`
+   - `pjbBuldList` → `propertyDescription`, `mulBigo` → `remarks`
+4. `getUsageCodes()` 는 4개 대분류(`10000=토지`, `20000=건물`, `30000=차량및운송장비`, `40000=기타`)와 일부 대표 중/소분류를 정적으로 반환한다. `getRegionCodes()` 는 19개 시도 + 코드만 반환한다. 시군구/읍면동은 upstream cascade XHR이 안정적이지 않아 정적 표에 포함하지 않으며 raw 코드를 그대로 전달하면 된다. 알 수 없는 값은 fail-open으로 통과한다.
+5. **Same-name usage codes 보호**: `resolveUsageCode("아파트", "large")` 처럼 입력 이름이 다른 level 에만 존재하면, 같은 이름의 medium/small 코드를 잘못 리턴하지 않고 fail-open(원문 통과)한다.
+
+## Throttling and call-budget rules
+
+- 호출 간 최소 2초 (기본). 더 늘리려면 `--min-delay-ms 3000`.
+- 기본 세션 budget 은 **10회**. 더 많은 조회가 필요하면 새 세션을 열거나 (`new CourtAuctionHttpClient`) `maxCallsPerSession` 을 명시적으로 늘린다.
+- 차단(`data.ipcheck === false`)을 만나면 `BLOCKED` 에러를 즉시 throw 하고 멈춘다. 자동 retry 하지 않는다 (차단 연장 위험).
+- 차단된 IP는 **약 1시간** 후 자연 복구된다. 그 사이에는 다른 IP/네트워크에서 작업하거나 사람이 브라우저로 사이트에 접속해서 차단 해제 화면을 거친다.
+- **Workflow C 자유검색은 사이트 WAF 가 raw HTTP 호출을 더 엄격하게 차단**한다. `searchProperties()` 는 1차 direct HTTP에서 WAF성 HTTP 400을 만났을 때만 Playwright fallback 으로 재시도한다. 명시적 차단(`BLOCKED`/`ipcheck=false`)은 기본적으로 즉시 중단하며, 사용자가 위험을 이해하고 `fallbackOnBlocked:true` 를 준 경우에만 재시도한다. Playwright fallback 모듈(`rebrowser-playwright` 또는 `playwright-core`)이 없으면 첫 HTTP 400 실패가 그대로 throw 된다.
+- searchProperties 는 같은 Playwright 클라이언트로 연속 호출하면 **10~15회 간격 호출에서 안정**하다. 그 이상 burst 호출이 필요하면 호출 사이 3~5초 sleep 을 두고 새 클라이언트를 열어라.
+
+## Node.js example
+
+```js
+const {
+  searchSaleNotices,
+  getSaleNoticeDetail,
+  getCaseByCaseNumber,
+  getCourtCodes
+} = require("court-auction-notice-search");
+
+async function main() {
+  const courts = await getCourtCodes();
+  console.log(`법원사무소 ${courts.count}개 로드됨`);
+
+  const notices = await searchSaleNotices({
+    date: "2026-04-27",
+    courtCode: "B000210",
+    bidType: "date"
+  });
+  console.log(`서울중앙지방법원 매각공고 ${notices.count}건`);
+
+  if (notices.items.length > 0) {
+    const detail = await getSaleNoticeDetail(notices.items[0]);
+    for (const item of detail.items) {
+      console.log(
+        `${item.caseNumber} (${item.usage}) — 감정 ${item.appraisedPrice}원 / 최저 ${item.minimumSalePrice}원`
+      );
+      console.log(`  주소: ${item.address}`);
+    }
+  }
+
+  const caseInfo = await getCaseByCaseNumber({
+    courtCode: "B000210",
+    caseNumber: "2024타경100001"
+  });
+  if (caseInfo.found) {
+    console.log(`사건명: ${caseInfo.caseInfo.caseName}`);
+    console.log(`매각기일 횟수: ${caseInfo.schedule.length}`);
+  }
+}
+
+main().catch((error) => {
+  if (error.code === "BLOCKED") {
+    console.error("[BLOCKED] 사이트가 1시간 차단했습니다. 다른 IP에서 다시 시도하거나 1시간 뒤 재시도하세요.");
+  } else {
+    console.error(error);
+  }
+  process.exitCode = 1;
+});
+```
+
+## CLI example
+
+```bash
+# 1. 법원사무소 코드표
+court-auction-notice-search codes courts --pretty | head -40
+
+# 2. 입찰구분 (정적 코드)
+court-auction-notice-search codes bid-types --pretty
+court-auction-notice-search codes usages --pretty
+court-auction-notice-search codes regions --pretty
+
+# 3. 매각공고 목록
+court-auction-notice-search notices --date 2026-04 --court-code B000210 --bid-type date --pretty
+
+# 4. 매각공고 상세 — list 응답의 row 의 raw 필드를 그대로 detail 호출에 사용한다.
+#    (CLI 단발 호출에서는 list -> detail 으로 결과를 파이프할 수 있도록 jq 등을 함께 사용)
+
+# 5. 사건번호 직접 조회
+court-auction-notice-search case --court-code B000210 --case-number "2024타경100001" --pretty
+
+# 6. 자유 조건검색
+court-auction-notice-search search --sido 서울특별시 --sigungu 11680 --usage-large 건물 --usage-medium 21200 \
+  --price-min 100000000 --price-max 500000000 --sale-from 2026-05-01 --sale-to 2026-05-20 --pretty
+```
+
+## Block / Error handling
+
+- `error.code === "BLOCKED"` — `data.ipcheck === false`. 1시간 대기 후 다른 IP에서 재시도. 사용자에게 차단 사실과 대기 안내를 그대로 전달한다.
+- `error.code === "BUDGET_EXCEEDED"` — 세션 budget 초과. 의도적인 안전장치다. 정말 필요하면 `--max-calls 20` 같이 늘리지만 차단 위험을 함께 안내한다.
+- `error.code === "UPSTREAM_ERROR"` — 사이트가 일반적인 에러를 돌려준 경우. 세션 만료 또는 잘못된 jdbnCd 가 가장 흔한 원인. warmup 부터 다시.
+- `error.code === "NETWORK_ERROR"` — 타임아웃/연결 실패.
+- `error.code === "PLAYWRIGHT_UNAVAILABLE"` — Playwright fallback 을 명시적으로 쓰려는데 모듈이 깔려있지 않음. `npm i rebrowser-playwright` 또는 `npm i playwright-core` 로 해결.
+
+## Done when
+
+- 사용자에게 IP 차단 위험과 "참고용·실제 입찰 전 법원 원문 재확인" 고지를 했다.
+- 매각공고를 펼쳐서 `caseNumber/usage/address/appraisedPrice/minimumSalePrice` 가 채워진 JSON을 돌려줬다.
+- 사건번호로 직접 조회한 경우, `found:false` 일 때 사용자가 후속 조치를 알 수 있도록 안내했다.
+- 차단 발생 시 자동 재시도하지 않고 즉시 멈췄다.
+- 작업 후 호출 budget 이 남아있는지 사용자에게 알려서 추가 호출 여지를 명시했다.

package/skills/court-auction-notice-search/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "court-auction-notice-search",
+  "description": "Browse 대법원경매정보(courtauction.go.kr) 부동산 매각공고 by 매각기일·법원·기일/기간 입찰, expand each notice into 사건번호·용도·주소·감정평가액·최저매각가, search property items by free conditions(지역·용도·가격·면적·유찰횟수), and look up a case directly by 법원+사건번호. Read-only, slow-by-design (~2s/call) to avoid IP blocks. 돌쇠에서는 가능한 가장 가까운 합법적 공식 단계까지 준비한다.",
+  "profiles": [
+    "browser",
+    "hard-boundary"
+  ],
+  "frontmatter": "name: court-auction-notice-search\ndescription: Browse 대법원경매정보(courtauction.go.kr) 부동산 매각공고 by 매각기일·법원·기일/기간 입찰, expand each notice into 사건번호·용도·주소·감정평가액·최저매각가, search property items by free conditions(지역·용도·가격·면적·유찰횟수), and look up a case directly by 법원+사건번호. Read-only, slow-by-design (~2s/call) to avoid IP blocks. 돌쇠에서는 가능한 가장 가까운 합법적 공식 단계까지 준비한다.\nlicense: MIT\nmetadata:\n  category: real-estate\n  locale: ko-KR\n  phase: v1"
+}