@nomadamas/k-skill 0.1.0

package/skills/keris-academic-search/instruction.md

@@ -0,0 +1,81 @@
+# KERIS Academic Search
+
+## What this skill does
+
+KERIS가 운영하는 RISS 검색 Open API에서 학위논문, 국내외 학술논문, 단행본, 연구보고서, 학술지 메타데이터를 조회한다. 제목, 저자, 발행처, 연도, RISS 상세 링크, API가 반환한 원문 유무/무료 표시를 요약한다.
+
+조회 전용이다. 기관 로그인, 구독 권한 우회, 복사·대출 신청, 유료 결제, 원문 다운로드는 자동화하지 않는다.
+
+## Official access path
+
+1. 기본 경로: 사용자 본인의 RISS 검색 API 키로 상류(`https://www.riss.kr/openApi`)를 직접 호출한다. 이 스킬은 `k-skill-proxy`를 사용하지 않는다.
+2. 상류 계약: `key`, `version=1.0`, `type`별 XML, `rsnum`, `rowcount(최대 100)`
+3. 공식 문서: RISS API 센터(<https://www.riss.kr/apicenter/apiMain.do>)의 학위논문/국내학술논문/해외학술논문/단행본/연구보고서/학술지 검색 API 정보
+
+### RISS API 키 발급
+
+RISS 검색 Open API 키는 **공익 목적의 비영리 기관/대학에만** 무료로 발급된다(향후 민간 확대 예정). data.go.kr 키와 완전히 별개다.
+
+1. RISS(<https://www.riss.kr>)에 기관 소속으로 회원가입/로그인
+2. RISS API 센터 → **RISS 검색 API** 선택 → 이용신청(<https://riss.kr/openAPI/OpenApiRegisterFinal.do>)
+3. KERIS 담당자 심사·승인 후 인증키(`key` 파라미터) 발급
+4. 발급받은 키를 `KSKILL_RISS_API_KEY`(호환 `RISS_API_KEY`) 환경변수 또는 `~/.config/k-skill/secrets.env`에 설정
+
+공공데이터포털 데이터셋 `15071949`는 RISS 종합목록의 정적 파일/카탈로그 현황 관련 표면이다. 기사·논문 검색 API가 아니므로 검색 fallback으로 사용하지 않는다. 데이터셋 `3046254`는 관련 카탈로그 항목이지만 실제 검색 계약은 RISS API 센터와 `/openApi`를 기준으로 한다.
+
+## Commands
+
+```bash
+python3 scripts/keris_academic.py search --keyword '인공지능 교육'
+python3 scripts/keris_academic.py search --title '대학도서관' --author '김연구' --resource-type T
+python3 scripts/keris_academic.py search --keyword '한국어 교육' --resource-type D --page 2 --page-size 20 --json
+```
+
+검색 필드는 `keyword`, `title`, `author`, `subject`, `publisher`이며 하나 이상 필요하다. `page`는 1 이상, `pageSize`는 1~100이다. RISS의 `rsnum`은 `(page-1)*pageSize+1`로 계산한다. 실제 호출에는 사용자 RISS 키가 필요하다.
+
+여러 upstream type을 합치는 `ALL`과 `A`는 첫 페이지에서 type별 결과를 round-robin으로 합친다. 정확한 후속 페이지가 필요하면 `T`, `D`, `B` 또는 실제 단일 자료유형 검색을 사용한다. 결합 검색은 upstream을 type 수만큼 호출한다.
+
+사용자 resource type alias:
+
+- `ALL`: 공식 `T/A/O/U/F/S`를 모아 최대 `pageSize`건 반환
+- `T`: 학위논문, 공식 `T`
+- `A`: 국내+해외 학술논문, 공식 `A/O`
+- `D`: 국내 학술논문(domestic article) 호환 alias, 공식 `A`
+- `B`: 단행본(book) 호환 alias, 공식 `U`
+
+응답 item의 `resource_type`에는 alias가 아니라 실제 RISS 코드를 보존한다.
+
+## Credentials
+
+```bash
+python3 scripts/keris_academic.py search --keyword '교육 데이터' --resource-type ALL --dry-run
+```
+
+- RISS 키: `KSKILL_RISS_API_KEY`, 없으면 compatibility `RISS_API_KEY`, 이후 `~/.config/k-skill/secrets.env`
+- `DATA_GO_KR_API_KEY`는 RISS 검색에 사용하지 않는다
+- `--dry-run`은 키를 발급받기 전에도 호출 URL을 확인할 수 있으며 키를 `REDACTED`로 표시한다
+- 키가 없으면 실행을 중단하고 RISS API 센터 발급 안내를 출력한다
+
+## Output and fallback order
+
+1. 검색 성공 결과를 제목, 저자, 발행처/학술지, 연도, 링크, 원문 상태로 요약한다.
+2. 키가 없으면 RISS API 센터에서 검색 API 키를 발급받도록 안내한다.
+3. RISS 장애/쿼터/파싱 오류를 웹 scraping이나 data.go.kr `15071949`로 대체하지 않는다.
+4. 빈 결과는 성공(`items: []`)으로 유지하고 검색어/자료유형을 조정한다.
+
+## Failure modes
+
+- missing key: 실행 중단 + RISS API 센터 키 발급 안내(exit 1)
+- invalid input: 입력 검증 오류 메시지(exit 1)
+- RISS 인증 오류 또는 HTTP 401/403: 키/기관 권한 확인 안내(exit 1)
+- 호출량/쿼터 초과 또는 HTTP 429: 쿼터 초과 안내(exit 1)
+- upstream network/HTTP failure: 네트워크/HTTP 오류 메시지(exit 1)
+- empty/malformed/unexpected XML: XML 파싱 오류 메시지(exit 1)
+- empty result: 성공 응답과 빈 `items`
+- login/licensed full text: 상세 링크만 제공하고 자동 다운로드하지 않음
+
+## Done when
+
+- 검색 조건과 실제 RISS 자료유형이 명시됐다.
+- 결과 또는 typed failure를 제공했다.
+- 원문 유무 표시는 API 값으로만 설명했고 접근권한을 보장하거나 다운로드를 자동화하지 않았다.

package/skills/keris-academic-search/scripts/keris_academic.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""Read-only KERIS/RISS academic metadata search helper using stdlib only.
+
+RISS 검색 Open API는 기관/대학 전용 인증키를 요구하므로 k-skill-proxy를 거치지
+않고, 사용자가 직접 발급받은 RISS 키로 상류(``https://www.riss.kr/openApi``)를
+호출한다.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+from typing import Any, Dict, List, Optional
+
+DEFAULT_SECRETS_PATH = pathlib.Path("~/.config/k-skill/secrets.env").expanduser()
+RISS_OPEN_API_URL = "https://www.riss.kr/openApi"
+RESOURCE_TYPE_MAP = {"ALL": ["T", "A", "O", "U", "F", "S"], "T": ["T"], "A": ["A", "O"], "D": ["A"], "B": ["U"]}
+MISSING_KEY_MSG = (
+    "RISS API 키가 없습니다. RISS API 센터(https://www.riss.kr/apicenter/apiMain.do)에서 "
+    "검색 API 키를 발급받아 KSKILL_RISS_API_KEY(호환 RISS_API_KEY) 환경변수 또는 "
+    "~/.config/k-skill/secrets.env 에 설정하세요. RISS 키는 비영리 기관/대학에 발급됩니다."
+)
+
+
+class HelperError(RuntimeError):
+    pass
+
+
+def load_secrets(path: pathlib.Path) -> Dict[str, str]:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return {}
+    values = {}
+    for raw in lines:
+        line = raw.strip()
+        if line and not line.startswith("#") and "=" in line:
+            key, value = line.split("=", 1)
+            values[key.strip()] = value.strip().strip('"').strip("'")
+    return values
+
+
+def resolve_api_key(args: argparse.Namespace) -> Optional[str]:
+    for name in ("KSKILL_RISS_API_KEY", "RISS_API_KEY"):
+        value = os.environ.get(name)
+        if value and value.strip():
+            return value.strip()
+    secrets = load_secrets(pathlib.Path(args.secrets_path).expanduser())
+    value = secrets.get("KSKILL_RISS_API_KEY") or secrets.get("RISS_API_KEY")
+    return value.strip() if value and value.strip() else None
+
+
+def build_query(args: argparse.Namespace) -> Dict[str, Any]:
+    query = {}
+    for field in ("keyword", "title", "author", "subject", "publisher"):
+        value = getattr(args, field)
+        if value and value.strip():
+            text = value.strip()
+            if len(text) > 200 or any(ord(char) < 32 or ord(char) == 127 for char in text):
+                raise HelperError(f"{field} 값은 1~200자의 일반 텍스트여야 합니다.")
+            query[field] = text
+    if not query:
+        raise HelperError("--keyword, --title, --author, --subject, --publisher 중 하나 이상을 입력하세요.")
+    if not 1 <= args.page <= 100000:
+        raise HelperError("page 값은 1~100000 범위여야 합니다.")
+    if not 1 <= args.page_size <= 100:
+        raise HelperError("pageSize 값은 1~100 범위여야 합니다.")
+    if len(RESOURCE_TYPE_MAP[args.resource_type]) > 1 and args.page > 1:
+        raise HelperError("Combined resourceType searches support page 1 only; later pages require a single resource type.")
+    query.update({"resourceType": args.resource_type, "page": args.page, "pageSize": args.page_size})
+    return query
+
+
+def build_riss_urls(query: Dict[str, Any], api_key: str) -> List[str]:
+    rsnum = ((query["page"] - 1) * query["pageSize"]) + 1
+    urls = []
+    for upstream_type in RESOURCE_TYPE_MAP[query["resourceType"]]:
+        params = {key: value for key, value in query.items() if key not in {"resourceType", "page", "pageSize"}}
+        params.update({"key": api_key, "version": "1.0", "type": upstream_type, "rsnum": rsnum, "rowcount": query["pageSize"]})
+        urls.append(f"{RISS_OPEN_API_URL}?{urllib.parse.urlencode(params)}")
+    return urls
+
+
+def parse_riss_xml(raw: bytes) -> Dict[str, Any]:
+    try:
+        root = ET.fromstring(raw)
+    except ET.ParseError as error:
+        raise HelperError("RISS API 응답 XML이 올바르지 않습니다.") from error
+    if root.tag != "record":
+        raise HelperError("RISS API 응답 envelope가 올바르지 않습니다.")
+    error_text = root.findtext("./head/Error")
+    if error_text is None or not error_text.strip():
+        raise HelperError("RISS API 응답에 상태 메타데이터가 없습니다.")
+    code = error_text.strip()
+    message = (root.findtext("./head/ErrorMessage") or "Unknown RISS error").strip()
+    if code not in {"0", "000"}:
+        raise HelperError(f"RISS API 오류 {code}: {message}")
+    items = []
+    for metadata in root.findall("./metadata"):
+        values: Dict[str, List[str]] = {}
+        for child in metadata:
+            value = "".join(child.itertext()).strip()
+            if value:
+                values.setdefault(child.tag.removeprefix("riss.").lower(), []).append(value)
+        first = lambda key: values.get(key, [None])[0]
+        image, charge = (first("image") or "").upper(), first("charge")
+        available = True if image == "Y" else False if image == "N" else None
+        access = "free" if available and charge == "1" else "paid_or_restricted" if available and charge == "0" else "available" if available else "none" if available is False else "unknown"
+        author = first("author") or ""
+        authors = [part.strip() for part in author.replace(";", ",").split(",") if part.strip()] or ([author] if author else [])
+        items.append({"resource_type": first("type"), "title": first("title"), "authors": authors, "publisher": first("publisher"), "year": first("pubdate"), "publication": first("stitle"), "material_type": first("mtype"), "link": first("url"), "full_text_available": available, "full_text_access": access, "holdings": values.get("holdings", [])})
+    total_text = root.findtext("./head/totalcount")
+    try:
+        total_count = int(total_text) if total_text is not None else len(items)
+    except ValueError as error:
+        raise HelperError("RISS API 응답 totalcount가 올바른 정수가 아닙니다.") from error
+    if total_count < 0:
+        raise HelperError("RISS API 응답 totalcount가 음수입니다.")
+    return {"total_count": total_count, "items": items}
+
+
+def http_get_riss_xml(urls: List[str], timeout: int, page: int, page_size: int) -> Dict[str, Any]:
+    results = []
+    for url in urls:
+        request = urllib.request.Request(url, headers={"accept": "application/xml", "user-agent": "k-skill/keris-academic-search"})
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                results.append(parse_riss_xml(response.read()))
+        except urllib.error.HTTPError as error:
+            if error.code in (401, 403):
+                raise HelperError("RISS API가 키를 거부했습니다(HTTP 403). 발급받은 RISS 검색 API 키와 기관 권한을 확인하세요.") from error
+            if error.code == 429:
+                raise HelperError("RISS API 호출량/쿼터를 초과했습니다(HTTP 429).") from error
+            raise HelperError(f"RISS API 요청 실패: HTTP {error.code} {error.reason}") from error
+        except urllib.error.URLError as error:
+            raise HelperError(f"RISS API 네트워크 오류: {error.reason}") from error
+        except TimeoutError as error:
+            raise HelperError("RISS API 요청 시간이 초과되었습니다.") from error
+    queues = [list(result["items"]) for result in results]
+    items = []
+    while len(items) < page_size and any(queues):
+        for queue in queues:
+            if queue:
+                items.append(queue.pop(0))
+            if len(items) >= page_size:
+                break
+    return {"page": page, "page_size": page_size, "total_count": sum(result["total_count"] for result in results), "items": items}
+
+
+def format_text(payload: Dict[str, Any]) -> str:
+    items = payload.get("items") or []
+    lines = [f"RISS 학술자료 검색 결과: {payload.get('total_count', len(items))}건"]
+    labels = {"free": "원문 있음(무료 표시)", "paid_or_restricted": "원문 있음(유료/기관권한 가능)", "available": "원문 있음(접근조건 확인 필요)", "none": "원문 없음", "unknown": "원문 여부 미상"}
+    for item in items:
+        lines.append(f"- {item.get('title') or '제목 없음'} / {', '.join(item.get('authors') or []) or '저자 미상'} / {item.get('publisher') or item.get('publication') or '발행처 미상'} / {item.get('year') or '연도 미상'} / {labels.get(item.get('full_text_access'), '원문 여부 미상')}")
+        if item.get("link"):
+            lines.append(f"  {item['link']}")
+    if not items:
+        lines.append("조건에 맞는 학술자료가 없습니다.")
+    return "\n".join(lines)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="KERIS/RISS 학술자료 메타데이터 검색")
+    search = parser.add_subparsers(dest="command", required=True).add_parser("search")
+    for field in ("keyword", "title", "author", "subject", "publisher"):
+        search.add_argument(f"--{field}")
+    search.add_argument("--resource-type", choices=RESOURCE_TYPE_MAP, default="ALL")
+    search.add_argument("--page", type=int, default=1)
+    search.add_argument("--page-size", type=int, default=10)
+    search.add_argument("--secrets-path", default=str(DEFAULT_SECRETS_PATH))
+    search.add_argument("--timeout", type=int, default=20)
+    search.add_argument("--dry-run", action="store_true")
+    search.add_argument("--json", action="store_true")
+    return parser
+
+
+def parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
+    return build_parser().parse_args(argv)
+
+
+def run(argv: Optional[List[str]] = None) -> int:
+    try:
+        args = parse_args(argv)
+        query = build_query(args)
+        if args.dry_run:
+            urls = build_riss_urls(query, "REDACTED")
+            print(json.dumps({"operation": "search", "urls": urls, "query": query}, ensure_ascii=False, indent=2))
+            return 0
+        api_key = resolve_api_key(args)
+        if not api_key:
+            raise HelperError(MISSING_KEY_MSG)
+        urls = build_riss_urls(query, api_key)
+        payload = http_get_riss_xml(urls, args.timeout, query["page"], query["pageSize"])
+        print(json.dumps(payload, ensure_ascii=False, indent=2) if args.json else format_text(payload))
+        return 0
+    except HelperError as error:
+        print(str(error), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(run())

package/skills/keris-academic-search/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "keris-academic-search",
+  "description": "Use when the user asks to search Korean theses, academic articles, research reports, journals, or university-library catalog metadata through KERIS RISS. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "action:booking"
+  ],
+  "frontmatter": "name: keris-academic-search\ndescription: Use when the user asks to search Korean theses, academic articles, research reports, journals, or university-library catalog metadata through KERIS RISS. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: research\n  locale: ko-KR\n  phase: v1"
+}

package/skills/kleague-results/instruction.md

@@ -0,0 +1,92 @@
+# K League Results
+
+## What this skill does
+
+공식 K리그 JSON 표면으로 특정 날짜의 K리그1/K리그2 경기 결과를 조회하고, 필요하면 특정 팀(예: `FC서울`, `서울 이랜드`, 팀 코드 `K09`)만 필터링한 뒤 현재 순위까지 함께 정리한다.
+
+## When to use
+
+- "오늘 K리그1 경기 결과 알려줘"
+- "2026-03-22 FC서울 경기 결과랑 현재 순위 보여줘"
+- "2026-03-22 K리그2 결과 정리해줘"
+
+## Prerequisites
+
+- Node.js 18+
+- `npm install -g kleague-results`
+
+## Inputs
+
+- 날짜: `YYYY-MM-DD`
+- 리그: `K리그1` 또는 `K리그2` (기본값은 `K리그1`)
+- 선택 사항: 팀명, 풀네임, 팀 코드 (`서울`, `FC서울`, `K09` 등)
+
+## Workflow
+
+### 0. Install the package globally when missing
+
+`npm root -g` 아래에 `kleague-results` 가 없으면 HTML scraping 으로 우회하지 말고 먼저 전역 Node 패키지 설치를 시도한다.
+
+```bash
+npm install -g kleague-results
+```
+
+### 1. Fetch the official K League JSON
+
+이 스킬은 HTML 크롤링 대신 아래 공식 JSON 엔드포인트를 사용한다.
+
+- 일정/결과: `https://www.kleague.com/getScheduleList.do`
+- 팀 순위: `https://www.kleague.com/record/teamRank.do`
+
+```bash
+GLOBAL_NPM_ROOT="$(npm root -g)" node --input-type=module - <<'JS'
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const entry = pathToFileURL(
+  path.join(process.env.GLOBAL_NPM_ROOT, "kleague-results", "src", "index.js"),
+).href;
+const { getKLeagueSummary } = await import(entry);
+
+const summary = await getKLeagueSummary("2026-03-22", {
+  leagueId: "K리그1",
+  team: "FC서울",
+  includeStandings: true,
+});
+
+console.log(JSON.stringify(summary, null, 2));
+JS
+```
+
+### 2. Normalize for humans
+
+원본 JSON을 그대로 던지지 말고 아래 기준으로 정리한다.
+
+- 홈팀 vs 원정팀
+- 경기 시간 / 경기 종료 여부
+- 스코어
+- 현재 순위
+- 요청 팀이 있으면 해당 팀 경기만 필터링
+
+### 3. Keep the answer compact
+
+요청이 scoreboard 면 경기별 한 줄 요약부터 준다. 특정 팀 요청이면 그 팀 경기와 현재 순위만 먼저 보여준다.
+
+## Done when
+
+- 날짜 기준 경기 요약이 있다
+- 팀 요청이면 해당 팀 경기만 남아 있다
+- 현재 순위가 같이 정리되어 있다
+
+## Failure modes
+
+- K리그 사이트가 `getScheduleList.do` 또는 `teamRank.do` 응답 구조를 바꾸면 패키지 수정이 필요하다
+- 경기 전 날짜면 결과 대신 예정 상태가 반환될 수 있다
+- `서울` 처럼 짧은 이름만 주면 리그에 따라 `FC서울` / `서울 이랜드` 구분이 필요할 수 있다
+
+## Notes
+
+- 이 스킬은 조회 전용이다
+- 사용자의 "오늘/어제" 요청은 항상 절대 날짜(`YYYY-MM-DD`)로 변환해서 실행한다
+- 패키지를 새로 추가한 상태라면 머지 후 npm publish(Changesets 기반)를 진행해야 전역 설치 흐름이 살아난다
+- 자세한 사용 예시는 `docs/features/kleague-results.md` 와 `packages/kleague-results/README.md` 를 따른다

package/skills/kleague-results/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "kleague-results",
+  "description": "케이리그 경기 결과와 현재 순위를 날짜/팀 기준으로 조회한다. 공식 JSON 엔드포인트와 kleague-results npm 패키지를 사용한다.",
+  "profiles": [
+    "lookup"
+  ],
+  "frontmatter": "name: kleague-results\ndescription: 케이리그 경기 결과와 현재 순위를 날짜/팀 기준으로 조회한다. 공식 JSON 엔드포인트와 kleague-results npm 패키지를 사용한다.\nlicense: MIT\nmetadata:\n  category: sports\n  locale: ko-KR\n  phase: v1"
+}

package/skills/kopis-performance-search/instruction.md

@@ -0,0 +1,109 @@
+# KOPIS Performance Search
+
+## What this skill does
+
+KOPIS 공연예술통합전산망 Open API `https://kopis.or.kr/openApi/restful` 을 `k-skill-proxy` 경유로 호출한다. `www.kopis.or.kr` redirect는 일부 요청을 차단할 수 있어 canonical host를 직접 사용한다.
+
+지원 endpoint:
+
+- `GET /v1/kopis/performances` → `pblprfr` 공연 목록
+- `GET /v1/kopis/performances/{id}` → `pblprfr/{mt20id}` 공연 상세
+- `GET /v1/kopis/facilities` → `prfplc` 공연시설 목록
+- `GET /v1/kopis/facilities/{id}` → `prfplc/{mt10id}` 공연시설 상세
+
+예매, 좌석 선점, 결제 자동화는 범위 밖이다.
+
+## When to use
+
+- "이번 달 서울 공연 KOPIS에서 찾아줘"
+- "공연 ID PF132236 상세 보여줘"
+- "세종문화회관 KOPIS 시설 정보 찾아줘"
+
+## Prerequisites
+
+- 인터넷 연결
+- hosted/self-host `k-skill-proxy`의 `/v1/kopis/*` route 접근 가능
+
+## Credential requirements
+
+- 사용자 측 필수 시크릿 없음.
+- `KSKILL_PROXY_BASE_URL` — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+- `KOPIS_API_KEY` 또는 `KSKILL_KOPIS_API_KEY` 는 프록시 운영 서버 환경에만 둔다.
+
+키 발급: KOPIS Open API 안내 <https://www.kopis.or.kr/por/cs/openapi/openApiInfo.do?menuId=MNU_00074> 에서 회원가입/로그인 후 OpenAPI 이용신청으로 발급한다.
+
+## Inputs
+
+공연 목록:
+
+- `start`/`stdate`: 시작일 `YYYYMMDD`
+- `end`/`eddate`: 종료일 `YYYYMMDD`
+- `genre`/`shcate`: 장르 코드
+- `areaCode`/`signgucode`: 지역 코드
+- `sigunguCode`/`signgucodesub`: 시군구 코드
+- `prfstate`, `kidstate`, `openrun`, `afterdate`
+- `page`/`cpage`, `limit`/`rows`
+
+시설 목록:
+
+- `q`/`query`/`name`/`shprfnmfct`: 시설명
+- `areaCode`/`signgucode`, `sigunguCode`/`signgucodesub`
+- `fcltychartr`, `afterdate`
+- `page`/`cpage`, `limit`/`rows`
+
+## Workflow
+
+### 1. Search a small list first
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "$BASE/v1/kopis/performances" \
+  --data-urlencode "start=20260701" \
+  --data-urlencode "end=20260731" \
+  --data-urlencode "areaCode=11" \
+  --data-urlencode "limit=10"
+```
+
+### 2. Fetch details for a selected ID
+
+```bash
+curl -fsS "$BASE/v1/kopis/performances/PF132236"
+```
+
+시설명으로 먼저 찾은 뒤 시설 ID가 필요하면 상세를 조회한다.
+
+```bash
+curl -fsS --get "$BASE/v1/kopis/facilities" \
+  --data-urlencode "q=세종문화회관" \
+  --data-urlencode "limit=5"
+```
+
+## Failure modes
+
+- `400 bad_request`: 날짜 형식, 페이지 크기, ID 형식이 잘못됨.
+- `503 upstream_not_configured`: 프록시 서버에 `KOPIS_API_KEY`/`KSKILL_KOPIS_API_KEY` 없음.
+- KOPIS upstream XML 에러/빈 결과: 검색 기간·지역·장르를 완화하거나 ID를 다시 확인한다.
+- KOPIS 공식 가이드는 오류 XML 스키마를 명확히 열거하지 않는다. live 응답의 XML 본문을 그대로 확인한다.
+
+## Done when
+
+- 목록 검색은 날짜 범위를 좁혀 수행했다.
+- 상세 답변은 KOPIS `mt20id` 또는 `mt10id`를 함께 명시했다.
+- 공연명, 기간, 장소, 상태, 출처 endpoint를 원문 필드 기준으로 요약했다.
+- 예매/결제/좌석 자동화로 넘어가지 않았다.
+
+## 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/kopis/performances" --data-urlencode "start=20260701" --data-urlencode "end=20260731"` (키 미설정이면 503 확인)
+
+Live smoke는 hosted/self-host proxy에 `KOPIS_API_KEY`가 설정된 뒤 수행한다.
+
+## Safety notes
+
+- 조회 전용 스킬이다.
+- 예매, 좌석 선점, 결제, 로그인 자동화는 하지 않는다.
+- 인증키는 프록시 서버에서만 다루며 repo/GitHub Actions/public docs에 저장하지 않는다.

package/skills/kopis-performance-search/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "kopis-performance-search",
+  "description": "KOPIS 공연 목록·상세·시설을 조회하고, 돌쇠에서는 공식 예매처의 좌석·예약·승인 기반 결제까지 이어간다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "action:booking"
+  ],
+  "frontmatter": "name: kopis-performance-search\ndescription: KOPIS 공연 목록·상세·시설을 조회하고, 돌쇠에서는 공식 예매처의 좌석·예약·승인 기반 결제까지 이어간다.\nlicense: MIT\nmetadata:\n  category: culture\n  locale: ko-KR\n  phase: v1"
+}

package/skills/korea-weather/instruction.md

@@ -0,0 +1,93 @@
+# 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 에 그대로 넘긴다.
+
+```bash
+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'
+```
+
+격자 좌표 예시:
+
+```bash
+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` 를 참고한다.

package/skills/korea-weather/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "korea-weather",
+  "description": "한국 날씨를 기상청 단기예보 조회서비스와 프록시 경유로 조회해 요약한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: korea-weather\ndescription: 한국 날씨를 기상청 단기예보 조회서비스와 프록시 경유로 조회해 요약한다.\nlicense: MIT\nmetadata:\n  category: weather\n  locale: ko-KR\n  phase: v1"
+}