instruction.md
# 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에 저장하지 않는다.
references/DISCLAIMER.md
# DISCLAIMER — `kopis-performance-search`
이 스킬은 KOPIS·예매처·공연기획사 또는 자료 제공자의 공식 기능 또는 공식 지원 도구가 아니며, 공식 제휴·후원·승인·인증 또는 협업한 사실이 전혀 없습니다. 관련 상표와 서비스명은 공연정보 조회·예매 대상 설명을 위해서만 사용합니다.
대법원 2005. 6. 10. 선고 [2005도1637 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=83920)(소니용 리모컨 사건)은 기능 설명용 표장과 출처표시를 구별했습니다. [상표법 제2조](https://www.law.go.kr/법령/상표법/제2조), [제89조](https://www.law.go.kr/법령/상표법/제89조), [제90조](https://www.law.go.kr/법령/상표법/제90조), [제108조](https://www.law.go.kr/법령/상표법/제108조)에 따른 출처 혼동 판단은 별도입니다.
대법원 2022. 5. 12. 선고 [2021도1533 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=221765)은 공개정보 수집만으로 곧바로 [정보통신망법 제48조](https://www.law.go.kr/법령/정보통신망이용촉진및정보보호등에관한법률/제48조) 위반이 되는 것은 아닌 사정을 제시했지만, 크롤링·좌석 선점·결제 자동화를 일반적으로 허용하지 않습니다. [저작권법 제93조](https://www.law.go.kr/법령/저작권법/제93조)의 데이터베이스 권리와 [형법 제314조 제2항](https://www.law.go.kr/법령/형법/제314조)의 서비스 장애·영업 방해 책임은 별도입니다.
- 공개 공연정보 자동 수집은 반드시 개인의 정보 조회용으로만 사용합니다.
- 조직적·대량 크롤링, 별도 DB 구축, 반복 좌석 선점이나 구매 자동화에 사용하지 않습니다.
- 접근통제·CAPTCHA·차단·rate limit을 우회하지 않으며 예매처의 정상 영업을 방해하지 않습니다.
이 문서는 적법성을 보증하는 법률 자문이 아닙니다.
references/TRADEMARK-LEGAL-STATEMENT.md
# 상표 사용 법적 고지 — `kopis-performance-search`
이 스킬에서 `KOPIS`와 예매처 명칭은 공연정보 조회 대상과 공식 예매 연결 대상을 식별하기 위해 사용합니다. k-skill의 출처를 해당 기관·업체로 표시하거나 공식·제휴·후원·승인·협업 관계를 주장하려는 사용이 아닙니다.
대법원 2005. 6. 10. 선고 [2005도1637 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=83920)은 타인의 표장을 출처표시가 아니라 기능 또는 적용 대상을 밝히기 위해 사용하고 상표 사용으로 인식될 수 없는 경우를 구별했습니다. 실제 표시 태양과 거래계 인식에 따라 결론이 달라질 수 있으므로 평문으로 필요한 범위에서만 사용하고 로고·공식·제휴·후원·인증 표현을 사용하지 않습니다.
공개정보 접근과 사용 제한을 포함한 전체 조건은 `npx -y @nomadamas/k-skill@0 read kopis-performance-search references/DISCLAIMER.md`에서 확인합니다.
skill.json
{
"name": "kopis-performance-search",
"description": "KOPIS 공연 목록·상세·시설을 조회한다. 조회 전용.",
"profiles": [
"proxy",
"lookup"
],
"frontmatter": "name: kopis-performance-search\ndescription: KOPIS 공연 목록·상세·시설을 조회한다. 조회 전용.\nlicense: MIT\nmetadata:\n category: culture\n locale: ko-KR\n phase: v1"
}
SKILL.md
---
name: kopis-performance-search
description: KOPIS 공연 목록·상세·시설을 조회한다. 조회 전용.
license: MIT
metadata:
category: culture
locale: ko-KR
phase: v1
---
# kopis-performance-search
<!-- k-skill:cli-stub — generated by scripts/generate-skill-stubs.js; edit skill.json / instruction.md instead -->
## Get the full instructions (required first step)
Run this and follow its output as the primary instructions for this skill:
```bash
npx -y @nomadamas/k-skill@0 instruct kopis-performance-search
```
The CLI detects the current runtime (Dolshoi vault/CloakBrowser vs generic) and prints only the applicable instructions, always up to date. Helper files bundled with the CLI are listed by:
```bash
npx -y @nomadamas/k-skill@0 files kopis-performance-search
```
Keep the CLI and every coding-agent skill install current (including Vercel Agent Skills) with:
```bash
npx -y @nomadamas/k-skill@0 update
```
If `npx` is unavailable, install Node.js 18+ or follow https://github.com/NomaDamas/k-skill#readme, or read the source instructions at https://github.com/NomaDamas/k-skill/blob/main/kopis-performance-search/instruction.md.
## Legal disclaimer (required)
This skill is not an official feature of, officially supported by, affiliated with, sponsored by, approved by, or developed in collaboration with any third-party trademark owner or service operator it identifies. Third-party names are used only to describe the skill's function, lookup target, or compatibility.
Any automated collection of publicly accessible information must be limited to personal, non-organizational lookup. Do not use this skill for systematic or bulk crawling, database building, access-control or block circumvention, or conduct that interferes with a third party's business or service.
Read the full Korean legal disclaimer, including the cited Korean Supreme Court precedents and statutory limits, before use:
```bash
npx -y @nomadamas/k-skill@0 read kopis-performance-search references/DISCLAIMER.md
```
## Hard rules even without the CLI
- Never execute payment, message/email delivery, final submission, cancellation, or public posting without the user's explicit approval immediately beforehand.
- Never ask for, print, or store plaintext credentials in chat, files, or shell arguments.
- Never bypass legal, physical-presence, CAPTCHA, identity-proofing, or electronic-signature boundaries.