Skill

Pass

Audit score 90

k-schoollunch-menu

nomadamas/k-skill

Look up Korean school lunch menus by education office and school name via NEIS API.

What is k-schoollunch-menu?

Queries Korean school meal menus (급식 식단) from the NEIS education portal by natural-language education office and school name. Use when users ask for school lunch information for a specific school and date.

Search schools by education office name and school name in natural language
Fetch meal menus for a specific school and date from NEIS
Handle ambiguous education office names by showing candidates
Disambiguate multiple matching schools by address
Format meal data with line breaks and nutritional info when available

How to install k-schoollunch-menu

npx skills add https://github.com/nomadamas/k-skill --skill k-schoollunch-menu

Prerequisites

Internet connection
curl available in environment
Access to k-skill-proxy with KEDU_INFO_KEY configured (default hosted or self-hosted)

Claude Code

Cursor

Windsurf

Cline

How to use k-schoollunch-menu

1.Collect from user: education office name (자연어), school name, and meal date (defaults to today in Korea time)
2.Call /v1/neis/school-search with education office and school name to find the school
3.If multiple schools match, show user the school names and addresses to select one
4.Extract ATPT_OFCDC_SC_CODE and SD_SCHUL_CODE from the selected school result
5.Call /v1/neis/school-meal with the school codes and date (YYYYMMDD format)
6.Format and summarize the meal data for the user, converting <br/> to line breaks

Use cases

Good for

User asks: '서울특별시교육청 미래초등학교 오늘 급식 뭐야?' (Seoul school lunch today)
User requests: '○○초 급식 식단 알려줘' (Show school lunch menu)
User inquires: '이번 주 화요일 중학교 급식 메뉴' (This week Tuesday middle school menu)
User asks for lunch without specifying school: agent collects education office, school name, and date

Who it's for

Students checking school lunch menus
Parents planning meals for their children
Anyone needing Korean school meal information

k-schoollunch-menu FAQ

Do I need to provide an API key?

No. The KEDU_INFO_KEY is stored only on the k-skill-proxy server. Users only need internet access to the proxy.

What if multiple schools have the same name?

The agent will show you the school names and addresses (from ORG_RDNMA) and ask you to select the correct one.

What if the education office name is ambiguous?

The proxy returns candidate_codes. The agent will show you the options and ask for a more specific education office name (e.g., 경상북도교육청 vs 경상남도교육청).

What happens if there's no meal data for that date?

NEIS may return empty results for holidays, breaks, or dates without provided meal data. The agent will inform you that meal data is unavailable for that date.

Can I use a self-hosted proxy?

Yes. Set KSKILL_PROXY_BASE_URL environment variable to your proxy URL. If not set, it defaults to https://k-skill-proxy.nomadamas.org.

Full instructions (SKILL.md)

Source of truth, from nomadamas/k-skill.

name: k-schoollunch-menu description: Use when the user asks for Korean school meal menus (급식 식단) by natural-language education office and school name, via k-skill-proxy NEIS school-search and school-meal routes. license: MIT metadata: category: utility locale: ko-KR phase: v1

Korean School Lunch Menu (NEIS)

What this skill does

나이스(NEIS) 교육정보 개방 포털의 학교기본정보·급식식단정보를 k-skill-proxy가 중계하는 HTTP API로 조회한다.

사용자는 시도교육청 이름(자연어)과 학교 이름, 날짜만 말하면 된다.
에이전트는 먼저 /v1/neis/school-search로 학교를 찾고, 응답의 SD_SCHUL_CODE·ATPT_OFCDC_SC_CODE로 /v1/neis/school-meal을 호출한다.
인증키(KEDU_INFO_KEY)는 프록시 서버에만 두고, 클라이언트는 키 없이 프록시 URL만 호출한다.

When to use

"서울특별시교육청 미래초등학교 오늘 급식 뭐야?"
"○○초 급식 식단 알려줘"
"이번 주 화요일 중학교 급식 메뉴"
"급식 메뉴 조회해줘" (교육청·학교·날짜 확인 후 진행)

Prerequisites

