@nomadamas/k-skill 0.1.0

package/skills/nts-business-registration/scripts/nts_business_registration.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from typing import Any
+
+PROXY_BASE_URL_ENV_VAR = "KSKILL_PROXY_BASE_URL"
+DEFAULT_PROXY_BASE_URL = "https://k-skill-proxy.nomadamas.org"
+PROXY_DOWN_MSG = "설정된 k-skill-proxy 서버가 응답하지 않습니다. 잠시 후 재시도하거나 운영자에게 문의하세요."
+PROXY_KEY_NOT_CONFIGURED_MSG = "k-skill-proxy에 필요한 API 키가 설정되어 있지 않습니다. 운영자에게 문의하세요."
+BATCH_LIMIT = 100
+VALIDATE_TEXT_FIELD_LIMITS = {
+    "p_nm": 30,
+    "p_nm2": 30,
+    "b_nm": 200,
+    "b_sector": 100,
+    "b_type": 100,
+    "b_adr": 500,
+}
+
+
+class ApiError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int | None = None, url: str | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.url = url
+
+
+def _text_or_none(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def resolve_proxy_base_url(explicit_base_url: str | None = None, env: dict[str, str] | None = None) -> str:
+    env = os.environ if env is None else env
+    candidate = _text_or_none(explicit_base_url or env.get(PROXY_BASE_URL_ENV_VAR))
+    if candidate and candidate.casefold() in {"off", "false", "0", "disable", "disabled", "none"}:
+        raise ValueError("KSKILL_PROXY_BASE_URL 가 비활성화되어 있습니다.")
+    if candidate and candidate != "replace-me":
+        return candidate.rstrip("/")
+    return DEFAULT_PROXY_BASE_URL
+
+
+def normalize_business_number(value: Any) -> str:
+    raw = _text_or_none(value)
+    if not raw:
+        raise ValueError("사업자등록번호(b_no)를 입력하세요.")
+    normalized = re.sub(r"\D", "", raw)
+    if not re.fullmatch(r"\d{10}", normalized):
+        raise ValueError("사업자등록번호는 숫자 10자리여야 합니다.")
+    return normalized
+
+
+def normalize_start_date(value: Any) -> str:
+    raw = _text_or_none(value)
+    if not raw:
+        raise ValueError("개업일자(start_dt)를 YYYYMMDD 형식으로 입력하세요.")
+    normalized = re.sub(r"\D", "", raw)
+    if not re.fullmatch(r"\d{8}", normalized):
+        raise ValueError("개업일자는 YYYYMMDD 형식이어야 합니다.")
+    try:
+        dt.date(int(normalized[:4]), int(normalized[4:6]), int(normalized[6:8]))
+    except ValueError as error:
+        raise ValueError("개업일자는 유효한 날짜여야 합니다.") from error
+    return normalized
+
+
+def normalize_validate_text(value: Any, field_name: str, *, required: bool = False) -> str | None:
+    text = _text_or_none(value)
+    if not text:
+        if required:
+            raise ValueError(f"{field_name}을(를) 입력하세요.")
+        return None
+    max_length = VALIDATE_TEXT_FIELD_LIMITS.get(field_name)
+    if max_length and len(text) > max_length:
+        raise ValueError(f"{field_name}은(는) {max_length}자 이하여야 합니다.")
+    return text
+
+
+def normalize_corp_no(value: Any) -> str | None:
+    raw = _text_or_none(value)
+    if not raw:
+        return None
+    normalized = re.sub(r"\D", "", raw)
+    if not re.fullmatch(r"\d{13}", normalized):
+        raise ValueError("corp_no는 숫자 13자리여야 합니다.")
+    return normalized
+
+
+def build_status_payload(business_numbers: list[Any]) -> dict[str, list[str]]:
+    numbers = [normalize_business_number(value) for value in business_numbers]
+    numbers = list(dict.fromkeys(numbers))
+    if not numbers:
+        raise ValueError("사업자등록번호를 1개 이상 입력하세요.")
+    if len(numbers) > BATCH_LIMIT:
+        raise ValueError("한 번에 조회할 수 있는 사업자등록번호는 100개까지입니다.")
+    return {"b_no": numbers}
+
+
+def build_validate_business(**kwargs: Any) -> dict[str, str]:
+    p_nm = normalize_validate_text(kwargs.get("p_nm"), "p_nm", required=True)
+
+    business = {
+        "b_no": normalize_business_number(kwargs.get("b_no")),
+        "start_dt": normalize_start_date(kwargs.get("start_dt")),
+        "p_nm": p_nm,
+    }
+
+    for key in ("p_nm2", "b_nm", "b_sector", "b_type", "b_adr"):
+        value = normalize_validate_text(kwargs.get(key), key)
+        if value:
+            business[key] = value
+
+    corp_no = normalize_corp_no(kwargs.get("corp_no"))
+    if corp_no:
+        business["corp_no"] = corp_no
+    return business
+
+
+def build_validate_payload(businesses: list[dict[str, Any]]) -> dict[str, list[dict[str, str]]]:
+    if not businesses:
+        raise ValueError("진위확인 대상 businesses를 1개 이상 입력하세요.")
+    if len(businesses) > BATCH_LIMIT:
+        raise ValueError("한 번에 진위확인할 수 있는 사업자는 100개까지입니다.")
+    return {"businesses": [build_validate_business(**business) for business in businesses]}
+
+
+def read_json_response(request: urllib.request.Request) -> dict[str, Any]:
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as error:
+        body = error.read().decode("utf-8", errors="replace")
+        try:
+            payload = json.loads(body)
+        except json.JSONDecodeError:
+            payload = None
+        if error.code == 503 and isinstance(payload, dict) and payload.get("error") == "upstream_not_configured":
+            raise ApiError(PROXY_KEY_NOT_CONFIGURED_MSG, status_code=error.code, url=getattr(error, "url", None)) from error
+        if isinstance(payload, dict) and payload.get("message"):
+            raise ApiError(str(payload["message"]), status_code=error.code, url=getattr(error, "url", None)) from error
+        raise ApiError(f"NTS business proxy request failed with HTTP {error.code}", status_code=error.code, url=getattr(error, "url", None)) from error
+    except urllib.error.URLError as error:
+        raise ApiError(f"{PROXY_DOWN_MSG} (상세: {error.reason})") from error
+
+
+def _post_json(path: str, payload: dict[str, Any], *, base_url: str | None = None, read_json: Any = read_json_response) -> dict[str, Any]:
+    resolved_base_url = resolve_proxy_base_url(base_url)
+    request = urllib.request.Request(
+        f"{resolved_base_url}{path}",
+        data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+        headers={
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": "k-skill-nts-business-registration/1.0",
+        },
+        method="POST",
+    )
+    return read_json(request)
+
+
+def query_status(business_numbers: list[Any], *, base_url: str | None = None, read_json: Any = read_json_response) -> dict[str, Any]:
+    return _post_json("/v1/nts-business/status", build_status_payload(business_numbers), base_url=base_url, read_json=read_json)
+
+
+def validate_businesses(businesses: list[dict[str, Any]], *, base_url: str | None = None, read_json: Any = read_json_response) -> dict[str, Any]:
+    return _post_json("/v1/nts-business/validate", build_validate_payload(businesses), base_url=base_url, read_json=read_json)
+
+
+def _parse_business_json(value: str) -> dict[str, Any]:
+    payload = json.loads(value)
+    if not isinstance(payload, dict):
+        raise argparse.ArgumentTypeError("business JSON must be an object")
+    return payload
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="NTS business registration status/authenticity helper")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    status = subparsers.add_parser("status", help="사업자등록번호 상태조회")
+    status.add_argument("--b-no", action="append", required=True, help="사업자등록번호(10자리; 하이픈 허용). 여러 번 지정 가능")
+    status.add_argument("--proxy-base-url")
+
+    validate = subparsers.add_parser("validate", help="사업자등록정보 진위확인")
+    validate.add_argument("--business-json", action="append", type=_parse_business_json, required=True, help='예: {"b_no":"1234567890","start_dt":"20200101","p_nm":"홍길동"}')
+    validate.add_argument("--proxy-base-url")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "status":
+            print(json.dumps(query_status(args.b_no, base_url=args.proxy_base_url), ensure_ascii=False, indent=2))
+            return 0
+        if args.command == "validate":
+            print(json.dumps(validate_businesses(args.business_json, base_url=args.proxy_base_url), ensure_ascii=False, indent=2))
+            return 0
+    except (ValueError, ApiError) as error:
+        print(json.dumps({"error": str(error)}, ensure_ascii=False, indent=2), file=sys.stderr)
+        return 1
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/nts-business-registration/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "nts-business-registration",
+  "description": "국세청 사업자등록정보 진위확인 및 사업자등록 상태조회를 공공데이터포털 API(k-skill-proxy 경유)로 수행한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "action:submission"
+  ],
+  "frontmatter": "name: nts-business-registration\ndescription: 국세청 사업자등록정보 진위확인 및 사업자등록 상태조회를 공공데이터포털 API(k-skill-proxy 경유)로 수행한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: business\n  locale: ko-KR\n  phase: v1"
+}

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

