# Korea Air Quality

> 대한민국 대기질(미세먼지, 초미세먼지, 오존, 통합대기) 조회·브리핑·알림을 위한 OpenClaw 스킬. 사용자가 서울/성동구/분당 같은 한국 지역의 공기질을 묻거나, 오늘/지금 대기질 요약, 현재 위치 기반 조회, 기본 지역 저장, 나쁨 이상 알림, 매일 아침 대기질 브리핑, 여러 지역 비교를 원할 때 사용한다. 특히 한국 지역명 입력을 받아 지역/측정소 후보를 해석하고, 위치 공유 다음 저장된 기본 지역, 그다음 수동 지역 입력 순서로 기본 지역을 결정하는 워크플로에 적합하다.

- Skill: `twbeatles/korea-air-quality` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add twbeatles/korea-air-quality`
- Raw SKILL.md: https://api.skillmd.com/api/skills/twbeatles/korea-air-quality/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: twbeatles (https://skillmd.com/u/twbeatles)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/twbeatles/korea-air-quality

---


# korea-air-quality

대한민국 지역의 대기질을 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-default`), 좌표 저장(`save-location`), 기본 설정 삭제(`clear-default`)를 모두 지원한다.

### 4. 알림 / 감시

다음 요청을 처리한다.

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

현재 버전은 `alert-add`, `alert-list`, `alert-remove`, `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 및 한국환경공단 에어코리아(`ArpltnInforInqireSvc`, ver 1.3) 기반으로 한국 지역 대기질 조회가 가능하며, 동/구/시 단위 4단계 계층형 측정소 매칭, 전국 17개 시도 거점 지원, 기본 지역/좌표 저장, 여러 지역 비교, 알림 점검(`alert-check`), 중복 알림 방지, 오존/통합대기(KHAI) 지표 등급화, 날씨 결합 아침 브리핑, 환경 자동 감지 OpenClaw cron 초안 생성을 지원한다. `--provider airkorea` 와 `setup-provider` 설정 흐름을 통해 국내 실측 API와 해외 기상 API를 유연하게 전환할 수 있다.