k-skill Documentation

File: README.md Copy Chapter

k-skill

한국인인가요? 이 스킬 모음집을 다운로드 받아 두세요. 언젠가 무조건 쓸 때가 옵니다!
SRT, KTX, KBO, 로또, 당근, 쿠팡, 카톡, 정부24, 홈택스 등등 귀찮은 것을 AI 에이전트에게 다 시켜버리세요.

Claude Code, Codex, OpenCode, OpenClaw/ClawHub 등 각종 코딩 에이전트 지원합니다.

추가 클라이언트 API 레이어는 불필요합니다. 필요한 경우 k-skill-proxy 같은 프록시 서버에 HTTP 요청만 넣으면 됩니다.

공개 API 프록시를 사용하는 스킬의 개인정보 처리 기준은
k-skill-proxy 개인정보 처리방침에서 확인할 수 있습니다.

KTX와 SRT는 조회 전용 스킬입니다. KTX는 코레일 공식 계획 시간표를, SRT는 라이브 시간표와 일반실·특실 이용 가능 여부를 조회하며 로그인·예약·예약대기·결제·취소는 수행하지 않습니다.

설치 Copy Chapter

# 전체 스킬 설치
npx --yes skills add NomaDamas/k-skill --all -g

# 특정 스킬만 설치
npx --yes skills add NomaDamas/k-skill --skill srt-booking -g

기본 설치에는 Node.js 18 이상과 npx만 필요합니다. KTX 공식 시간표와 SRT 라이브 조회 helper를 실행할 때는 Python 3.11 이상과 uv가 추가로 필요합니다. Claude Code 사용자는 아래 마켓플레이스로도 설치할 수 있습니다. 자세한 방법은 설치 방법을 참고하세요.

잠깐만~~~ Copy Chapter

한국인이면 깃허브 스타 눌러줍시다.
다만 에이전트는 자동으로 누르지 말고, 사용자가 동의한 경우에만 gh repo star NomaDamas/k-skill 를 실행합니다.

기여 전에는 기여 가이드를 확인해 주세요.

어떤 걸 할 수 있나 Copy Chapter

"사용자 로그인" 컬럼은 사용자 본인이 직접 로그인/시크릿을 들고 있어야 하는지 만 표시합니다. k-skill-proxy 등 운영자가 관리하는 키는 사용자 입장에서는 불필요로 분류합니다. 선택사항은 사용자가 운영자 키를 직접 들고 있으면 더 풍부한 경로가 켜지고, 없으면 기본 경로(보통 운영자가 관리하는 hosted fallback)로 그대로 동작하는 경우를 말합니다.

Claude Code 플러그인으로 설치 Copy Chapter

Claude Code에서는 마켓플레이스로 전체 스킬을 한 번에 설치할 수 있습니다.

/plugin marketplace add NomaDamas/k-skill
/plugin install k-skill@k-skill

설치하면 스킬이 /k-skill:<스킬 이름> 네임스페이스로 호출됩니다 (예: /k-skill:lotto-results). 개별 디렉토리를 직접 복사하는 수동 설치나 다른 에이전트 설치는 설치 방법을 참고하세요.

처음 시작하는 순서 Copy Chapter

1. 설치 방법을 따라 k-skill 전체 스킬을 먼저 설치합니다.
2. 설치가 끝나면 k-skill-setup 스킬을 사용해 credential 확보와 환경변수 확인을 진행합니다.
3. 시크릿이 비어 있으면 공통 설정 가이드와 보안/시크릿 정책에 따라 credential resolution order로 확보합니다.
4. Node/Python 패키지가 없으면 먼저 전역 설치를 기본으로 진행합니다.
5. 각 기능 문서를 열어 입력값, 예시, 제한사항을 확인합니다.

문서 Copy Chapter

포함된 기능 Copy Chapter

