skills/nomadamas__k-skill
1
0
Fork 0
mirror of https://github.com/NomaDamas/k-skill.git synced 2026-09-14 16:37:18 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
fix/release-python-workflow
nomadamas__k-skill/korea-weather/SKILL.md
T
Jeffrey (Dongkyu) Kim dc9a765e2a Feature/#205 (#210) 
* Align proxy defaults for hosted Korean routes

Constraint: Issue #205 requires unset or empty KSKILL_PROXY_BASE_URL to use the hosted proxy consistently while preserving explicit proxy overrides and server-side upstream keys.\nRejected: Keeping Seoul subway and Korea weather as self-host-only routes | it preserves the documented inconsistency and blocks zero-config usage.\nConfidence: high\nScope-risk: narrow\nDirective: Keep client docs pointing to hosted proxy defaults unless a route is intentionally removed from hosted service.\nTested: node --test scripts/skill-docs.test.js; npm run ci; hosted smoke curls for /v1/seoul-subway/arrival and /v1/korea-weather/forecast; architect verification approved.\nNot-tested: Private self-host proxy deployment.

* Preserve hosted proxy fallback in setup guidance

Make self-host proxy examples inactive by default so client setup no longer blocks the hosted proxy resolver contract for Seoul subway and Korea weather skills.

Constraint: PR #210 review required unset and empty KSKILL_PROXY_BASE_URL to fall back to https://k-skill-proxy.nomadamas.org while preserving explicit self-host overrides.\nRejected: Keep active https://your-proxy.example.com placeholder | It creates a non-empty override and prevents hosted fallback for users copying the default secrets file.\nConfidence: high\nScope-risk: narrow\nDirective: Keep upstream API keys documented as proxy-operator/server-side only; do not reintroduce active client-side proxy placeholders for hosted-default flows.\nTested: node --test scripts/skill-docs.test.js; npm run ci; hosted smoke checks for /v1/seoul-subway/arrival?stationName=강남 and /v1/korea-weather/forecast?lat=37.5665&lon=126.9780; resolver smoke for unset, empty, and custom KSKILL_PROXY_BASE_URL; git diff --check; Ralph architect verification CLEAR.\nNot-tested: none

* Clarify proxy guide override boundary

Document the hosted-client default in the proxy guide while keeping the self-host placeholder as an explicitly scoped override, so users do not mistake it for required setup.

Constraint: Issue #205 review round 2 left a WATCH concern on docs/features/k-skill-proxy.md client env-var wording.

Rejected: Leave the proxy guide unchanged | It preserved ambiguity between hosted-client defaults and self-host/operator overrides.

Rejected: Sentence-exact regression assertions | They were too brittle after code review; semantic assertions preserve wording flexibility while locking the policy.

Confidence: high

Scope-risk: narrow

Directive: Keep KSKILL_PROXY_BASE_URL examples inactive or clearly scoped unless documenting a self-host/alternate-proxy override.

Tested: node --test scripts/skill-docs.test.js; npm run ci; resolver smoke for unset empty and custom KSKILL_PROXY_BASE_URL; hosted Seoul subway and Korea weather smokes; git diff --check; code-reviewer APPROVE; architect CLEAR

Not-tested: none

* Keep proxy guide examples on the hosted-default path

Constraint: PR #210 issue #205 follow-up requires KSKILL_PROXY_BASE_URL unset/empty to resolve to hosted while preserving explicit self-host overrides.\nRejected: Labeling the existing 127.0.0.1 examples as operator-only | it would leave the general usage section less aligned with the hosted-client default.\nConfidence: high\nScope-risk: narrow\nDirective: Keep Seoul subway and Korea weather user-facing examples on the resolver pattern unless the section is explicitly scoped to local operator smoke tests.\nTested: node --test scripts/skill-docs.test.js; npm run ci; resolver smoke for unset empty custom KSKILL_PROXY_BASE_URL; hosted Seoul subway and Korea weather smoke; architect verification CLEAR.\nNot-tested: None.
2026-05-06 16:56:40 +09:00

