@nomadamas/k-skill 0.1.0

package/skills/ohou-today-deal/scripts/ohou_today_deal.py

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+"""ohou-today-deal — 오늘의집 공개 오늘의딜 특가 상품 조회 CLI.
+
+조회 전용. 로그인·장바구니·구매·결제 자동화 없음.
+__NEXT_DATA__ 서버 렌더링 초기 데이터만 읽는 read-only 스킬.
+
+Usage:
+    ohou-today-deal list [--limit N] [--sort discount|price|review|annual-sales]
+    ohou-today-deal list --query 러그 --min-discount 30 --free-delivery
+    ohou-today-deal list --html-file ./fixture.html
+
+Supported surface:
+    https://ohou.se/commerces/today_deals  (공개 HTML)
+"""
+from __future__ import annotations
+
+import argparse
+import html
+import json
+import re
+import sys
+import urllib.request
+from dataclasses import asdict, dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+DEFAULT_URL = "https://ohou.se/commerces/today_deals"
+DEFAULT_USER_AGENT = (
+    "k-skill-ohou-today-deal/1.0 (+https://github.com/NomaDamas/k-skill)"
+)
+TODAY_DEAL_FEED_KEYS: tuple[tuple[str, ...], ...] = (
+    ("today-deal-feed",),
+    ("special-today-deal-feed",),
+)
+
+
+@dataclass(frozen=True)
+class OhouDeal:
+    id: str
+    title: str
+    brand: str | None
+    url: str
+    image_url: str | None
+    original_price: int | None
+    selling_price: int | None
+    discount_rate: int | None
+    best_price: int | None
+    best_discount_rate: int | None
+    best_discount_description: str | None
+    review_count: int
+    review_average: float | None
+    scrap_count: int | None
+    annual_sales: int | None
+    free_delivery: bool
+    sold_out: bool
+    start_at: str | None
+    end_at: str | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _to_int(value: Any) -> int | None:
+    if value is None or value == "":
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _to_float(value: Any) -> float | None:
+    if value is None or value == "":
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def fetch_html(url: str = DEFAULT_URL, timeout: int = 20) -> str:
+    # ohou.se Akamai 정책: 익명 UA(`python-urllib`, `Mozilla/5.0` 단독)는 403,
+    # 봇 이름+contact URL이 포함된 well-formed UA는 허용. 우회가 아닌 자기소개.
+    request = urllib.request.Request(
+        url,
+        headers={
+            "User-Agent": DEFAULT_USER_AGENT,
+            "Accept": "text/html,application/json",
+        },
+    )
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        charset = response.headers.get_content_charset() or "utf-8"
+        return response.read().decode(charset, errors="replace")
+
+
+def extract_next_data(document: str) -> dict[str, Any]:
+    stripped = document.lstrip()
+    if stripped.startswith("{"):
+        return json.loads(stripped)
+
+    match = re.search(
+        r'<script\b[^>]*\bid=["\']__NEXT_DATA__[^>]*>(.*?)</script>',
+        document,
+        re.DOTALL,
+    )
+    if not match:
+        raise ValueError("Could not find __NEXT_DATA__ in Today Deal HTML")
+    return json.loads(html.unescape(match.group(1)))
+
+
+def _walk(value: Any):
+    """스택 기반 DFS로 JSON 트리의 모든 dict 노드를 순회한다.
+
+    __NEXT_DATA__는 깊고 거대한 트리 구조를 가질 수 있어
+    재귀 대신 반복문을 사용해 sys.getrecursionlimit() 제한을 회피한다.
+    """
+    stack = [value]
+    while stack:
+        curr = stack.pop()
+        if isinstance(curr, dict):
+            yield curr
+            stack.extend(curr.values())
+        elif isinstance(curr, list):
+            stack.extend(reversed(curr))
+
+
+def _looks_like_deal_node(node: dict[str, Any]) -> bool:
+    deal = node.get("deal")
+    return (
+        node.get("type") == "DEAL"
+        and isinstance(deal, dict)
+        and bool(deal.get("id"))
+        and bool(deal.get("name"))
+    )
+
+
+def _iter_today_deal_feeds(payload: dict[str, Any]):
+    """__NEXT_DATA__에서 today-deal-feed / special-today-deal-feed 쿼리만 골라낸다.
+
+    React Query dehydrated state는 `props.pageProps.dehydratedState.queries`에
+    `[{queryKey, state: {data: {...}}}]` 형태로 저장된다. queryKey가 일치하는
+    엔트리의 `state.data.todayDealFeed.slots`만 today-deal 콘텐츠로 인정한다.
+    """
+    allowed = {tuple(key) for key in TODAY_DEAL_FEED_KEYS}
+    queries = (
+        payload.get("props", {})
+        .get("pageProps", {})
+        .get("dehydratedState", {})
+        .get("queries", [])
+    )
+    if not isinstance(queries, list):
+        return
+    for entry in queries:
+        if not isinstance(entry, dict):
+            continue
+        query_key = entry.get("queryKey")
+        if not isinstance(query_key, list):
+            continue
+        if tuple(query_key) not in allowed:
+            continue
+        state = entry.get("state") or {}
+        data = state.get("data") or {}
+        feed = data.get("todayDealFeed") or {}
+        slots = feed.get("slots")
+        if isinstance(slots, list):
+            yield tuple(query_key), slots
+
+
+def _normalize_deal(node: dict[str, Any]) -> OhouDeal:
+    deal = node.get("deal", {})
+    price = deal.get("price") or {}
+    best_price = node.get("bestDiscountPrice") or {}
+    brand = deal.get("brand") or {}
+    review = deal.get("reviewStatistic") or {}
+    scrap = deal.get("scrapInfo") or {}
+    badge = deal.get("badgeProperties") or {}
+    annual_sales = node.get("salesStats", {}).get("annualCumulativeSales")
+    deal_id = str(deal.get("id", ""))
+
+    return OhouDeal(
+        id=deal_id,
+        title=str(deal.get("name") or node.get("title") or ""),
+        brand=brand.get("name"),
+        url=f"https://ohou.se/productions/{deal_id}/selling",
+        image_url=deal.get("imageUrl"),
+        original_price=_to_int(price.get("representativeOriginalPrice")),
+        selling_price=_to_int(price.get("representativeSellingPrice")),
+        discount_rate=_to_int(price.get("discountRate")),
+        best_price=_to_int(best_price.get("price")),
+        best_discount_rate=_to_int(best_price.get("discountRate")),
+        best_discount_description=best_price.get("discountPlanDescription"),
+        review_count=_to_int(review.get("reviewCount")) or 0,
+        review_average=_to_float(review.get("reviewAverage")),
+        scrap_count=_to_int(scrap.get("scrapCount")),
+        annual_sales=_to_int(annual_sales),
+        free_delivery=bool(badge.get("isFreeDelivery")),
+        sold_out=bool(deal.get("isSoldOut")),
+        start_at=node.get("startAt"),
+        end_at=node.get("endAt"),
+    )
+
+
+def extract_deals(payload: dict[str, Any]) -> list[OhouDeal]:
+    seen: set[str] = set()
+    deals: list[OhouDeal] = []
+    found_feed = False
+
+    for _query_key, slots in _iter_today_deal_feeds(payload):
+        found_feed = True
+        for node in slots:
+            if not isinstance(node, dict) or not _looks_like_deal_node(node):
+                continue
+            deal = _normalize_deal(node)
+            if deal.id in seen:
+                continue
+            seen.add(deal.id)
+            deals.append(deal)
+
+    # Fixture/legacy fallback: payload에 React Query dehydratedState가 없거나
+    # queryKey 구조가 다른 경우(테스트 fixture, 단순화된 페이로드)에 한해서만
+    # 전체 트리를 DFS로 훑어 DEAL 노드를 수집한다. 라이브 페이지는 항상
+    # 위쪽 명시적 분기에서 잡히므로 이 fallback은 영향받지 않는다.
+    if not found_feed:
+        for node in _walk(payload):
+            if not _looks_like_deal_node(node):
+                continue
+            deal = _normalize_deal(node)
+            if deal.id in seen:
+                continue
+            seen.add(deal.id)
+            deals.append(deal)
+
+    return deals
+
+
+def filter_deals(
+    deals: list[OhouDeal],
+    *,
+    query: str | None = None,
+    min_discount: int | None = None,
+    free_delivery: bool = False,
+    include_sold_out: bool = False,
+) -> list[OhouDeal]:
+    """단일 루프로 모든 필터 조건을 검사한다."""
+    needle = query.casefold() if query else None
+    filtered: list[OhouDeal] = []
+
+    for deal in deals:
+        if not include_sold_out and deal.sold_out:
+            continue
+        if needle and needle not in deal.title.casefold() and needle not in (deal.brand or "").casefold():
+            continue
+        if min_discount is not None and (deal.best_discount_rate or deal.discount_rate or 0) < min_discount:
+            continue
+        if free_delivery and not deal.free_delivery:
+            continue
+        filtered.append(deal)
+
+    return filtered
+
+
+def sort_deals(deals: list[OhouDeal], sort_key: str) -> list[OhouDeal]:
+    if sort_key == "discount":
+        return sorted(
+            deals,
+            key=lambda deal: (deal.best_discount_rate or deal.discount_rate or -1, deal.review_count),
+            reverse=True,
+        )
+    if sort_key == "price":
+        return sorted(deals, key=lambda deal: deal.best_price or deal.selling_price or sys.maxsize)
+    if sort_key == "review":
+        return sorted(deals, key=lambda deal: (deal.review_count, deal.review_average or 0), reverse=True)
+    if sort_key == "annual-sales":
+        return sorted(deals, key=lambda deal: deal.annual_sales or -1, reverse=True)
+    return deals
+
+
+def build_payload(args: argparse.Namespace) -> dict[str, Any]:
+    document = Path(args.html_file).read_text(encoding="utf-8") if args.html_file else fetch_html(args.url)
+    payload = extract_next_data(document)
+    deals = extract_deals(payload)
+    filtered = filter_deals(
+        deals,
+        query=args.query,
+        min_discount=args.min_discount,
+        free_delivery=args.free_delivery,
+        include_sold_out=args.include_sold_out,
+    )
+    sorted_deals = sort_deals(filtered, args.sort)
+    limited_deals = sorted_deals[: args.limit]
+
+    kst = timezone(timedelta(hours=9))
+    now_utc = datetime.now(timezone.utc)
+
+    return {
+        "source": {
+            "name": "ohou-today-deal",
+            "url": args.url,
+            "fetched_at": now_utc.isoformat(),
+            "fetched_at_kst": now_utc.astimezone(kst).strftime("%Y-%m-%d %H:%M:%S KST"),
+            "surface": "__NEXT_DATA__ today-deal-feed + special-today-deal-feed",
+        },
+        "filters": {
+            "query": args.query,
+            "min_discount": args.min_discount,
+            "free_delivery": args.free_delivery,
+            "include_sold_out": args.include_sold_out,
+            "sort": args.sort,
+            "limit": args.limit,
+        },
+        "count": len(limited_deals),
+        "total_count": len(deals),
+        "filtered_count": len(filtered),
+        "items": [deal.to_dict() for deal in limited_deals],
+    }
+
+
+def _positive_int(value: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"expected integer, got {value!r}") from exc
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError(f"must be a positive integer, got {parsed}")
+    return parsed
+
+
+def _discount_rate(value: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"expected integer, got {value!r}") from exc
+    if not 0 <= parsed <= 100:
+        raise argparse.ArgumentTypeError(
+            f"discount rate must be between 0 and 100, got {parsed}"
+        )
+    return parsed
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Read Ohouse today deal products from public HTML.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    list_parser = subparsers.add_parser("list", help="오늘의집 오늘의딜 상품 목록")
+    list_parser.add_argument("--url", default=DEFAULT_URL)
+    list_parser.add_argument("--html-file", help="테스트/오프라인 검증용 HTML 또는 JSON 파일")
+    list_parser.add_argument("--query", help="상품명 또는 브랜드 키워드")
+    list_parser.add_argument("--min-discount", type=_discount_rate, help="최소 할인율 (0~100)")
+    list_parser.add_argument("--free-delivery", action="store_true", help="무료배송 상품만")
+    list_parser.add_argument("--include-sold-out", action="store_true", help="품절 상품 포함")
+    list_parser.add_argument(
+        "--sort",
+        choices=["default", "discount", "price", "review", "annual-sales"],
+        default="discount",
+    )
+    list_parser.add_argument("--limit", type=_positive_int, default=10, help="결과 개수 (양의 정수)")
+
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = parse_args(argv)
+    if args.command == "list":
+        print(json.dumps(build_payload(args), ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/skills/ohou-today-deal/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "ohou-today-deal",
+  "description": "오늘의집 공개 오늘의딜 페이지에서 로그인 없이 특가 상품을 조회하고 할인율, 가격, 리뷰, 링크를 정리하는 읽기 전용 스킬. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "browser",
+    "action:commerce"
+  ],
+  "frontmatter": "name: ohou-today-deal\ndescription: 오늘의집 공개 오늘의딜 페이지에서 로그인 없이 특가 상품을 조회하고 할인율, 가격, 리뷰, 링크를 정리하는 읽기 전용 스킬. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: retail\n  locale: ko-KR\n  phase: v1"
+}