• SRT 라이브 시간표 조회
• KTX 공식 시간표 조회
• 고속버스 예매
• 시외버스 예매
• 자연휴양림 빈 객실 조회
• 카카오톡 Mac 아카이브 검색
• 서울 지하철 도착정보 조회
• 서울 실시간 혼잡도 조회
• 한국 대중교통 길찾기 가이드
• 카카오맵 가이드
• 지하철 분실물 조회 가이드
• 긱뉴스 조회 가이드
• 한국 날씨 조회 가이드
• 한국 공휴일·특일 조회 가이드
• 서울 기상 위험 시간대 조회 가이드
• 사용자 위치 미세먼지 조회
• 한강 수위 정보 가이드
• 한국 법령 검색 가이드
• 한국 개인정보처리방침·이용약관 자동 생성 가이드
• 사업자등록정보 확인 가이드
• 사업자 실사 종합 가이드
• 국민연금 가입 사업장 조회 가이드
• 국세 체납 명단공개 검색 가이드
• 금융위 기업기본정보 조회 가이드
• 부정당제재업체 조회 가이드
• 나라장터 발주계획 검색 가이드
• 국방전자조달시스템 공고 조회 가이드
• 인허가 영업상태 조회 가이드
• 장수 점포 레이더 가이드
• 창업진흥원 K-Startup 조회 가이드
• 국회 의안·표결 조회 가이드
• 한국 사업자 장부 자동화 가이드
• 팝빌 all-service API helper
• 한국 부동산 실거래가 조회 가이드
• 한국 주택 공시가격 조회 가이드
• 개별공시지가 조회 가이드
• LH 청약 공고문 조회 가이드
• SH 청약·주택 공고문 조회 가이드
• S2B 학교장터 공고 조회 가이드
• 법원 경매 부동산 매각공고 조회 가이드
• 장학금 검색 및 조회 가이드
• 생활쓰레기 배출정보 조회 가이드
• 학교 급식 식단 조회 가이드
• 도서관 도서 조회 가이드
• KERIS/RISS 학술자료 검색 가이드
• 기부처 조회 가이드
• 의약품 안전 체크 가이드
• 식품 안전 체크 가이드
• 한국 주식 정보 조회 가이드
• 국가데이터처 KOSIS 통계 조회 가이드
• 한국은행 ECOS 경제통계 조회 가이드
• 조선왕조실록 검색 가이드
• 한국 국가유산 검색 가이드
• 한국 특허 정보 검색 가이드
• KR WHOIS 조회 가이드
• 근처 가장 싼 주유소 찾기 가이드
• 근처 공중화장실 찾기 가이드
• 근처 공영주차장 찾기 가이드
• 전기차 충전소 위치·상태 조회 가이드
• 고속도로 교통량·소통·CCTV 조회 가이드
• 전기차 보조금 현황 조회 가이드
• 근처 응급실 병상 상태 확인 가이드
• 장기요양·건강검진기관 조회 가이드
• 한국 마라톤 일정 조회 가이드
• KBO 경기 결과 조회
• KBL 경기 결과 가이드
• K리그 경기 결과 조회
• LCK 경기 분석 가이드
• 토스증권 조회 가이드
• 대신증권 리포트 조회 가이드
• 공연 일정·잔여석 조회 가이드
• KOPIS 공연 조회 가이드
• 로또 당첨 확인
• 등기부등본 자동화 가이드
• 건축물대장 표제부 조회 가이드
• 법인등기 신청 컨설팅
• 지급명령 신청 보조 가이드
• HWP 문서 조회/변환
• HWP 문서 편집
• HWP 레이아웃·IR 디버깅
• 근처 술집 조회 가이드
• 우편번호 검색
• 다이소 상품 조회
• 마켓컬리 상품 조회 가이드
• 올리브영 검색 가이드
• 영화관 검색 가이드
• 올라포케 역삼 포케 가이드
• 마이리얼트립 MCP 검색 가이드
• 항공권 가격 조회 가이드
• 택배 배송조회
• 쿠팡 상품 검색
• 오늘의집 오늘의딜 조회
• 번개장터 검색 가이드
• 당근 중고거래 검색 가이드
• 당근부동산 검색 가이드
• 당근알바 검색 가이드
• 당근중고차 검색 가이드
• 한국어 맞춤법 검사 가이드
• 네이버 블로그 리서치 가이드
• 네이버 쇼핑 가격비교 가이드
• 다나와 최저가 비교 가이드
• 네이버 뉴스 검색 가이드
• 한국일보 뉴스 조회 가이드
• 한국어 글자 수 세기 가이드
• 한국어 유행어 글쓰기 가이드
• 한국어 AI 윤문 가이드
• 한국 중세 국어풍 변환 가이드
• 사주 운세 풀이 가이드
• 작명소 가이드
• K-스킬 공통 설정 가이드
• K-스킬 클리너 가이드
• 릴리스/배포 가이드

설치 기본 흐름은 "전체 스킬 설치 → k-skill-setup 실행 → 개별 기능 사용" 입니다.

라이선스 Copy Chapter

이 저장소의 기본 라이선스는 MIT입니다. 단, 프록시 서버 관련 디렉토리는 AGPL-3.0-only가 적용됩니다.

• packages/k-skill-proxy/ — AGPL-3.0-only
• infra/k-skill-proxy-dashboard/ — AGPL-3.0-only (프록시 모니터링 스택)

제3자 상표와 서비스명은 기능·조회 대상·호환 대상을 설명하기 위해서만 사용하며, 별도 명시가 없는 한 해당 권리자나 운영사의 공식 기능·지원·제휴·승인 또는 협업을 의미하지 않습니다. 공개정보 조회 기능은 개인적·비조직적 용도로만 사용하고, 대량·체계적 크롤링이나 접근통제 회피, 서비스 장애·영업 방해를 해서는 안 됩니다.

File: docs/features/bunjang-search.md Copy Chapter

번개장터 검색 가이드

이 기능으로 할 수 있는 일 Copy Chapter

upstream bunjang-cli / pinion05/bunjangcli 를 사용해 번개장터 검색, 상세조회, 선택적 찜/채팅, 대량 수집, AI TOON export 를 처리한다.

• search 로 검색
• item get / item list 로 상세조회
• favorite add / favorite remove / favorite list 로 선택적 찜 관리
• chat list / chat start / chat send 로 선택적 채팅
• --start-page, --pages, --max-items, --with-detail, --output 으로 대량 수집
• --ai --output <directory> 로 TOON chunk 저장

가장 중요한 규칙 Copy Chapter

이 기능은 upstream 원본을 그대로 쓴다.
k-skill 안에 번개장터 수집기를 새로 넣지 않고, CLI first 문서/스킬만 유지한다.
즉 기본 경로는 아래다.

