instruction.md
# Naver Shopping Search
## What this skill does
`k-skill-proxy`가 네이버 검색 Open API 쇼핑 검색(`shop.json`)을 우선 사용하고, 키가 없을 때만 네이버 쇼핑/검색의 로그인 없는 공개 BFF JSON endpoint를 **단일 검색 요청**으로 가져와 상품 후보를 정규화한다.
- 상품명/검색어로 네이버 쇼핑 후보를 찾는다.
- 현재 노출 가격, 판매처, 링크, 이미지, 리뷰/구매 수(노출될 때만)를 정리한다.
- 가격이 낮은 후보와 공식몰/브랜드몰 후보를 분리해서 비교할 수 있다.
- 주문, 장바구니, 찜, 로그인 세션 접근은 하지 않는다.
## When to use
- "네이버 쇼핑에서 에어팟 가격 비교해줘"
- "네이버 최저가로 커피머신 찾아줘"
- "네이버 쇼핑 링크랑 판매처별 가격을 비교해줘"
- "이 상품 네이버 쇼핑에서 얼마쯤 해?"
## When not to use
- 회원 전용가, 쿠폰 적용가, 네이버페이 개인화 혜택을 확정해야 하는 경우
- 주문/장바구니/찜/로그인이 필요한 액션
- 차단 우회, CAPTCHA 우회, fingerprint spoofing 등 접근 통제를 우회해야 하는 경우
## Required inputs
상품명 또는 검색어가 없으면 먼저 물어본다.
권장 질문:
> 찾을 네이버 쇼핑 상품명이나 검색어를 알려주세요. 예: 에어팟 프로 2세대, 아이폰 15 케이스
검색어가 너무 넓으면 브랜드/용량/모델명을 추가로 물어본다.
## Proxy endpoint
기본값은 public/read-only/no-auth 프록시다. 프록시 서버에 `NAVER_SEARCH_CLIENT_ID`와 `NAVER_SEARCH_CLIENT_SECRET`이 있으면 공식 Search API를 우선 사용한다.
```bash
curl -fsS --get "${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}/v1/naver-shopping/search" \
--data-urlencode 'q=에어팟 프로 2세대' \
--data-urlencode 'limit=10' \
--data-urlencode 'sort=rel'
```
쿼리 파라미터:
- `q` 또는 `query` — 검색어. 2글자 이상.
- `limit` — 반환 개수. 기본 10, 최대 40으로 clamp.
- `page` — 페이지. 기본 1. no-key BFF fallback에서는 BFF의 `page`를 요청하고 해당 페이지 카드만 정규화한다.
- `sort` — `rel`, `date`, `price_asc`, `price_dsc`, `review` 중 하나. 알 수 없는 값은 `rel`.
- 공식 Search API 경로는 네이버 API sort를 사용한다. 단, 공식 API가 `review` 정렬을 지원하지 않아 `review` 요청은 upstream `sort=sim`으로 조회하고 `meta.sort_applied: "unsupported"`, `meta.upstream_sort: "sim"`으로 표시한다.
- no-key BFF fallback은 `rel`은 BFF 노출 순서를 유지하고, `price_asc`/`price_dsc`/`review`는 선택된 BFF 페이지 카드 안에서 로컬 정렬한다. BFF 카드에 날짜 필드가 없어 `date`는 `meta.sort_applied: "unsupported"`로 표시하고 BFF 노출 순서를 유지한다.
응답 주요 필드:
- `items[].title`
- `items[].price` / `items[].price_text`
- `items[].mall_name`
- `items[].url`
- `items[].image_url`
- `items[].review_count`, `purchase_count`, `score` (노출될 때만)
- `meta.extraction` — `naver-openapi`, `bff-json`, `embedded-json`, `html-card`, `none`
- `meta.sort_applied` — `upstream`, `local`, `unsupported` 중 하나
## Workflow
1. 검색어를 확인한다.
2. `GET /v1/naver-shopping/search` 를 호출한다.
3. `items`가 있으면 요청 sort와 `meta.sort_applied`를 확인한 뒤 가격 낮은 순, 공식/브랜드몰 여부, 리뷰 수 등을 기준으로 3~5개 후보를 짧게 비교한다.
4. `meta.extraction`과 조회 시각 기준임을 함께 말한다.
5. `items`가 비었거나 upstream 차단/오류가 나면 우회 시도를 반복하지 말고, 검색어를 좁히거나 브라우저 수동 확인을 안내한다.
## Response style
- 가격은 "조회 시점 네이버 쇼핑 노출가"라고 표현한다.
- 배송비, 쿠폰, 옵션 추가금, 회원 혜택은 비로그인 공개 검색만으로 확정하지 않는다.
- 판매처 신뢰도는 노출된 판매처명/리뷰 수만 근거로 보수적으로 말한다.
- 최저가만 단정하지 말고 동률/옵션 차이를 조심한다.
## Failure modes
- 공식 Search API 키가 없어서 BFF fallback을 사용할 때는 네이버가 특정 IP/환경에 418/403 등 bot-block 응답을 줄 수 있다.
- no-key fallback은 `ns-portal.shopping.naver.com/api/v2/shopping-paged-slot?query=<검색어>&source=shp_gui` 공개 JSON path를 사용한다.
- 검색 결과 BFF JSON 스키마는 비공식 프론트엔드 표면이라 바뀔 수 있다.
- 가격/품절/배송 정보는 실시간으로 바뀐다.
- 프록시는 접근 통제 우회를 하지 않는다. 공식 Search API 또는 단일 공개 검색 요청 + 캐시 + rate limit만 사용한다.
## Done when
- 검색어를 확인했다.
- 네이버 쇼핑 후보를 최소 1개 이상 반환하거나, 왜 반환하지 못했는지 설명했다.
- 가격/판매처/링크를 조회 시점 기준으로 보수적으로 정리했다.
- 로그인/주문/차단 우회 범위를 벗어나지 않았다.
references/DISCLAIMER.md
# DISCLAIMER — `naver-shopping-search`
이 스킬은 네이버·네이버쇼핑 또는 판매자의 공식 기능 또는 공식 지원 도구가 아니며, 공식 제휴·후원·승인·인증 또는 협업한 사실이 전혀 없습니다. 상표와 서비스명은 상품·가격 조회 기능과 대상을 설명하기 위해서만 사용합니다.
대법원 2005. 6. 10. 선고 [2005도1637 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=83920)(소니용 리모컨 사건)은 기능 설명용 표장과 출처표시를 구별했습니다. [상표법 제2조](https://www.law.go.kr/법령/상표법/제2조), [제89조](https://www.law.go.kr/법령/상표법/제89조), [제90조](https://www.law.go.kr/법령/상표법/제90조), [제108조](https://www.law.go.kr/법령/상표법/제108조)에 따른 출처 혼동 판단은 별도입니다.
대법원 2022. 5. 12. 선고 [2021도1533 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=221765)은 공개정보 수집만으로 곧바로 [정보통신망법 제48조](https://www.law.go.kr/법령/정보통신망이용촉진및정보보호등에관한법률/제48조) 위반이 되는 것은 아닌 사정을 제시했지만, [저작권법 제93조](https://www.law.go.kr/법령/저작권법/제93조)의 상품 DB 권리와 [형법 제314조 제2항](https://www.law.go.kr/법령/형법/제314조)은 별도입니다.
- 공개 상품정보 자동 수집은 반드시 개인의 정보 조회용으로만 사용합니다.
- 조직적·대량 크롤링, 상품 DB 구축·재판매, 이미지·상세설명 원본 재배포를 하지 않습니다.
- 출처 링크를 유지하고 접근통제·차단·rate limit을 우회하거나 정상 영업을 방해하지 않습니다.
이 문서는 적법성을 보증하는 법률 자문이 아닙니다.
references/TRADEMARK-LEGAL-STATEMENT.md
# 상표 사용 법적 고지 — `naver-shopping-search`
이 스킬에서 `네이버 쇼핑` 및 `Naver` 명칭은 상품 후보·최저가·판매처 링크 조회의 **대상 쇼핑 서비스**를 식별하기 위해 사용한다. k-skill의 출처를 네이버로 표시하려는 사용이 아니다.
대법원 2005. 6. 10. 선고 [2005도1637 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=83920)은 타인의 표장을 출처표시가 아니라 상품 기능 또는 적용 기종을 밝히기 위해 사용하고 상표 사용으로 인식될 수 없는 경우 침해가 아니라고 판시했다. [상표법 제2조](https://www.law.go.kr/법령/상표법/제2조), [제89조](https://www.law.go.kr/법령/상표법/제89조), [제90조](https://www.law.go.kr/법령/상표법/제90조), [제108조](https://www.law.go.kr/법령/상표법/제108조)와 대법원 [2011다18802](https://www.law.go.kr/LSW/precInfoP.do?precSeq=167457), [2019후10418](https://law.go.kr/LSW/precInfoP.do?mode=0&precSeq=230725) 판결에 따라 실제 거래계에서 출처표시로 기능하는지는 표시 태양과 사용 경위 등을 종합해 판단해야 한다.
따라서 이 명칭은 필요한 범위의 평문으로만 사용하고, 별도 근거 없이 로고, 공식·제휴·후원·인증·파트너 표현을 사용하지 않는다. 각 상표의 권리는 해당 권리자에게 있다. 이 문서는 상품정보의 저작권·데이터베이스권, 부정경쟁방지법, 약관·계약 또는 접근·재사용의 적법성을 판단하지 않는다.
전체 검토: [제3자 상표의 기능 설명·호환 대상 표시 검토](https://github.com/NomaDamas/k-skill/blob/dev/docs/legal/trademark-use-review.md)
skill.json
{
"name": "naver-shopping-search",
"description": "네이버 쇼핑 공개 BFF JSON을 k-skill-proxy로 조회해 상품 후보, 최저가, 판매처 링크를 보수적으로 가격비교한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
"profiles": [
"proxy",
"vault",
"browser",
"action:commerce"
],
"frontmatter": "name: naver-shopping-search\ndescription: 네이버 쇼핑 공개 BFF JSON을 k-skill-proxy로 조회해 상품 후보, 최저가, 판매처 링크를 보수적으로 가격비교한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n category: retail\n locale: ko-KR\n phase: v1"
}
SKILL.md
---
name: naver-shopping-search
description: 네이버 쇼핑 공개 BFF JSON을 k-skill-proxy로 조회해 상품 후보, 최저가, 판매처 링크를 보수적으로 가격비교한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.
license: MIT
metadata:
category: retail
locale: ko-KR
phase: v1
---
# naver-shopping-search
<!-- k-skill:cli-stub — generated by scripts/generate-skill-stubs.js; edit skill.json / instruction.md instead -->
## Get the full instructions (required first step)
Run this and follow its output as the primary instructions for this skill:
```bash
npx -y @nomadamas/k-skill@0 instruct naver-shopping-search
```
The CLI detects the current runtime (Dolshoi vault/CloakBrowser vs generic) and prints only the applicable instructions, always up to date. Helper files bundled with the CLI are listed by:
```bash
npx -y @nomadamas/k-skill@0 files naver-shopping-search
```
If `npx` is unavailable, install Node.js 18+ or follow https://github.com/NomaDamas/k-skill#readme, or read the source instructions at https://github.com/NomaDamas/k-skill/blob/main/naver-shopping-search/instruction.md.
## Legal disclaimer (required)
This skill is not an official feature of, officially supported by, affiliated with, sponsored by, approved by, or developed in collaboration with any third-party trademark owner or service operator it identifies. Third-party names are used only to describe the skill's function, lookup target, or compatibility.
Any automated collection of publicly accessible information must be limited to personal, non-organizational lookup. Do not use this skill for systematic or bulk crawling, database building, access-control or block circumvention, or conduct that interferes with a third party's business or service.
Read the full Korean legal disclaimer, including the cited Korean Supreme Court precedents and statutory limits, before use:
```bash
npx -y @nomadamas/k-skill@0 read naver-shopping-search references/DISCLAIMER.md
```
## Hard rules even without the CLI
- Never execute payment, message/email delivery, final submission, cancellation, or public posting without the user's explicit approval immediately beforehand.
- Never ask for, print, or store plaintext credentials in chat, files, or shell arguments.
- Never bypass legal, physical-presence, CAPTCHA, identity-proofing, or electronic-signature boundaries.