kakao-bar-nearby

어떤 스킬인가요?

Use when the user asks for nearby bars or 근처 술집. Ask for the user's location, search with the official Kakao Local API, then follow returned Kakao Map detail links for open-now, menu, and seating hints. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# Kakao Bar Nearby

## What this skill does

유저가 알려준 현재 위치를 기준으로 **카카오맵 공식 API에서 근처 술집 후보를 찾고**, 후보별 카카오맵 상세 링크로 핸드오프해 영업 상태·메뉴·좌석 정보를 확인한다.

- 위치는 자동으로 추정하지 않는다.
- **반드시 먼저 현재 위치를 질문**한다.
- `서울역`, `강남`, `사당`, `신논현`, `논현` 같은 역명/동네/랜드마크 질의를 그대로 받을 수 있다.
- 장소 후보 검색과 거리 계산은 `k-skill-proxy`의 Kakao Local REST API를 우선 사용한다.
- 공식 API에 없는 현재 영업 상태, 대표 메뉴, 좌석 옵션은 반환된 카카오맵 장소 상세 링크에서 확인한다.

## When to use

- "서울역 근처 술집 찾아줘"
- "강남에서 지금 영업중인 와인바 뭐 있어?"
- "논현 근처 4명 갈만한 술집 알려줘"
- "사당에서 전화번호 있는 이자카야 몇 군데만 보여줘"

## Mandatory first question

위치 정보 없이 바로 검색하지 말고 반드시 먼저 물어본다.

- 권장 질문: `현재 위치를 알려주세요. 서울역/강남/사당 같은 역명이나 동네명으로 보내주시면 카카오맵 기준 근처 술집을 찾아볼게요.`
- 위치가 애매하면: `가까운 역명이나 동 이름으로 한 번만 더 알려주세요.`

## Access path

### Primary: official Kakao Local API

- hosted proxy: `https://k-skill-proxy.nomadamas.org`
- anchor and bar search: `GET /v1/kakao-map/search/keyword`
- user API key: 필요 없음
- package function: `searchNearbyBarsByLocationQuery(locationQuery, options?)`

패키지는 기준 장소를 공식 API로 찾은 뒤 같은 좌표를 중심으로 `<location> 술집`을 거리순 검색한다. 결과의 `sourceUrl`과 `detailLookup.url`은 Kakao Local 응답의 `place_url`을 사용하며, 누락 시 공식 장소 ID로 `https://place.map.kakao.com/<id>`를 구성한다.

### Detail handoff: official Kakao Map place page

- place detail: `https://place.map.kakao.com/<id>`
- detail fields: `openStatus`, `menuSamples`, `seatingKeywords`, `capacityHint`

내부 `place-api.map.kakao.com/places/panel3` JSON이나 모바일 검색 HTML을 기본 검색 경로로 사용하지 않는다. 장소 상세 정보가 필요할 때만 반환된 공식 장소 페이지를 브라우저로 연다.

## Workflow

1. 유저에게 반드시 현재 위치를 묻는다.
2. `searchNearbyBarsByLocationQuery`로 공식 Kakao Local API 기반 후보를 가져온다.
3. `items[]`에서 이름, 카테고리, 주소, 전화번호, 거리, `detailLookup.url`을 확인한다.
4. 상위 3~5개 후보의 `detailLookup.url`을 브라우저로 열고 장소명이 후보와 일치하는지 먼저 확인한다.
5. 상세 페이지에서 보이는 정보만 사용해 다음 필드를 보강한다.
   - 현재 영업 상태와 오늘 영업시간
   - 대표 메뉴 2~3개
   - 단체석, 룸, 바테이블, 혼술 등 좌석/인원 힌트
6. 상세 확인이 끝난 후보는 영업 중 우선, 그다음 거리순으로 정리한다.
7. 상세 페이지가 차단되거나 해당 필드가 없으면 추정하지 않는다. 공식 API 결과와 장소 링크를 제공하고 `상세 정보 미확인`으로 표시한다.

## Package output contract

```js
const { searchNearbyBarsByLocationQuery } = require("kakao-bar-nearby");

const result = await searchNearbyBarsByLocationQuery("서울역", {
  limit: 5,
  radius: 3000
});
```

주요 반환 필드:

- `anchor`: 공식 API에서 선택한 기준 장소
- `items[].name`, `category`, `address`, `phone`
- `items[].distanceMeters`
- `items[].sourceUrl`
- `items[].detailLookup.status`: 상세 페이지 확인 전에는 `required`
- `items[].detailLookup.url`: 영업·메뉴·좌석 확인에 사용할 카카오맵 장소 링크
- `items[].detailLookup.fields`: 상세 페이지에서 확인할 필드 목록
- `meta.source`: `kakao-local-rest-api`
- `meta.detailLookupRequiredCount`

공식 API 단계에서는 상세 필드를 임의로 채우지 않는다.