1. npx --yes bunjang-cli ...
2. 반복 사용이면 npm install bunjang-cli

먼저 필요한 것 Copy Chapter

• 인터넷 연결
• node 22+
• npx 또는 npm
• 선택적으로 interactive TTY 터미널

2026-04-06 기준 npm view bunjang-cli version 은 0.2.1 이고, README 요구 사항은 Node.js 22+ 다.

가장 빠른 시작: npx CLI Copy Chapter

npx --yes bunjang-cli --help
npx --yes bunjang-cli --json auth status
npx --yes bunjang-cli --json search "아이폰" --max-items 3 --sort date
npx --yes bunjang-cli --json item get 354957625

반복 사용이면 전역 설치도 가능하다.

npm install bunjang-cli
export NODE_PATH="$(npm root -g)"
bunjang-cli --help

로그인은 선택적 interactive 플로우 Copy Chapter

npx --yes bunjang-cli auth login
npx --yes bunjang-cli auth logout
npx --yes bunjang-cli --json auth status

• auth login 은 브라우저에서 로그인 후 터미널로 돌아와 Enter 를 눌러야 완료된다.
• 즉 TTY / interactive 세션 이 아닌 환경에서는 로그인 완료 처리가 멈출 수 있다.
• 그래서 기본 문서는 검색/상세조회/대량 수집을 먼저 안내하고, 찜/채팅은 로그인된 경우에만 선택적으로 진행한다.

기본 흐름 Copy Chapter

1. 검색 Copy Section

npx --yes bunjang-cli search "아이폰"
npx --yes bunjang-cli search "아이폰" --price-min 500000 --price-max 1200000
npx --yes bunjang-cli search "아이폰" --sort date
npx --yes bunjang-cli --json search "아이폰" --max-items 5

검색 결과에는 매입글/광고/악세서리 글이 섞이고, live search payload 에서는 location 이 noisy 하거나 description / status 가 빠질 수 있다. 그래서 검색 단계는 제목/가격 중심 1차 triage 로만 쓰고, 세부 판단은 상세조회 이후로 미룬다.

2. 상세조회 Copy Section

npx --yes bunjang-cli item get 354957625
npx --yes bunjang-cli --json item get 354957625
npx --yes bunjang-cli --json item list --ids 354957625,354801707

상세에서는 price, description, location, category, status, sellerName, sellerReviewCount, favoriteCount, transportUsed 를 우선 본다. 즉 description / status / 믿을 만한 location 이 필요하면 반드시 item get 또는 --with-detail 이후 에만 판정한다.

3. 대량 수집 Copy Section

npx --yes bunjang-cli search "아이폰" \
  --start-page 1 \
  --pages 5 \
  --max-items 50 \
  --sort date \
  --with-detail \
  --output artifacts/bunjang-iphone.json

export 검증 시에는 결과 파일 존재 여부와 top-level items[] 안의 summary / detail / optional error 구조, item 별 sourcePage 또는 summary.raw.page 를 함께 확인한다.

4. AI TOON chunk Copy Section

npx --yes bunjang-cli search "아이폰" \
  --start-page 1 \
  --pages 5 \
  --max-items 50 \
  --with-detail \
  --ai \
  --output artifacts/bunjang-iphone-ai

• --ai 에서는 --output 이 디렉토리 여야 한다.
• 결과는 items-1.toon 같은 chunk 로 나뉜다.
• 대량 후보를 여러 에이전트에게 분산 평가시키기 좋다.

5. 찜/채팅은 로그인 후에만 Copy Section

npx --yes bunjang-cli --json favorite list
npx --yes bunjang-cli --json favorite add 354957625
npx --yes bunjang-cli --json favorite remove 354957625
npx --yes bunjang-cli --json chat list
npx --yes bunjang-cli --json chat start 354957625 --message "안녕하세요"
npx --yes bunjang-cli --json chat send 84191651 --message "상품 상태 괜찮을까요?"

• favorite 와 chat 은 로그인이 필요한 선택적 기능이다.
• 기본 검색/분석 요청이라면 실행하지 않고 명령만 안내한다.
• 검증이 필요하면 favorite list 로 세션을 먼저 확인한 뒤 add/remove 를 왕복 실행한다.

라이브 확인 메모 Copy Chapter

2026-04-06 기준 아래 흐름을 실제로 실행해 응답을 확인했다.

• npx --yes bunjang-cli --help → top-level commands (auth, search, item, chat, favorite, purchase) 확인
• npx --yes bunjang-cli --json auth status → authenticated: false, headfulLoginRequired: true 확인
• npx --yes bunjang-cli --json search "아이폰" --max-items 1 → items[0].id = 354957625, transportUsed = browser 확인
• npx --yes bunjang-cli --json item get 354957625 → description, location, sellerReviewCount, favoriteCount, transportUsed = api 확인

같은 날짜에 search summary 는 title/price 중심 triage 용으로만 안전했고, status / description 은 summary 에서 안정적으로 오지 않았다. 그래서 문서에서는 상세 필드 의존 판단을 item get / --with-detail 뒤로 고정한다.

같은 날짜에 favorite list 는 로그인 브라우저를 띄운 뒤 터미널 Enter 를 기다렸다. 그래서 문서에서는 찜/채팅을 로그인 후 선택적으로만 실행 하도록 고정한다.