@@ -0,0 +1,54 @@
+# 국세청 고액·상습체납자 명단공개 검색
+
+## What this skill does
+
+국세청 누리집의 **고액·상습체납자 명단공개**(국세기본법 제85조의5)를 무인증 공개 검색으로 직접 조회한다.
+
+- 법인 명단: 법인명으로 검색 — 공개년도·법인명·대표자·업종·소재지·총 체납액·세목·체납건수·체납요지
+- 개인 명단: 상호로 검색 — 공개년도·성명·연령·상호·직업·주소·총 체납액·세목·체납요지
+
+이 명단에는 **사업자등록번호가 수록되지 않는다.** 상호·법인명 문자열 일치 후보의 공개 사실만 나열하며, 동명 상호 가능성은 사용자가 판단한다.
+
+## Design principles
+
+- 점수·등급·해석 라벨을 만들지 않는다. 공개된 사실 + 출처만 담는다.
+- 인증 없이 동작하는 공개 read-only 검색이므로 프록시를 거치지 않고 사용자 머신에서 직접 호출한다.
+- HTML 스크래핑이므로 페이지 마커가 어긋나면 즉시 `unavailable`로 강등하고 수동 확인 경로를 안내한다.
+
+## When to use
+
+- "이 회사(거래처/의뢰인) 국세 체납 명단공개에 올라 있어?"
+- "상호로 고액·상습체납자 명단 대조해줘"
+
+## Prerequisites
+
+- 인터넷 연결, `python3` (stdlib만 사용 — 추가 의존성 없음)
+- `scripts/nts_tax_delinquency.py` helper
+
+## Credential requirements
+
+- 없음. 무인증 공개 검색이다.
+
+## Inputs
+
+- `--name`: 상호·법인명 — 필수 (명단에 사업자등록번호가 없어 번호로는 검색 불가)
+
+## Privacy boundary
+
+- 입력한 상호·법인명은 국세청 누리집으로 전송된다.
+- 명단공개 자료에 사업자등록번호가 없어 상호·법인명 문자열 일치의 공개 사실만 나열한다.
+
+## CLI examples
+
+```bash
+python3 nts-tax-delinquency/scripts/nts_tax_delinquency.py --name "○○건설"
+```
+
+## Failure modes
+
+- `unavailable` + 안내: 상호 미입력, 네트워크 오류, 페이지 구조 변경 추정 — 수동 확인 URL 제공.
+- 0건: 두 명단 모두 매치 없음 (`match_count: 0`).
+
+## Official surfaces
+
+- 명단공개 검색: `https://www.nts.go.kr/nts/ad/openInfo/selectList.do`

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