인터넷 연결
curl 사용 가능 환경
k-skill-proxy에 KEDU_INFO_KEY가 설정된 배포(기본 hosted 또는 self-host)에 접근 가능할 것

Credential requirements

사용자 측 필수 시크릿 없음.
KSKILL_PROXY_BASE_URL — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted https://k-skill-proxy.nomadamas.org 를 사용한다.
KEDU_INFO_KEY 는 프록시 운영 서버 환경에만 둔다.

Proxy base URL

에이전트는 아래처럼 base 를 정한다.

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
BASE="${BASE%/}"

Workflow

1) Collect inputs (do not guess)

다음이 없으면 사용자에게 짧게 묻는다.

교육청 — 자연어 허용 (예: 서울특별시교육청, 서울, 경기도교육청).
학교명 — 자연어 (예: 미래초등학교, ○○중학교).
급식일 — YYYYMMDD 또는 사용자가 말한 날짜를 한국 시간 기준으로 YYYYMMDD로 정한다. 생략 시 오늘(한국 시간).

교육청 표현이 애매해 ambiguous_education_office가 나오면, 응답의 candidate_codes를 보여 주고 더 구체적인 이름(예: 경상북도교육청 vs 경상남도교육청)을 받는다.

2) Search school (`/v1/neis/school-search`)

curl -fsS --get "${BASE}/v1/neis/school-search" \
  --data-urlencode "educationOffice=${EDU_OFFICE}" \
  --data-urlencode "schoolName=${SCHOOL_NAME}"

EDU_OFFICE, SCHOOL_NAME은 사용자 입력을 그대로 넣어도 된다. 프록시가 교육청명을 코드로 해석한다.
응답의 resolved_education_office.atpt_ofcdc_sc_code로 실제 매칭된 시도교육청 코드를 확인할 수 있다.

3) Disambiguate when multiple schools match

schoolInfo 본문에서 row가 여러 개면 사용자에게 **학교명·주소(ORG_RDNMA 등)**를 보여 주고 하나를 고르게 한다.

한 건뿐이면 그 row의 ATPT_OFCDC_SC_CODE, SD_SCHUL_CODE를 다음 단계에 쓴다.

4) Fetch meal (`/v1/neis/school-meal`)

curl -fsS --get "${BASE}/v1/neis/school-meal" \
  --data-urlencode "educationOfficeCode=${ATPT}" \
  --data-urlencode "schoolCode=${SD}" \
  --data-urlencode "mealDate=${YYYYMMDD}"

ATPT / SD는 3단계에서 확정한 코드.
조식·중식·석식만 보고 싶으면 mealKindCode=1|2|3 (선택).

5) Summarize for the user

mealServiceDietInfo 안의 row를 기준으로 요약한다.
메뉴 문자열(DDISH_NM 등)의 <br/>는 줄바꿈으로 바꿔 읽기 쉽게 한다.
칼로리·영양 정보 필드가 있으면 한두 줄로 덧붙인다.
NEIS가 빈 결과를 주면 "해당 일자 급식 데이터 없음" 가능성을 안내한다.

Upstream reference

급식·학교기본정보 데이터: 나이스 교육정보 개방 포털

Done when

교육청·학교·날짜를 확인했다.
학교 검색으로 단일 학교를 확정했다(또는 사용자가 선택했다).
급식 API 호출에 성공했고, 메뉴를 사용자 친화적으로 정리했다.

Failure modes

프록시에 KEDU_INFO_KEY 미설정 → 503 / upstream_not_configured
교육청 이름이 여러 시도에 걸침 → 400 / ambiguous_education_office
학교명이 여러 건 — 사용자 선택 없이 임의로 고르지 말 것
공휴일·방학·미제공 일자로 빈 급식
NEIS API 일시 장애·호출 제한

Notes

학교 코드를 사용자에게 외우게 하지 않는다. 항상 school-search → school-meal 순서를 따른다.
Raw JSON을 그대로 붙여 넣지 말고 요약 위주로 답한다.
자세한 엔드포인트·필드는 docs/features/k-schoollunch-menu.md와 docs/features/k-skill-proxy.md를 참고한다.