제한사항 Copy Chapter

• 로그인 없는 환경에서는 찜/채팅/구매 흐름을 바로 검증하기 어렵다.
• 검색 결과에는 매입글/광고/악세서리 노이즈가 섞일 수 있다.
• DOM/API 변경에 따라 browser transport 동작이 깨질 수 있다.
• 구매 자동 확정/결제는 다루지 않는다.

참고 링크 Copy Chapter

• npm package: https://www.npmjs.com/package/bunjang-cli
• upstream repo: https://github.com/pinion05/bunjangcli

File: docs/features/cheap-gas-nearby.md Copy Chapter

근처 가장 싼 주유소 찾기 가이드

이 기능으로 할 수 있는 일 Copy Chapter

• 현재 위치 기준 근처 최저가 주유소 검색
• 휘발유/경유 기준 nearby 가격 비교
• Opinet 공식 API(aroundAll.do, detailById.do) 기반 요약
• 셀프 여부, 세차장, 경정비, 품질인증 여부까지 함께 정리

먼저 필요한 것 Copy Chapter

• 인터넷 연결
• node 18+
• cheap-gas-nearby package 또는 이 저장소 전체 설치

사용자 쪽에서 별도 OPINET_API_KEY 를 준비할 필요가 없다. 기본적으로 https://k-skill-proxy.nomadamas.org 프록시를 경유하며, upstream key는 proxy 서버에서만 주입한다.

가장 먼저 할 일 Copy Chapter

이 기능은 반드시 현재 위치를 먼저 물어본 뒤 실행합니다.

권장 질문 예시:

현재 위치를 알려주세요. 동네/역명/랜드마크/위도·경도 중 편한 형식으로 보내주시면 근처에서 가장 싼 주유소를 찾아볼게요.

제품을 안 알려주면 보통 휘발유(B027) 기준으로 시작하고, 경유가 필요하면 D047 로 바꿉니다.

입력값 Copy Chapter

• 동네/상권: 강남, 성수동, 판교
• 역명/랜드마크: 서울역, 강남역, 코엑스
• 좌표: 37.55472, 126.97068
• 제품코드: B027(휘발유), D047(경유)

위치 문자열은 Kakao Map anchor 검색으로 WGS84 좌표를 잡고, 내부적으로 KATEC 으로 변환해 Opinet nearby 검색에 사용합니다.

공식 표면 Copy Chapter

• Opinet 오픈 API 안내: https://www.opinet.co.kr/user/custapi/openApiInfo.do
• 반경 내 주유소: https://www.opinet.co.kr/api/aroundAll.do
• 주유소 상세정보(ID): https://www.opinet.co.kr/api/detailById.do
• 지역코드: https://www.opinet.co.kr/api/areaCode.do
• Kakao Map 모바일 검색: https://m.map.kakao.com/actions/searchView
• Kakao Map 장소 패널 JSON: https://place-api.map.kakao.com/places/panel3/<confirmId>

Opinet nearby 검색의 핵심 파라미터:

• x, y: 기준 위치 KATEC 좌표
• radius: 반경(m, 최대 5000)
• prodcd: B027, D047, B034, C004, K015
• sort=1: 가격순

기본 흐름 Copy Chapter

1. 유저에게 현재 위치를 먼저 묻습니다.
2. 위치 문자열을 받으면 Kakao Map으로 anchor 후보를 고르고 좌표를 확보합니다.
3. 좌표를 WGS84 → KATEC 으로 변환합니다.
4. Opinet aroundAll.do 를 sort=1 가격순으로 조회합니다.
5. 상위 후보는 detailById.do 로 재조회해 주소/전화번호/편의시설을 보강합니다.
6. 가격순 상위 3~5개만 짧게 응답합니다.

Node.js 예시 Copy Chapter

const { searchCheapGasStationsByLocationQuery } = require("cheap-gas-nearby");