package/skills/olive-young-search/instruction.md

@@ -0,0 +1,154 @@
+# Olive Young Search
+
+## What this skill does
+
+upstream 원본 [`hmmhmmhm/daiso-mcp`](https://github.com/hmmhmmhm/daiso-mcp) 와 npm package [`daiso`](https://www.npmjs.com/package/daiso) 를 그대로 사용해 **올리브영 매장 검색, 상품 검색, 재고 확인** 흐름을 안내한다.
+
+이 저장소는 원본 MCP 서버 코드를 vendoring 하지 않는다. 대신 **MCP 서버를 Claude Code에 직접 설치하지 않고 CLI 형태로 먼저 확인하는 경로**를 기본값으로 둔다.
+
+핵심 조회 경로:
+
+- 매장 검색: `/api/oliveyoung/stores`
+- 상품 검색: `/api/oliveyoung/products`
+- 재고 확인: `/api/oliveyoung/inventory`
+- health check: `npx --yes daiso health`
+
+## When to use
+
+- "명동 근처 올리브영 매장 찾아줘"
+- "올리브영 선크림 어떤 거 있나 보여줘"
+- "명동 근처 올리브영에서 선크림 재고 확인해줘"
+- "올리브영 검색용 CLI 붙여줘"
+
+## When not to use
+
+- 로그인, 주문, 장바구니, 결제 자동화
+- 올리브영 계정/세션이 필요한 private 기능
+- upstream 서버 코드를 이 저장소 안에 복사해서 유지하려는 경우
+
+## Prerequisites
+
+- 인터넷 연결
+- `node` 20 권장 (`hmmhmmhm/daiso-mcp` 2026-04-05 기준 `engines.node` 는 `>=20 <21`)
+- `npx` 또는 `npm`
+- 필요하면 `git`
+
+Node 22에서도 로컬 smoke test는 성공했지만 `EBADENGINE` 경고가 보여서, **안정 경로는 Node 20 LTS** 로 본다.
+
+## Preferred setup: CLI first, not direct MCP install
+
+가장 빠른 경로는 MCP 연결부터 하지 않고 upstream CLI로 공개 endpoint를 확인하는 것이다.
+
+```bash
+npx --yes daiso health
+npx --yes daiso get /api/oliveyoung/stores --keyword 명동 --limit 5 --json
+npx --yes daiso get /api/oliveyoung/products --keyword 선크림 --size 5 --json
+npx --yes daiso get /api/oliveyoung/inventory --keyword 선크림 --storeKeyword 명동 --size 5 --json
+```
+
+반복 사용이면 전역 설치도 가능하다.
+
+```bash
+npm install -g daiso
+export NODE_PATH="$(npm root -g)"
+daiso health
+```
+
+## Fallback: clone the original repository and run the same CLI locally
+
+public endpoint 재시도나 버전 고정이 필요하면 원본 저장소를 clone 해서 build 결과물 `dist/bin.js` 를 `node` 로 직접 실행한다.
+clone checkout 안에서는 `npx daiso ...` 가 `Permission denied` 로 실패할 수 있으므로, local fallback은 아래 경로를 기본으로 둔다.
+
+```bash
+git clone https://github.com/hmmhmmhm/daiso-mcp.git
+cd daiso-mcp
+npm install
+npm run build
+node dist/bin.js health
+node dist/bin.js get /api/oliveyoung/stores --keyword 명동 --limit 5 --json
+node dist/bin.js get /api/oliveyoung/products --keyword 선크림 --size 5 --json
+node dist/bin.js get /api/oliveyoung/inventory --keyword 선크림 --storeKeyword 명동 --size 5 --json
+```
+
+즉, 이 스킬의 기본 원칙은 **원본 `hmmhmmhm/daiso-mcp`를 설치/실행해서 쓰고, `k-skill`에는 가이드만 추가하는 것**이다.
+
+## Required inputs
+
+### 1. Store or area keyword first when place context is missing
+
+- 권장 질문: `어느 지역/매장을 기준으로 볼까요? 예: 명동, 강남역, 성수`
+- 재고 질문인데 지역이 없으면 먼저 지역/매장 키워드를 받는다.
+
+### 2. Product keyword first when inventory is requested
+
+- 권장 질문: `찾을 상품 키워드도 알려주세요. 예: 선크림, 립밤, 마스크팩`
+- 상품 종류를 묻는 경우에도 키워드를 너무 넓게 받지 않는다.
+
+## Workflow
+
+### 1. Check server health
+
+```bash
+npx --yes daiso health
+```
+
+### 2. Resolve nearby stores
+
+```bash
+npx --yes daiso get /api/oliveyoung/stores --keyword 명동 --limit 5 --json
+```
+
+매장 후보가 여러 개면 상위 2~3개만 요약하고 다시 확인받는다.
+
+### 3. Resolve product candidates
+
+```bash
+npx --yes daiso get /api/oliveyoung/products --keyword 선크림 --size 5 --json
+```
+
+상품 후보가 많으면 `goodsNumber`, 가격, 이미지 URL, `inStock` 여부를 함께 짧게 정리한다.
+
+### 4. Check inventory for the chosen area/store keyword
+
+```bash
+npx --yes daiso get /api/oliveyoung/inventory --keyword 선크림 --storeKeyword 명동 --size 5 --json
+```
+
+응답의 `inventory.products[].storeInventory.stores[]` 안에서 다음 값을 우선 본다.
+
+- `stockLabel`
+- `remainQuantity`
+- `stockStatus`
+- `storeName`
+
+### 5. Respond conservatively
+
+최종 응답은 아래 순서로 짧게 정리한다.
+
+- 기준 지역/매장 키워드
+- 상위 매장 후보
+- 상품 후보 또는 선택 상품
+- 재고 있는 매장 / 품절 / 미판매 구분
+- 필요하면 `imageUrl` 참고 링크
+- 공개 endpoint 특성상 재고는 실시간 100% 보장값이 아니므로 방문 직전 재확인을 권장
+
+## Done when
+
+- `hmmhmmhm/daiso-mcp` 원본 repo와 `daiso` CLI 사용 경로를 명시했다.
+- MCP 서버를 직접 설치하는 대신 CLI first 흐름을 제시했다.
+- 매장 검색 → 상품 검색 → 재고 확인 순서를 따랐다.
+- `/api/oliveyoung/stores`, `/api/oliveyoung/products`, `/api/oliveyoung/inventory` 중 필요한 호출을 실제로 안내했다.
+- 재고 결과를 매장별 `stockLabel` 중심으로 요약했다.
+
+## Failure modes
+
+- public endpoint는 upstream 내부 수집 경로(Zyte 의존) 사정으로 간헐적인 5xx/503을 줄 수 있다.
+- 지역 키워드가 너무 넓으면 멀리 떨어진 동명이점 매장이 섞일 수 있다.
+- 인기 상품은 검색 결과가 많아 상위 몇 개만 먼저 확인받는 편이 안전하다.
+- 재고 수량은 시점 차이로 실제 방문 시 달라질 수 있다.
+
+## Notes
+
+- 원본 프로젝트: `https://github.com/hmmhmmhm/daiso-mcp`
+- npm package: `https://www.npmjs.com/package/daiso`
+- 이 저장소는 upstream 코드를 vendoring 하지 않고 skill/docs만 유지한다.

package/skills/olive-young-search/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "olive-young-search",
+  "description": "upstream daiso CLI를 사용해 올리브영 매장 검색, 상품 검색, 재고 확인을 조회한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "action:commerce"
+  ],
+  "frontmatter": "name: olive-young-search\ndescription: upstream daiso CLI를 사용해 올리브영 매장 검색, 상품 검색, 재고 확인을 조회한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: retail\n  locale: ko-KR\n  phase: v1"
+}

