instruction.md
# NHIS Care And Checkup Search
## What this skill does
국민건강보험공단 장기요양기관 검색서비스(data.go.kr `15059029`)와 검진기관 찾기 조회(data.go.kr `15154419`)를 `k-skill-proxy` 경유로 호출해 공개 기관 후보를 조회한다.
> 이 스킬은 국민건강보험공단의 공개 기관 정보를 정리하는 **조회 도구**이며 의료 판단, 장기요양 등급 판정 또는 특정 기관의 적합성·서비스 품질을 보증하지 않는다. 실제 이용 조건과 예약 가능 여부는 NHIS 또는 해당 기관에 직접 확인한다.
## When to use
- "서울 강남 장기요양기관 찾아줘"
- "요양원 후보와 주소/전화번호 확인해줘"
- "서울 강남 건강검진기관 찾아줘"
- "주말 검진 가능한 검진기관 찾아줘"
## When not to use
- 의료 판단, 장기요양 등급 판정, 특정 기관 추천 보증
- 예약·신청·민감 의료정보 조회 자동화
## Prerequisites
- 인터넷 연결
- hosted/self-host `k-skill-proxy`의 `/v1/nhis/long-term-care`, `/v1/nhis/checkup/*` route 접근 가능
## Credential requirements
- 사용자 측 필수 시크릿 없음.
- `KSKILL_PROXY_BASE_URL` — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted `https://k-skill-proxy.nomadamas.org` 를 사용한다.
- `DATA_GO_KR_API_KEY` 는 프록시 운영 서버 환경에만 둔다. 공공데이터포털에서 필요한 서비스의 활용신청이 승인돼 있어야 한다.
키 발급:
- 장기요양기관 검색 서비스: <https://www.data.go.kr/data/15059029/openapi.do>
- 건강검진기관 검색 서비스: <https://www.data.go.kr/data/15154419/openapi.do>
- 공공데이터포털 이용 가이드: <https://www.data.go.kr/ugs/selectPublicDataUseGuideView.do>
## Inputs
장기요양기관 route:
- `q`, `query`, `name`, 또는 `adminNm`: 기관명 검색어
- `sido` 또는 `siDoCd`: 시도 코드
- `sigungu` 또는 `siGunGuCd`: 시군구 코드
- `service_kind` 또는 `serviceKind`: 급여/서비스 종류 코드
- `page` 또는 `pageNo`: 기본 1
- `limit` 또는 `numOfRows`: 기본 10, 최대 100
건강검진기관 route:
- route operation: `list`, `by-region`, `by-checkup-type`, `holiday`
- `q`, `query`, `name`, 또는 `hmcNm`: 검진기관명 검색어
- `sido` 또는 `siDoCd`: 시도 코드
- `sigungu` 또는 `siGunGuCd`: 시군구 코드
- `hchk_type`, `checkup_type`, 또는 `hchkTypeCd`: 검진 유형 코드
- `page` 또는 `pageNo`: 기본 1
- `limit` 또는 `numOfRows`: 기본 10, 최대 100
## Workflow
### 1. Decide the surface
장기요양기관이면 `/v1/nhis/long-term-care`를 사용한다. 건강검진기관이면 검색 목적에 맞춰 `/v1/nhis/checkup/list`, `/v1/nhis/checkup/by-region`, `/v1/nhis/checkup/by-checkup-type`, `/v1/nhis/checkup/holiday` 중 하나를 사용한다.
### 2. Query long-term care institutions through the proxy
```bash
BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "$BASE/v1/nhis/long-term-care" \
--data-urlencode "q=강남" \
--data-urlencode "sido=11" \
--data-urlencode "limit=10"
```
### 3. Query health checkup institutions through the proxy
```bash
BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "$BASE/v1/nhis/checkup/by-region" \
--data-urlencode "q=검진" \
--data-urlencode "sido=11" \
--data-urlencode "limit=10"
```
### 4. Summarize source fields
응답 XML의 `item` 필드에서 기관명, 주소, 전화번호, 급여종류, 검진유형, 운영일처럼 upstream이 제공한 공개 항목만 요약한다. 사용자가 실제 이용·입소·검진 예약을 하려면 NHIS 또는 기관에 직접 확인하라고 안내한다.
## Failure modes
- `400 bad_request`: 검색어/지역/서비스 종류 중 하나도 없거나 코드/페이지 값이 잘못됨.
- `503 upstream_not_configured`: 프록시 서버에 `DATA_GO_KR_API_KEY` 가 없음.
- `502 upstream_forbidden`: data.go.kr gateway가 키를 거부함.
- 빈 결과: 지역 코드나 기관명 표기를 완화해서 재검색한다.
- 특정 서비스만 실패: 같은 `DATA_GO_KR_API_KEY`라도 data.go.kr 서비스별 활용신청이 별도라서 `15059029` 또는 `15154419` 승인 상태를 확인한다.
## Done when
- 장기요양기관 조회는 `k-skill-proxy` route로 수행했고 사용자에게 API key를 요구하지 않았다.
- 건강검진기관 조회는 `k-skill-proxy` route로 수행했고 사용자에게 API key를 요구하지 않았다.
- 결과에는 기관명, 위치, 연락처, 원천 서비스와 조회 조건을 함께 적었다.
## Maintainer review notes
키 없이 가능한 검증:
- `./scripts/validate-skills.sh`
- `node --test packages/k-skill-proxy/test/server.test.js`
- `curl -i --get "$KSKILL_PROXY_BASE_URL/v1/nhis/long-term-care" --data-urlencode "q=강남"` (키 미설정이면 503 확인)
- `curl -i --get "$KSKILL_PROXY_BASE_URL/v1/nhis/checkup/by-region" --data-urlencode "q=검진" --data-urlencode "sido=11"` (키 미설정이면 503 확인)
Live smoke는 hosted/self-host proxy에 `DATA_GO_KR_API_KEY`가 설정되고 `15059029` 또는 `15154419` 활용신청이 승인된 뒤 수행한다.
## Safety notes
- 조회 전용 스킬이다.
- 의료 판단, 장기요양 등급 판정, 예약/신청 자동화는 하지 않는다.
- 인증키는 프록시 서버에서만 다루며 repo/GitHub Actions/public docs에 저장하지 않는다.
skill.json
{
"name": "nhis-care-checkup-search",
"description": "국민건강보험공단 장기요양기관·건강검진기관을 조회하고, 돌쇠에서는 공식 연락·예약 가능 표면까지 이어간다.",
"profiles": [
"proxy",
"lookup"
],
"frontmatter": "name: nhis-care-checkup-search\ndescription: 국민건강보험공단 장기요양기관·건강검진기관을 조회하고, 돌쇠에서는 공식 연락·예약 가능 표면까지 이어간다.\nlicense: MIT\nmetadata:\n category: healthcare\n locale: ko-KR\n phase: v1"
}
SKILL.md
---
name: nhis-care-checkup-search
description: 국민건강보험공단 장기요양기관·건강검진기관을 조회하고, 돌쇠에서는 공식 연락·예약 가능 표면까지 이어간다.
license: MIT
metadata:
category: healthcare
locale: ko-KR
phase: v1
---
# nhis-care-checkup-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 nhis-care-checkup-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 nhis-care-checkup-search
```
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/nhis-care-checkup-search/instruction.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.