korea-air-quality

대한민국 대기질(미세먼지, 초미세먼지, 오존, 통합대기) 조회·브리핑·알림을 위한 OpenClaw 스킬. 사용자가 서울/성동구/분당 같은 한국 지역의 공기질을 묻거나, 오늘/지금 대기질 요약, 현재 위치 기반 조회, 기본 지역 저장, 나쁨 이상 알림, 매일 아침 대기질 브리핑, 여...

대한민국 지역의 대기질을 OpenClaw에서 자연어로 조회하고, 브리핑/감시 흐름으로 연결한다.

Quick start

우선 references/api-and-product-plan.md 를 읽고 데이터 소스/범위를 확인한다. 그 다음 아래 흐름으로 처리한다.

1. 사용자가 원하는 것이 무엇인지 분류한다.
   • 지금/오늘 대기질 조회
   • 현재 위치 기반 조회
   • 기본 지역 저장/변경
   • 나쁨 이상 알림
   • 아침 브리핑
   • 여러 지역 비교
2. 지역 결정을 시도한다.
   • 1순위: 사용자가 방금 공유한 위치 좌표
   • 2순위: 저장된 기본 지역
   • 3순위: 메시지에 포함된 지역명
3. 지역이 확정되면 측정소/행정구역 후보를 해석한다.
4. 실시간 대기질과 예보를 조합해 짧고 실용적으로 요약한다.
5. 반복 요청이면 alert/cron 흐름으로 바꾼다.

Core capabilities

1. 현재 대기질 조회

다음 같은 요청을 처리한다.

• 지금 우리 동네 미세먼지 어때?
• 오늘 서울 공기질 알려줘
• 성동구 초미세먼지 어때?
• 분당 공기 어때?

반드시 포함한다.

• 기준 지역 또는 측정소
• 측정 시각
• PM10 / PM2.5 / O3 가능 범위
• 등급(좋음/보통/나쁨/매우나쁨)
• 한 줄 행동 가이드

2. 현재 위치 기반 조회

사용자가 위치를 직접 보내거나 좌표가 있으면 가장 우선한다. 좌표가 있으면 가장 가까운 측정소를 찾는 방식으로 해석한다. 좌표가 없으면 저장된 기본 지역을 사용하고, 그것도 없으면 지역명을 다시 물어본다.

3. 기본 지역 저장

다음 요청을 처리한다.

• 내 기본 지역을 성동구로 저장해줘
• 앞으로는 분당 기준으로 알려줘
• 기본 지역 삭제해줘
• 내 현재 위치를 기본 위치로 저장해줘

저장 위치는 data/user-preferences.json 같은 로컬 파일을 우선 고려한다. 사용자별 식별자가 필요하면 채널 사용자 id를 키로 쓴다. 현재 버전은 지역명 저장과 좌표 저장(save-location) 모두 지원한다.

4. 알림 / 감시

다음 요청을 처리한다.

• 초미세먼지 나쁨 이상이면 알려줘
• 서울 오존 나쁘면 알려줘
• 출근 시간에 공기 안 좋으면 알려줘

현재 버전은 alert-add, alert-list, alert-check 명령으로 로컬 규칙 저장/점검이 가능하다. alert-check 는 기본적으로 중복 hit를 다시 알리지 않도록 상태를 저장한다. 반복 감시는 watch 성격의 로컬 규칙 + OpenClaw cron 조합으로 설계한다.

5. 아침 브리핑

다음 요청을 처리한다.

• 매일 아침 7시에 오늘 공기질 알려줘
• 날씨랑 같이 대기질 브리핑해줘

현재 버전은 morning-brief 명령으로 날씨 + 대기질 결합 브리핑을 생성할 수 있다. 브리핑은 모바일에서 읽기 좋게 짧게 쓰고, 아래 순서를 권장한다.

• 지역
• 현재/예상 등급
• 핵심 수치
• 외출/환기/마스크 한 줄 팁

Location resolution policy

항상 아래 우선순위를 사용한다.

1. 사용자가 방금 보낸 위치 좌표
2. 저장된 기본 지역
3. 메시지에 적힌 지역명
4. 아무 정보가 없으면 지역을 짧게 재질문

우리 동네, 내 위치, 지금 있는 곳 같은 표현은 좌표 또는 기본 지역 해석을 먼저 시도한다.

Output style

출력은 한국어로, 짧고 실용적으로 쓴다.

권장 형식:

• 성동구 인근 측정소 기준
• 초미세먼지: 38㎍/㎥ · 나쁨
• 미세먼지: 54㎍/㎥ · 보통
• 한줄 요약: 오늘은 초미세먼지가 다소 높은 편이라 장시간 야외활동은 줄이는 게 좋겠어.
• 행동 팁: 창문 환기는 짧게, 외출 시 마스크 권장

여러 지역 비교일 때는 지역별 1~2줄 요약으로 정리한다.

Resources

references/api-and-product-plan.md

데이터 소스 후보, 권장 MVP 범위, 위치 반영 전략, 알림 설계를 정리한 문서다. 이 스킬을 확장하거나 실제 API를 연결할 때 먼저 읽는다.

scripts/air_quality.py

실행 가능한 CLI다. 현재 버전은 Open-Meteo 기반으로 한국 지역 대기질 조회가 가능하며, 지역명 해석, 기본 지역/기본 좌표 저장, 여러 지역 비교, 알림 점검, 중복 알림 방지, 아침 브리핑, OpenClaw cron 초안 생성을 지원한다. --provider airkorea 레이어와 setup-provider 설정 흐름도 준비돼 있어 국내 API 연결 시 이 파일을 중심으로 확장한다.