package/skills/parking-lot-search/instruction.md

@@ -0,0 +1,96 @@
+# Parking Lot Search
+
+## What this skill does
+
+유저가 알려준 현재 위치를 기준으로 **근처 공영주차장** 을 찾는다.
+
+- 위치는 자동 추정하지 않는다.
+- **반드시 먼저 현재 위치를 질문**한다.
+- 기본값은 `공영` 주차장만 보여준다.
+- 공식 `전국주차장정보표준데이터` Open API를 사용한다.
+- 위치 문자열은 Kakao Map anchor 검색으로 좌표를 잡은 뒤, 공식 주차장 데이터에서 거리순으로 정리한다.
+- 실시간 만차/잔여면/예약 여부는 공식 표준데이터에 없으므로 확정해서 말하지 않는다.
+
+## When to use
+
+- "근처 주차장 찾아줘"
+- "광화문 주변 공영주차장 어디 있어?"
+- "서울역 근처 무료 주차장 있어?"
+- "지금 여기서 가까운 공영주차장 지도 링크 줘"
+
+## Mandatory first question
+
+위치 정보 없이 바로 검색하지 말고 반드시 먼저 물어본다.
+
+권장 질문:
+
+`현재 위치를 알려주세요. 동네/역명/랜드마크/위도·경도 중 편한 형식으로 보내주시면 근처 공영주차장을 찾아볼게요.`
+
+위치가 애매하면:
+
+`가까운 역명이나 동 이름으로 한 번만 더 알려주세요.`
+
+## Official surfaces
+
+- 표준데이터 안내: `https://www.data.go.kr/data/15012896/standard.do`
+- Open API 안내: `https://www.data.go.kr/data/15012896/openapi.do`
+- Open API endpoint: `https://api.data.go.kr/openapi/tn_pubr_prkplce_info_api`
+- k-skill proxy: `/v1/parking-lots/search`
+- Kakao Map 모바일 검색: `https://m.map.kakao.com/actions/searchView?q=<query>`
+- Kakao Map 장소 패널 JSON: `https://place-api.map.kakao.com/places/panel3/<confirmId>`
+
+## Workflow
+
+1. 유저에게 반드시 현재 위치를 묻는다.
+2. 위치 문자열을 받으면 Kakao Map으로 anchor 후보를 고르고 좌표를 확보한다.
+3. anchor 주소에서 `시도 + 시군구` address hint를 만든다.
+4. k-skill-proxy `/v1/parking-lots/search` 또는 `parking-lot-search` 패키지로 공식 주차장 데이터를 조회한다.
+5. 보통 3~5개만 짧게 정리하고, 지도 링크를 같이 준다.
+6. 요금/운영시간은 데이터 기준일자와 함께 안내하고, 실시간 현황이 아님을 밝힌다.
+
+## Responding
+
+결과는 보통 아래 필드를 포함해 짧게 정리한다.
+
+- 주차장명
+- 거리
+- 공영/민영 및 노상/노외/부설 유형
+- 주소
+- 운영요일/운영시간
+- 요금정보, 기본요금, 추가요금
+- 주차구획수
+- 전화번호/관리기관
+- 데이터기준일자
+- 지도 링크
+
+## Node.js example
+
+```js
+const { searchNearbyParkingLotsByLocationQuery } = require("parking-lot-search");
+
+async function main() {
+  const result = await searchNearbyParkingLotsByLocationQuery("광화문", {
+    limit: 3,
+    radius: 1500
+  });
+
+  console.log(result.anchor);
+  console.log(result.items);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+```
+
+## 모두의주차장 status
+
+Issue #135에서 모두의주차장 연동 가능성을 언급했지만, v1은 공식 공공데이터 기반으로 시작한다. 승인된 공식/파트너 API 계약이 확인되기 전에는 모두의주차장 비공식 API 호출이나 scraping을 하지 않는다.
+
+## Done when
+
+- 유저의 현재 위치를 먼저 확인했다.
+- 공식 데이터 기반으로 최소 1개 이상 nearby parking lot을 찾았거나, 못 찾은 이유와 다음 질문을 제시했다.
+- 가장 가까운 결과를 3~5개 이내로 정리했다.
+- 실시간 잔여면/예약 가능 여부가 아님을 필요한 경우 명확히 했다.

package/skills/parking-lot-search/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "parking-lot-search",
+  "description": "Use when the user asks for nearby parking lots or 근처 주차장/공영주차장. Always ask the user's current location first, then use official Data.go.kr public parking data through k-skill-proxy or the parking-lot-search package.",
+  "profiles": [
+    "proxy",
+    "lookup"
+  ],
+  "frontmatter": "name: parking-lot-search\ndescription: Use when the user asks for nearby parking lots or 근처 주차장/공영주차장. Always ask the user's current location first, then use official Data.go.kr public parking data through k-skill-proxy or the parking-lot-search package.\nlicense: MIT\nmetadata:\n  category: convenience\n  locale: ko-KR\n  phase: v1"
+}