@@ -0,0 +1,150 @@
+"""NTS high-amount/habitual tax-delinquent disclosure search (unauthenticated).
+
+국세청 고액·상습체납자 명단공개를 nts.go.kr 공개 검색으로 직접 조회한다.
+인증키가 필요 없는 공개 read-only endpoint이므로 프록시를 거치지 않는다.
+
+The disclosure list does NOT contain business registration numbers, so this is a
+trade-name / corporate-name string match only — it cannot assert that a hit is
+the same entity as a given business number.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+URL = "https://www.nts.go.kr/nts/ad/openInfo/selectList.do"
+SOURCE = ("국세청 고액·상습체납자 명단공개 검색 — nts.go.kr 누리집 공개 검색 "
+          "(무인증, www.nts.go.kr/nts/ad/openInfo/selectList.do)")
+MANUAL_NOTE = f"수동 확인: 브라우저에서 {URL} 접속 후 명단공개 검색"
+USER_AGENT = ("Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+              "(KHTML, like Gecko) Chrome/126.0 Safari/537.36")
+KST = dt.timezone(dt.timedelta(hours=9))
+
+CORP_COLUMNS = ("no", "공개년도", "법인명", "대표자", "업종", "법인소재지",
+                "대표자주소", "총체납액", "세목", "납기", "체납건수", "체납요지")
+INDIV_COLUMNS = ("no", "공개년도", "성명", "연령", "상호", "직업(업종)", "체납자주소",
+                 "총체납액", "세목", "납기", "체납건수", "체납요지")
+
+IDENTITY_NOTE = ("명단공개 자료에는 사업자등록번호가 수록되지 않아 입력 사업자번호와의 "
+                 "동일성은 확인할 수 없다 — 상호·법인명 문자열 일치 후보의 공개 사실만 "
+                 "나열하며, 동명 상호일 가능성은 사용자가 판단한다.")
+
+_HEADING_MARKER = "고액상습체납자"
+_ZERO_MARKER = "조회된 데이터가 없습니다"
+
+
+class StructureChanged(RuntimeError):
+    """페이지 구조가 기대 마커와 다름 — 우아한 강등 트리거."""
+
+
+def _now_iso() -> str:
+    return dt.datetime.now(KST).isoformat(timespec="seconds")
+
+
+def _envelope(status: str, *, result: dict | None = None, note: str | None = None) -> dict:
+    return {
+        "source": SOURCE,
+        "looked_up_at": _now_iso(),
+        "status": status,
+        "result": result,
+        "origin": "unauthenticated-public",
+        "note": note,
+    }
+
+
+def _strip_tags(fragment: str) -> str:
+    return re.sub(r"\s+", " ", re.sub(r"<[^>]+>", " ", fragment)).strip()
+
+
+def parse_rows(html: str, columns: tuple) -> list[dict]:
+    if _HEADING_MARKER not in html.replace(" ", ""):
+        raise StructureChanged("명단공개 페이지 마커(고액상습체납자) 미발견")
+    if _ZERO_MARKER in html:
+        return []
+    cells = [_strip_tags(td) for td in re.findall(r"<td[^>]*>(.*?)</td>", html, re.S)]
+    if not cells or len(cells) % len(columns) != 0:
+        raise StructureChanged(f"표 셀 수({len(cells)})가 컬럼 수({len(columns)})의 배수가 아님")
+    return [dict(zip(columns, cells[i:i + len(columns)]))
+            for i in range(0, len(cells), len(columns))]
+
+
+def _post(data: dict[str, str], *, opener: Any = None) -> str:
+    request = urllib.request.Request(
+        URL,
+        data=urllib.parse.urlencode(data).encode("utf-8"),
+        headers={
+            "User-Agent": USER_AGENT,
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        method="POST",
+    )
+    open_fn = opener or urllib.request.urlopen
+    with open_fn(request, timeout=20) as response:
+        status = getattr(response, "status", 200)
+        if status != 200:
+            raise StructureChanged(f"HTTP {status}")
+        return response.read().decode("utf-8", errors="replace")
+
+
+def _search(tcd: str, search_type: str, value: str, columns: tuple, *, opener: Any = None) -> list[dict]:
+    html = _post({
+        "tcd": tcd,
+        "searchType": search_type,
+        "searchValue": value,
+        "searchYear": "",
+        "currPage": "1",
+        "pageIndex": "100",
+        "search_order": "1",
+    }, opener=opener)
+    return parse_rows(html, columns)
+
+
+def lookup(name: str, *, opener: Any = None) -> dict:
+    """고액·상습체납자 명단공개 대조 — 법인 명단(법인명)·개인 명단(상호) 각 1회."""
+    if not (name or "").strip():
+        return _envelope("unavailable",
+                         note=("명단공개 자료에 사업자등록번호가 수록되지 않아 상호·법인명 없이 "
+                               f"검색할 수 없습니다. --name 으로 상호를 지정하세요. {MANUAL_NOTE}"))
+    name = name.strip()
+    try:
+        corp_rows = _search("1", "1", name, CORP_COLUMNS, opener=opener)
+        indiv_rows = _search("2", "3", name, INDIV_COLUMNS, opener=opener)
+    except urllib.error.URLError as err:
+        return _envelope("unavailable", note=f"네트워크 오류: {err.reason}. {MANUAL_NOTE}")
+    except StructureChanged as err:
+        return _envelope("unavailable", note=f"페이지 구조 변경 추정({err}). {MANUAL_NOTE}")
+    except Exception as err:  # 경계 계약: 어떤 오류든 강등, 크래시 금지
+        return _envelope("unavailable", note=f"예상 외 오류({type(err).__name__}). {MANUAL_NOTE}")
+
+    result = {
+        "query_name": name,
+        "list_basis": "국세청 고액·상습체납자 명단공개 (국세기본법 제85조의5)",
+        "corporate_list": {"searched_by": "법인명", "match_count": len(corp_rows), "matches": corp_rows},
+        "individual_list": {"searched_by": "상호", "match_count": len(indiv_rows), "matches": indiv_rows},
+        "identity_note": IDENTITY_NOTE,
+    }
+    return _envelope("ok", result=result)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="국세청 고액·상습체납자 명단공개 검색 (무인증)")
+    parser.add_argument("--name", required=True, help="상호·법인명 — 필수 (명단에 사업자번호 없음)")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    print(json.dumps(lookup(args.name), ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/nts-tax-delinquency/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "nts-tax-delinquency",
+  "description": "국세청 고액·상습체납자 명단공개를 nts.go.kr 공개 검색으로 조회한다. 상호·법인명으로 법인 명단과 개인 명단을 대조해 공개된 체납 사실(총 체납액·세목·체납요지 등)을 나열한다. 인증키 불필요. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "action:submission"
+  ],
+  "frontmatter": "name: nts-tax-delinquency\ndescription: 국세청 고액·상습체납자 명단공개를 nts.go.kr 공개 검색으로 조회한다. 상호·법인명으로 법인 명단과 개인 명단을 대조해 공개된 체납 사실(총 체납액·세목·체납요지 등)을 나열한다. 인증키 불필요. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: business\n  locale: ko-KR\n  phase: v1"
+}

package/skills/ohou-today-deal/instruction.md

@@ -0,0 +1,182 @@
+# 오늘의집 오늘의딜 조회
+
+## What this skill does
+
+오늘의집 공개 오늘의딜 페이지(`https://ohou.se/commerces/today_deals`)의 서버 렌더링 초기 데이터(`__NEXT_DATA__`)를 읽어 특가 상품을 조회한다.
+
+- 오늘의딜/스페셜딜 상품 목록 조회
+- 할인율, 원가, 판매가, 쿠폰/결제혜택 반영 최저가 정리
+- 브랜드, 리뷰 수, 평점, 무료배송 여부, 상품 링크 확인
+- 키워드, 최소 할인율, 무료배송 필터
+
+## When to use
+
+- "오늘의집 오늘의딜 뭐 있어?"
+- "오늘의집에서 할인율 높은 특가 상품 3개 보여줘"
+- "오늘의집 무료배송 특가만 골라줘"
+- "오늘의집에서 러그 특가 찾아줘"
+
+## When not to use
+
+- 로그인, 장바구니, 구매, 결제 자동화 — 이 스킬은 의도적으로 구매 플로우를 포함하지 않는다.
+- 개인화 추천, 사용자별 쿠폰 적용 확정, 실시간 재고 보장.
+- 법적 증빙 수준의 가격 확정 — 조회 시점 기준 참고용이다.
+- 차단 우회, CAPTCHA 우회 — 표준 라이브러리 `urllib` 한 호출로 안 되면 실패 모드로 처리한다.
+
+## Required inputs
+
+별도 입력 없이 실행 가능. 선택적으로 아래를 지정할 수 있다:
+
+- `--query`: 상품명/브랜드 키워드
+- `--min-discount`: 최소 할인율 (0~100 정수)
+- `--free-delivery`: 무료배송 상품만
+- `--sort`: 정렬 기준 (`discount`, `price`, `review`, `annual-sales`)
+- `--limit`: 결과 개수 (양의 정수, 기본 10)
+- `--html-file`: 오프라인 HTML/JSON fixture 경로
+
+## Official/public surface
+
+- 오늘의집 오늘의딜 페이지: `https://ohou.se/commerces/today_deals`
+- 현재 웹 페이지는 canonical/OG URL로 `https://store.ohou.se/today_deals`를 노출하지만, 브라우저 접근용 공개 URL은 `ohou.se/commerces/today_deals`다.
+- 응답 HTML의 Next.js `__NEXT_DATA__` 안 React Query `dehydratedState`에서 `today-deal-feed`, `special-today-deal-feed` queryKey 두 곳의 `todayDealFeed.slots`만 명시적으로 읽는다. 다른 페이지 모듈(navigation, banner 등)에 `type: DEAL` 노드가 있어도 무시한다.
+- HTTP 요청은 `User-Agent: k-skill-ohou-today-deal/1.0 (+https://github.com/NomaDamas/k-skill)`로 보낸다. ohou.se 앞단 Akamai bot manager는 익명/단축 UA를 차단하지만 봇 이름 + contact URL이 포함된 well-formed UA는 통과시키므로 우회/조작 없이 정직한 자기소개로 요청한다.
+
+## Prerequisites
+
+- `python3`
+- 별도 로그인/API 키 없음
+
+## Workflow
+
+### 1. 오늘의딜 상품 조회
+
+오늘의집 오늘의딜 공개 페이지에서 상품 목록을 가져온다. 기본 정렬은 할인율 높은 순이다.
+
+```bash
+python3 ohou-today-deal/scripts/ohou_today_deal.py list --limit 10
+```
+
+응답 예시:
+```json
+{
+  "source": {
+    "name": "ohou-today-deal",
+    "url": "https://ohou.se/commerces/today_deals",
+    "fetched_at": "2026-05-18T01:44:16+00:00",
+    "surface": "__NEXT_DATA__ today-deal-feed + special-today-deal-feed"
+  },
+  "filters": {"query": null, "min_discount": null, "free_delivery": false, "sort": "discount", "limit": 10},
+  "count": 10,
+  "total_count": 72,
+  "filtered_count": 72,
+  "items": [
+    {
+      "id": "823405",
+      "title": "삼익가구 BEST상품 총집합",
+      "brand": "삼익가구",
+      "url": "https://ohou.se/productions/823405/selling",
+      "original_price": 449000,
+      "selling_price": 132000,
+      "discount_rate": 70,
+      "best_price": 118800,
+      "best_discount_rate": 73,
+      "best_discount_description": "쿠폰 할인가",
+      "review_count": 53818,
+      "review_average": 4.7,
+      "free_delivery": false,
+      "sold_out": false
+    }
+  ]
+}
+```
+
+### 2. 할인율 높은 순 정렬
+
+`bestDiscountPrice.discountRate`(쿠폰/결제혜택 반영 할인율)가 있으면 우선 사용하고, 없으면 상품 기본 `discountRate`를 사용한다.
+
+```bash
+python3 ohou-today-deal/scripts/ohou_today_deal.py list \
+  --sort discount \
+  --limit 5
+```
+
+정렬 옵션: `discount`(할인율), `price`(낮은 가격), `review`(리뷰 많은 순), `annual-sales`(연간 판매량).
+
+### 3. 키워드·할인율·무료배송 필터
+
+상품명 또는 브랜드에 키워드가 포함된 상품만 걸러내고, 최소 할인율과 무료배송 조건을 조합할 수 있다.
+
+```bash
+python3 ohou-today-deal/scripts/ohou_today_deal.py list \
+  --query 러그 \
+  --min-discount 30 \
+  --free-delivery \
+  --limit 5
+```
+
+### 4. 오프라인 fixture로 검증
+
+실제 네트워크 없이 저장된 HTML/JSON 파일로 동일한 파싱을 테스트한다.
+
+```bash
+python3 ohou-today-deal/scripts/ohou_today_deal.py list \
+  --html-file ./today-deals.html \
+  --limit 3
+```
+
+## Output format
+
+기본 출력은 들여쓰기 JSON (`indent=2`). 파이프/스크립트에서 사용할 때는 출력을 `jq` 등으로 후처리한다.
+
+주요 필드:
+
+| 필드 | 설명 |
+|---|---|
+| `source.fetched_at` | 조회 시각 (UTC ISO 8601) |
+| `count` | 반환된 상품 수 |
+| `total_count` | 전체 오늘의딜 상품 수 |
+| `filtered_count` | 필터 적용 후 상품 수 |
+| `items[].best_price` | 쿠폰/결제혜택 반영 최저가 (없으면 null) |
+| `items[].best_discount_rate` | 혜택 반영 할인율 (없으면 null) |
+| `items[].free_delivery` | 무료배송 여부 |
+| `items[].sold_out` | 품절 여부 |
+
+## Endpoints used
+
+이 스킬이 호출하는 공개 endpoint:
+
+| Method | URL | 용도 |
+|---|---|---|
+| GET | `https://ohou.se/commerces/today_deals` | 오늘의딜 공개 HTML (서버 렌더링) |
+
+비로그인 / 무인증. 헤더는 `User-Agent` + `Accept` 만.
+
+## Response policy
+
+- 상위 3~5개만 먼저 보여준다.
+- 상품명, 브랜드, 할인가, 원가, 할인율, 평점/리뷰 수, 무료배송 여부, 링크를 정리한다.
+- 가격, 할인, 품절, 쿠폰/결제혜택은 "조회 시각 기준"으로 변동 가능하다고 명시한다.
+- 구매/장바구니/결제는 자동화하지 말고 상품 링크만 제공한다.
+- "지금 사라" 같은 행위 유도 금지 — 사용자가 직접 페이지에서 구매한다.
+
+## Done when
+
+- 오늘의딜 상품 후보가 JSON 또는 요약 목록으로 반환된다.
+- 할인율/가격 기준과 조회 시점이 분리되어 설명된다.
+- 로그인, 구매, 결제, 개인화 기능을 시도하지 않았다.
+
+## Failure modes
+
+- **`__NEXT_DATA__` 미발견**: 오늘의집이 Next.js SSR 구조를 변경하거나, 서버 렌더링 대신 클라이언트 렌더링으로 전환하면 `ValueError` 발생. 스킬 파서 수정이 필요하다.
+- **today-deal-feed queryKey 미발견**: React Query 키 이름이 바뀌면 `extract_deals()`는 빈 리스트를 반환한다 (`total_count: 0`). `TODAY_DEAL_FEED_KEYS` 상수를 새 키 이름으로 업데이트해야 한다.
+- **HTTP 403**: ohou.se 앞단 Akamai bot manager가 요청을 차단한 경우. `User-Agent` 헤더가 변경되어 봇 자기소개 + contact URL 시그니처를 잃었을 가능성이 높다. 우회 시도하지 않고 에러 출력 후 종료한다.
+- **HTTP 4xx/5xx (기타)**: 일시 장애. 우회 시도하지 않고 에러 출력 후 종료.
+- **빈 응답 (`total_count: 0`)**: 오늘의딜이 아직 업데이트되지 않았거나, 페이지 구조가 바뀐 경우. 브라우저에서 직접 확인을 안내한다.
+- **가격/쿠폰 변동**: `best_price`는 조회 시점 기준이며, 사용자별 쿠폰/결제수단에 따라 실제 결제가는 다를 수 있다.
+- **필드 누락**: 일부 상품에 `bestDiscountPrice`, `badgeProperties.isFreeDelivery`, `scrapInfo` 등이 없을 수 있다. null로 처리된다.
+
+## Notes
+
+- read-only 스킬이다.
+- 화면 선택자보다 서버 렌더링 초기 JSON을 우선한다.
+- 새 dependency 없이 Python 표준 라이브러리만 사용한다.