async function main() {
  const result = await searchCheapGasStationsByLocationQuery("서울역", {
    productCode: "B027",
    radius: 1000,
    limit: 3
  });

  for (const item of result.items) {
    console.log(`${item.name}: ${item.price}원/L, ${item.distanceMeters}m, ${item.roadAddress}`);
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Offline smoke example Copy Chapter

실제 키가 없는 환경에서도 패키지 동작은 fixture 기반으로 검증할 수 있습니다.

node --test packages/cheap-gas-nearby/test/index.test.js

운영 팁 Copy Chapter

• 프록시 서버가 내려가 있거나 upstream key가 없으면 503 을 반환하므로 상태를 안내합니다.
• 서울역/강남처럼 넓은 질의는 anchor 위치가 흔들릴 수 있으니 필요하면 더 구체적인 역 출구/동 이름을 한 번 더 받습니다.
• 동일 가격이면 거리순으로 다시 정렬해 보여주는 편이 좋습니다.
• 결과가 너무 많으면 반경을 1000m 또는 2000m 정도로 유지하는 편이 읽기 쉽습니다.

주의할 점 Copy Chapter

• Opinet Open API 인증키는 proxy 서버에서만 관리합니다. 사용자/client 쪽 secrets 파일에는 넣지 않습니다.
• Kakao Map anchor 검색은 위치 기준점만 잡기 위한 보조 단계이고, 최종 가격/순위 데이터는 Opinet을 기준으로 합니다.
• Opinet 응답의 좌표는 KATEC 이므로 WGS84와 혼동하면 안 됩니다.

File: docs/features/corporate-registration-consulting.md Copy Chapter

법인등기 신청 컨설팅

corporate-registration-consulting은 일반 영리 주식회사 발기설립 등기를 처음 진행하는 사용자를 위해 저장된 HWP 양식 사본을 채우는 법인설립등기 준비 스킬이다. 모집설립은 일반적이지 않으므로 기본 플로우에서 제외한다.

핵심 원칙 Copy Chapter

• 런타임 지침은 corporate-registration-consulting/SKILL.md가 담당한다.
• 실제 작성은 Markdown 초안이 아니라 저장된 HWP 양식 사본을 레포 밖 비공개 작업 디렉터리에 복사해 진행한다. 최종 산출물은 실제 .hwp 사본이다.
• 정관은 templates/attachment-hwp/standard-articles-startup-moj.hwp 또는 templates/attachment-hwp/articles-of-incorporation.hwp를 우선 사용한다.
• 단순 replace-all은 shortcut일 뿐이며, 각 HWP의 상단·본문·표 셀·하단 날짜·서명/날인란을 한 장 한 장 순차 확인한다.
• 자리표시자와 실제 사용자 입력값을 구분하고, 개인정보가 들어간 산출물은 레포에 커밋하지 않는다.

필수 문서와 양식 Copy Chapter

인터넷등기소/온라인법인설립시스템 제출 전 대조용 저장된 양식 경로와 공식 출처 대조는 corporate-registration-consulting/templates/official-form-sources.md, 제출 체크리스트는 corporate-registration-consulting/templates/incorporation-document-pack.md를 기준으로 한다.

반드시 포함할 항목:

• 주식회사설립등기신청서(발기설립): templates/official/form-65-1-stock-company-incorporation-promoter.hwp
• 정관, 주식발행사항 동의/상법 제291조 사항 증명정보, 주식인수증, 발기인회의사록, 주주명부, 조사보고서, 취임승낙서, 이사회의사록, 인감신고서, 위임장: templates/attachment-hwp/*.hwp
• 등록면허세 영수필확인서, 등기신청수수료 영수필확인서
• 등기이사 개인 인감증명서 또는 본인서명사실확인서
• 등기이사 주민등록초본/등본 등 주소 확인 증빙
• 주금납입/잔고증명

조건부로 명의개서대리인, 현물출자·재산인수 등 변태설립사항, 인허가 업종, 정관 공증·의사록 인증 필요 여부를 확인한다.

중점 확인 Copy Chapter

• 정관 제2조 목적에는 실제 사업 업태·종목을 채운다.
• 정관 맨 마지막 작성일자, 발기인 성명, 서명/기명날인, 여러 장 문서의 간인을 확인한다.
• 인감신고서 제출을 위해 실제 법인인감 도장을 준비하도록 안내한다.
• 등록면허세·지방교육세·과밀억제권역/대도시 중과는 지방세법 제28조 및 위택스/관할 지자체 결과를 기준으로 확인한다.
• 소프트웨어 업종은 조세특례제한법 제6조 등 감면/중과 제외 가능성을 체크하되 확정하지 않는다.

면책 Copy Chapter

이 기능은 참고용이며 법률·세무 자문, 법무사 대행이 아니다. 에이전트는 인터넷등기소/위택스 로그인, 전자서명, 세금 납부, 등기 제출, 사용자 사칭, 최종 법률 판단, 최종 세무 판단을 지원하지 않는다. 실제 제출은 사용자가 직접 수행하고 제출 전 관할 등기소·위택스/지자체·법무사·변호사·세무사 확인을 권한다.

File: docs/features/coupang-product-search.md Copy Chapter

쿠팡 상품 검색

coupang-product-search는 k-skill-proxy의 공식 Coupang Partners API
프록시를 통해 상품을 조회한다. 로컬 MCP checkout이나 제3자 hosted fallback을
사용하지 않는다.

호출 경로 Copy Chapter

skill → k-skill-proxy /v1/coupang/products/search
      → 서버 보관 COUPANG_ACCESS_KEY/COUPANG_SECRET_KEY
      → Coupang Partners API /products/search

proxy 서버가 HMAC-SHA256 Authorization 헤더를 생성하므로 caller는 쿠팡
키를 볼 수도, 전달할 필요도 없다.

설정 Copy Chapter

프록시 운영 환경에 다음 두 변수를 설정한다.

COUPANG_ACCESS_KEY=...
COUPANG_SECRET_KEY=...

둘 중 하나라도 없으면 endpoint는 503 upstream_not_configured를 반환한다.
키를 query string, shell argument, 문서, 로그에 넣지 않는다.

검색 API Copy Chapter

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/coupang/products/search" \
  --data-urlencode 'keyword=무선청소기' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'subId=k-skill'

응답 items는 product_id, title, price, price_text, url,
image_url, review_count, score, is_rocket, is_free_shipping을
제공한다. 가격과 배송 상태는 실시간으로 바뀔 수 있다.

답변 규칙 Copy Chapter

• is_rocket으로 로켓배송 후보와 일반배송 후보를 구분한다.
• 예산이 있으면 price를 기준으로 필터링한다.
• 후보는 보통 3~5개로 요약한다.
• 상품 링크를 제공할 때 다음 고지를 함께 표시한다.

쿠팡 파트너스 활동을 통해 일정액의 수수료를 제공받을 수 있습니다.

오류 Copy Chapter

• 400 bad_request: 검색어가 없거나 너무 짧다.
• 503 upstream_not_configured: 프록시 키 미설정.
• 502 upstream_forbidden: 쿠팡 API 키 또는 권한 거부.
• 502 upstream_error / upstream_unavailable: 쿠팡 API 장애 또는 네트워크 오류.

오류를 임의의 scraping, 구형 MCP, 또는 다른 hosted endpoint로 우회하지 않는다.

출처 Copy Chapter

• Coupang Open API HMAC 문서
• k-skill-proxy feature guide

File: docs/features/court-auction-notice-search.md Copy Chapter

법원 경매 부동산 매각공고 조회

대한민국 법원이 운영하는 공식 법원경매정보 사이트(courtauction.go.kr) 의 매각공고와 사건정보를 에이전트가 활용할 수 있는 JSON 형태로 변환해서 돌려준다.

참고용입니다. 실제 입찰 전에는 반드시 해당 법원의 원문 매각공고와 매각물건명세서를 직접 확인하세요. 본 스킬은 read-only이며, 입찰서 자동 작성·자동 제출은 지원하지 않습니다.

무엇을 할 수 있나 Copy Chapter

• ✅ Workflow A — 매각공고 브라우징: 매각기일·법원·기일/기간 입찰을 조건으로 매각공고 목록 → 그 공고 안의 사건번호·용도·주소·감정평가액·최저매각가격 펼치기
• ✅ Workflow B — 사건번호 직접 조회: 법원사무소코드 + 사건번호(2024타경100001) → 사건정보·물건내역·매각기일별 이력·배당요구종기
• ✅ Workflow C — 부동산 물건 자유 조건검색: 지역·용도·가격대·면적·유찰횟수·매각기일 조건 → 물건 목록 JSON
• ✅ 법원사무소 코드(60+개) + 입찰구분 코드(기일입찰=000331, 기간입찰=000332) + Workflow C용 대표 용도/지역 코드 변환
• ✅ 3-tier transport — direct HTTP 1차, platform-aware runtime browser fallback(macOS: Aside → BrowserOS → Chrome, 기타: BrowserOS → Aside → Chrome), 로컬 Playwright(rebrowser-playwright/playwright-core) launch fallback
• ✅ 안티봇 가드 — 호출 간 ≥2초 jitter, 세션당 호출 budget, data.ipcheck === false 즉시 BLOCKED throw

무엇을 할 수 없나 (별도 follow-up 이슈) Copy Chapter

• ❌ Workflow D 일별/월별 캘린더
• ❌ 매각물건 사진(전경/개황/내부) URL 노출
• ❌ 매각물건명세서·현황조사서·감정평가서 PDF 다운로드
• ❌ 동산(자동차·중기) 경매

차단(BLOCKED) 정책 Copy Chapter

courtauction.go.kr 은 자동화 호출에 매우 민감해서 빠른 연속 조회 시 IP가 약 1시간 차단됩니다. 본 스킬은 다음과 같이 보수적으로 동작합니다.

• 호출 간 최소 2초 + jitter 0~1초 대기 (override: --min-delay-ms 3000)
• 세션당 호출 budget 10회 (override: --max-calls 5)
• data.ipcheck === false 또는 응답 메시지에 "차단" 포함 시 → BLOCKED 에러를 즉시 throw, 자동 재시도 금지 (차단 연장 위험)

차단되면 같은 IP에서 약 1시간을 기다려야 합니다. 그 사이에는 다른 IP 또는 사람이 직접 사이트에 접속해서 차단 해제 화면을 거칩니다.

CLI 사용 Copy Chapter

court-auction-notice-search -h
court-auction-notice-search codes courts --pretty | head -40
court-auction-notice-search codes bid-types --pretty
court-auction-notice-search codes usages --pretty
court-auction-notice-search codes regions --pretty
court-auction-notice-search notices --date 2026-04 --court-code B000210 --bid-type date --pretty
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
court-auction-notice-search case --court-code B000210 --case-number "2024타경100001" --pretty

Node.js 사용 Copy Chapter

const {
  searchSaleNotices,
  getSaleNoticeDetail,
  getCaseByCaseNumber,
  searchProperties
} = require("court-auction-notice-search");

const notices = await searchSaleNotices({
  date: "2026-04", // 월 전체 조회. 일자 입력은 같은 월 조회 후 해당일만 필터링
  courtCode: "B000210",
  bidType: "date"
});

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.address);
    console.log("  감정 ", item.appraisedPrice, "최저 ", item.minimumSalePrice);
  }
}

const caseInfo = await getCaseByCaseNumber({
  courtCode: "B000210",
  caseNumber: "2024타경100001"
});

const properties = await searchProperties({
  region: { sido: "서울특별시", sigungu: "11680", dong: "11680101" },
  usage: { large: "건물" },
  priceRange: { min: 100000000, max: 500000000 },
  saleDate: { from: "2026-05-01", to: "2026-05-20" },
  flbdCount: { min: 1 },
  page: 1,
  pageSize: 20
});

사이트 내부 endpoint (직접 캡처한 것) Copy Chapter

세션 cookie(JSESSIONID, WMONID)는 endpoint별 진입 화면을 먼저 열어 받아둡니다. 매각공고/상세는 GET /pgj/index.on?w2xPath=/pgj/ui/pgj100/PGJ143M01.xml&pgjId=143M01, 물건 자유 조건검색(Workflow C)은 GET /pgj/index.on?w2xPath=/pgj/ui/pgj100/PGJ151F00.xml&pgjId=151F00 으로 warmup 합니다.

브라우저 fallback 런타임 Copy Chapter

Workflow C direct HTTP가 WAF-style HTTP 400을 반환하거나, 명시적으로 fallbackOnBlocked:true 를 준 BLOCKED 응답일 때만 browser fallback을 쓴다. fallback 순서는 다음과 같다.

1. runtime browser (기본 auto) — k-skill-browser-runtime으로 macOS에서는 Aside Browser REPL(aside repl), BrowserOS GUI CDP(http://127.0.0.1:9100), Chrome/Chromium CDP(http://127.0.0.1:9222) 순서로 fallback하고 기타 플랫폼에서는 BrowserOS를 먼저 시도한다. KSKILL_BROWSER_PROVIDER(auto/browseros/aside/chrome-cdp), KSKILL_BROWSEROS_CDP_URL, KSKILL_CHROME_CDP_URL, KSKILL_ASIDE_COMMAND, provider, cdpUrl 로 조정할 수 있다. BrowserOS/Aside를 launch하거나 BrowserOS를 headless로 띄우지 않는다.
2. Local Playwright launch fallback — CDP endpoint가 닿지 않을 때만 이 패키지가 직접 소유하는 로컬 브라우저를 chromium.launch({ headless })로 띄운다. 이 로컬 브라우저는 패키지가 닫을 수 있다.

Runtime으로 붙은 BrowserOS/Aside/Chrome 세션은 사용자 소유이므로 fallback 종료 시 adapter 생성 page/context/tab만 정리하고 브라우저/프로필은 닫지 않는다. 로그인/CAPTCHA/payment/전자서명/irreversible 액션은 자동화하지 않는다.

설치 Copy Chapter

npm install court-auction-notice-search
# Runtime browser fallback 은 k-skill-browser-runtime regular dependency로 자동 설치된다.
# CDP가 unavailable일 때 로컬 launch fallback까지 쓰려면 (선택):
npm install rebrowser-playwright
# 또는
npm install playwright-core

관련 이슈 Copy Chapter

• 이 패키지는 Issue #167 에서 출발했고, #184에서 Workflow C 자유 조건검색을 추가했습니다.
• 캘린더·물건 사진·PDF·동산 경매는 별도 follow-up 이슈로 분리되어 추적됩니다.

File: docs/features/daangn-cars-search.md Copy Chapter

당근중고차 검색 가이드 (`daangn-cars-search`)

당근중고차 공개 웹 데이터 표면을 사용해 지역·키워드·가격 조건 기반 차량을 검색하고, 개별 차량 상세를 읽기 전용으로 확인하는 스킬입니다.

사용 시나리오 Copy Chapter

• "당근중고차 합정동 레이 찾아봐"
• "당근에서 천만원 이하 중고차 검색해줘"
• "이 당근 중고차 URL 상세 요약해줘"

구현 표면 Copy Chapter

브라우저 자동화, 로그인, 채팅, 문의, 구매 자동화를 사용하지 않습니다.

1. 지역 해석: https://www.daangn.com/kr/api/v1/regions/keyword?keyword=<지역명>
2. 검색: https://www.daangn.com/kr/cars/?in=<지역명>-&onlyOnSale=1&_data=routes/kr.cars._index
3. 상세: <차량 URL>?_data=routes%2Fkr.cars.%24car_post_id

로컬 실행 Copy Chapter

npx -y @nomadamas/k-skill@0 exec daangn-cars-search scripts/daangn_cars.py -- search "레이" --region "합정동" --limit 5
npx -y @nomadamas/k-skill@0 exec daangn-cars-search scripts/daangn_cars.py -- search --region "합정동" --price-max 10000000 --limit 5
npx -y @nomadamas/k-skill@0 exec daangn-cars-search scripts/daangn_cars.py -- detail "https://www.daangn.com/kr/cars/.../"

지역 필터 Copy Chapter

지역명은 당근 region API로 내부 id를 해석한 뒤 in=<지역명>- 형태로 검색 URL에 넣습니다.

합정동 → 서울특별시 마포구 합정동, id=231 → in=합정동-231

출력 해석 Copy Chapter

검색 결과는 title, price, price_text, region, status, driveDistance, carData, chatRoomCount, url을 우선 확인합니다. 차량 연식, 주행거리, 사고/정비 이력처럼 원문 의존도가 높은 정보는 상세 조회의 carPost 원문을 함께 확인합니다.

제한사항 Copy Chapter

• 공개 Remix _data route 이름이나 JSON shape가 바뀌면 실패할 수 있습니다.
• 문의, 시승 예약, 구매, 결제, 채팅 자동화는 실행하지 않습니다.
• 가격·판매 상태는 실시간으로 바뀔 수 있어 원문 URL을 함께 제시합니다.

File: docs/features/daangn-jobs-search.md Copy Chapter

당근알바 검색 가이드 (`daangn-jobs-search`)

당근알바 공개 웹 데이터 표면을 사용해 키워드·지역 기반 알바 공고를 검색하고, 개별 공고 상세를 읽기 전용으로 확인하는 스킬입니다.

사용 시나리오 Copy Chapter

• "당근알바 합정동 카페 알바 찾아봐"
• "홍대 근처 주말 알바 검색해줘"
• "이 당근알바 공고 상세 요약해줘"

구현 표면 Copy Chapter

브라우저 자동화, 로그인, 채팅, 지원, 문의 자동화를 사용하지 않습니다.

1. 지역 해석: https://www.daangn.com/kr/api/v1/regions/keyword?keyword=<지역명>
2. 검색: https://www.daangn.com/kr/jobs/?in=<지역명>-&search=<키워드>&_data=routes/kr.jobs._index
3. 상세: <공고 URL> → jobs.daangn.com/job-posts/ 공개 HTML의 title/meta/JSON-LD(헬퍼는 legacy _data를 먼저 시도 후 빈 응답이면 HTML 메타로 fallback)

로컬 실행 Copy Chapter

npx -y @nomadamas/k-skill@0 exec daangn-jobs-search scripts/daangn_jobs.py -- search "카페" --region "합정동" --limit 5
npx -y @nomadamas/k-skill@0 exec daangn-jobs-search scripts/daangn_jobs.py -- detail "https://www.daangn.com/kr/jobs/.../"

지역 필터 Copy Chapter

지역명은 당근 region API로 내부 id를 해석한 뒤 in=<지역명>- 형태로 검색 URL에 넣습니다.

합정동 → 서울특별시 마포구 합정동, id=231 → in=합정동-231

출력 해석 Copy Chapter

검색 결과는 title, company, region, address, salary, salaryType, workDays, workTimeStart, workTimeEnd, closed, url을 우선 확인합니다. 상세 조회는 가능하면 jobPost 원문을 사용하고, 공개 _data가 빈 응답이면 HTML title/meta/JSON-LD를 근거로 정리합니다.

제한사항 Copy Chapter

• 공개 Remix _data route 이름이나 JSON shape가 바뀌면 실패할 수 있습니다.
• 마감·삭제·비공개 전환된 공고는 상세 조회가 실패할 수 있습니다.
• 지원, 채팅, 문의, 개인정보 제출 자동화는 범위 밖입니다.

File: docs/features/daangn-realty-search.md Copy Chapter

당근부동산 검색 가이드 (`daangn-realty-search`)

당근부동산 공개 웹 데이터 표면을 사용해 지역 기반 부동산 매물 후보를 검색하고, 상세 페이지의 공개 메타를 읽기 전용으로 확인하는 스킬입니다.

사용 시나리오 Copy Chapter

• "당근부동산 합정동 월세 매물 찾아봐"
• "마포구 전세 후보 당근에서 봐줘"
• "이 당근부동산 URL 상세 요약해줘"

구현 표면 Copy Chapter

브라우저 자동화, 로그인, 채팅, 문의, 예약, 계약 자동화를 사용하지 않습니다.

1. 지역 해석: https://www.daangn.com/kr/api/v1/regions/keyword?keyword=<지역명>
2. 검색: https://realty.daangn.com/map/{name1}/{name2}/{name3}의 SSR window.RELAY_STORE
3. 상세: https://realty.daangn.com/articles/의 application/ld+json 및 <title>

구버전 https://www.daangn.com/kr/realty/?_data=routes/kr.realty._index 표면은 2026-06 기준 HTTP 204 빈 응답으로 폐기되어 사용하지 않습니다.

로컬 실행 Copy Chapter

npx -y @nomadamas/k-skill@0 exec daangn-realty-search scripts/daangn_realty.py -- search --region "합정동" --limit 5
npx -y @nomadamas/k-skill@0 exec daangn-realty-search scripts/daangn_realty.py -- search --region "합정동" --sales-type "STORE,OFFICETEL" --trade-type "MONTH"
npx -y @nomadamas/k-skill@0 exec daangn-realty-search scripts/daangn_realty.py -- detail "https://realty.daangn.com/articles/..."

지역 필터 Copy Chapter

지역명은 당근 region API로 name1/name2/name3를 해석한 뒤 지도 URL 경로에 넣습니다.

합정동 → 서울특별시 마포구 합정동 → /map/서울특별시/마포구/합정동

출력 해석 Copy Chapter

검색 결과는 salesType, area_sqm, area_pyeong, trades, url, 상세 보강 시 title, address, floor_label을 우선 확인합니다. 부동산 판단에는 실시간 상태, 보증금/월세, 관리비, 면적, 중개/직거래 여부가 중요하므로 원본 URL을 함께 제시합니다.

제한사항 Copy Chapter

• 당근부동산 목록 JSON과 realty.daangn.com 상세 HTML 구조 변경에 영향을 받습니다.
• 문의, 방문 예약, 계약, 결제, 채팅은 실행하지 않습니다.
• 공고 내용은 실시간 상태와 달라질 수 있어 최종 판단 전 원문 확인이 필요합니다.