3.5 KiB
Raw Permalink Blame History

name, description, license, metadata
name description license metadata
korea-weather 한국 날씨를 기상청 단기예보 조회서비스와 프록시 경유로 조회해 요약한다. MIT
category locale phase
weather ko-KR v1

Korea Weather

What this skill does

기상청 단기예보 조회서비스를 k-skill-proxy 경유로 조회해서 한국 날씨를 요약한다. 사용자는 개인 OpenAPI key를 직접 발급할 필요가 없고, proxy 서버에만 KMA_OPEN_API_KEY 를 둔다.

When to use

  • "서울 시청 근처 지금 날씨 어때?"
  • "부산 날씨 알려줘"
  • "위도/경도 기준으로 한국 단기예보 보고 싶어"

Prerequisites

  • optional: jq
  • optional: KSKILL_PROXY_BASE_URL (self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted https://k-skill-proxy.nomadamas.org 를 사용한다.)

Required environment variables

  • 없음. KSKILL_PROXY_BASE_URL 은 선택 사항이며, 비우면 기본 hosted https://k-skill-proxy.nomadamas.org 를 사용한다.

사용자가 공공데이터포털 기상청 API key를 직접 다룰 필요는 없다. /v1/korea-weather/forecast route는 기본 hosted proxy에서 호출하고, upstream KMA_OPEN_API_KEY 는 proxy 서버에서만 관리한다. 별도 proxy를 쓰는 경우에만 KSKILL_PROXY_BASE_URL 을 설정한다.

Inputs

  • 격자 좌표: nx, ny
  • 또는 위도/경도: lat, lon
  • 선택 사항: baseDate, baseTime

baseDate / baseTime 을 생략하면 proxy 가 KST 기준 최신 단기예보 발표 시각을 자동으로 고른다.

Workflow

1. Resolve the proxy base URL

KSKILL_PROXY_BASE_URL 이 있으면 그 값을 사용하고, 없거나 비어 있으면 기본 hosted proxy https://k-skill-proxy.nomadamas.org 를 사용한다.

2. Query the short-term forecast endpoint

격자 좌표가 이미 있으면 그대로 넣고, 위도/경도만 있으면 proxy 에 그대로 넘긴다.

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/korea-weather/forecast" \
  --data-urlencode 'lat=37.5665' \
  --data-urlencode 'lon=126.9780'

격자 좌표 예시:

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/korea-weather/forecast" \
  --data-urlencode 'nx=60' \
  --data-urlencode 'ny=127' \
  --data-urlencode 'baseDate=20260405' \
  --data-urlencode 'baseTime=0500'

3. Summarize the response conservatively

가능하면 아래 항목만 먼저 요약한다.

  • TMP: 기온
  • SKY: 하늘상태
  • PTY: 강수형태
  • POP: 강수확률
  • PCP: 강수량
  • SNO: 적설
  • REH: 습도
  • WSD: 풍속

응답에는 조회 시점과 baseDate / baseTime 도 함께 적는다.

Done when

  • 요청 위치의 단기예보 응답이 정리되어 있다
  • 조회 시점과 예보 발표 시각이 명시되어 있다
  • upstream key가 클라이언트에 노출되지 않았다

Failure modes

  • proxy upstream key 미설정 또는 hosted/self-host route 장애
  • nx / ny 또는 lat / lon 이 불완전한 경우
  • 기상청 quota 초과 또는 upstream 장애
  • 선택한 발표 시각에 아직 예보가 준비되지 않은 경우

Notes

  • 공식 API는 nx / ny 격자를 쓰지만, proxy 는 lat / lon 도 받아 내부에서 격자로 변환한다.
  • 단기예보 category 는 TMP, SKY, PTY, POP, PCP, SNO, REH, WSD 등을 중심으로 본다.
  • proxy 운영/환경변수 설정은 docs/features/k-skill-proxy.md 를 참고한다.
Reference in New Issue View Git Blame Copy Permalink