- `isOpenNow`: `null`
- `openStatus`: `null`
- `menuSamples`: `[]`
- `seatingKeywords`: `[]`
- `capacityHint`: `null`

## Responding

보통 3~5개만 짧게 정리한다.

- 술집명
- 카테고리
- 영업 상태 (`영업 중`, `영업 전`, `휴무일`, `상세 정보 미확인`)
- 대표 메뉴 2~3개
- 좌석/인원 수용 힌트 (`단체석`, `바테이블` 등)
- 전화번호
- 거리
- 카카오맵 상세 링크

공식 API에서 확인한 값과 상세 페이지에서 확인한 값을 혼동하지 않는다. 메뉴·영업·좌석 정보는 상세 페이지에서 실제로 확인한 후보에만 표시한다.

## Failure modes

- `429 rate_limited`: 잠시 후 재시도가 필요함을 알리고 반복 호출하지 않는다.
- `502 upstream_error` / `503 upstream_not_configured`: 공식 Kakao API 경로가 현재 사용 불가하므로 원인을 그대로 설명한다.
- 기준 장소가 모호함: 가까운 역명이나 동 이름을 한 번 더 묻는다.
- 술집 후보 없음: 반경을 넓히거나 `와인바`, `이자카야`, `호프`처럼 키워드를 구체화한다.
- 장소 상세 페이지 차단, CAPTCHA, 빈 화면, 구조 변경: 우회하지 않고 공식 API 후보와 링크까지만 제공한다.
- 메뉴·좌석·영업 정보가 페이지에 없음: 추정하지 않고 `상세 정보 미확인`으로 표시한다.

## Done when

- 유저의 현재 위치를 먼저 확인했다.
- 공식 Kakao Local API로 술집 후보를 최소 1개 이상 찾았거나 실패 이유를 설명했다.
- 각 후보의 카카오맵 상세 링크를 확보했다.
- 상위 후보의 상세 링크에서 영업 상태·메뉴·좌석 정보를 확인했거나, 확인하지 못한 이유를 명시했다.

# DISCLAIMER — `kakao-bar-nearby`

이 스킬은 제3자 상표권자·서비스 운영사의 공식 기능 또는 공식 지원 도구가 아니며, 공식 제휴·후원·승인·인증 또는 협업한 사실이 전혀 없습니다. 상표와 서비스명은 기능, 조회 대상 또는 호환 대상을 설명하기 위해서만 사용합니다.

대법원 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조)의 데이터베이스 권리와 [형법 제314조 제2항](https://www.law.go.kr/법령/형법/제314조)의 현실적 서비스 장애·영업 방해 책임은 별도로 판단됩니다.

- 공개정보 자동 수집 기능은 반드시 개인의 정보 조회용으로만 사용합니다.
- 조직적·체계적·대량 크롤링, 별도 DB 구축, 재판매·원본 재배포를 하지 않습니다.
- 특정 브랜드·업체의 영업이나 서비스를 방해하지 않도록 호출을 최소화하고 공격적 polling·병렬 대량 호출을 하지 않습니다.
- 로그인·유료벽·CAPTCHA·접근통제·rate limit·IP 차단을 우회하거나 차단 회피를 하지 않으며, 접근 거부 시 즉시 중단합니다.
- 적용되는 약관·API 조건과 저작권·데이터베이스권·개인정보 의무를 준수합니다.

이 문서는 적법성을 보증하는 법률 자문이 아닙니다.

# 상표 사용 법적 고지 — `kakao-bar-nearby`

이 스킬에서 `카카오맵` 및 `Kakao Map` 명칭은 주변 술집 검색·장소 상세 확인에 사용하는 **대상 지도 서비스**를 식별하기 위해 사용한다. 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)

{
  "name": "kakao-bar-nearby",
  "description": "Use when the user asks for nearby bars or 근처 술집. Ask for the user's location, search with the official Kakao Local API, then follow returned Kakao Map detail links for open-now, menu, and seating hints. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
  "profiles": [
    "proxy",
    "browser",
    "action:booking"
  ],
  "frontmatter": "name: kakao-bar-nearby\ndescription: Use when the user asks for nearby bars or 근처 술집. Ask for the user's location, search with the official Kakao Local API, then follow returned Kakao Map detail links for open-now, menu, and seating hints. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: food\n  locale: ko-KR\n  phase: v1"
}

---
name: kakao-bar-nearby
description: Use when the user asks for nearby bars or 근처 술집. Ask for the user's location, search with the official Kakao Local API, then follow returned Kakao Map detail links for open-now, menu, and seating hints. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.
license: MIT
metadata:
  category: food
  locale: ko-KR
  phase: v1
---

# kakao-bar-nearby

<!-- 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 kakao-bar-nearby
```

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 kakao-bar-nearby
```

Keep the CLI and every coding-agent skill install current (including Vercel Agent Skills) with:

```bash
npx -y @nomadamas/k-skill@0 update
```

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/kakao-bar-nearby/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 kakao-bar-nearby 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.