@nomadamas/k-skill 0.1.0

package/skills/kosis-stats/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "kosis-stats",
+  "description": "국가데이터처가 운영하는 KOSIS(국가통계포털, kosis.kr) Open API로 한국 공식 통계표를 검색하고 메타데이터·데이터·대용량 자료를 조회한다. Use when the user asks for 한국 공식 통계 (인구, 가구, 물가, 고용 등) 수치 조회, not for analysis or visualization.",
+  "profiles": [
+    "proxy",
+    "lookup"
+  ],
+  "frontmatter": "name: kosis-stats\ndescription: 국가데이터처가 운영하는 KOSIS(국가통계포털, kosis.kr) Open API로 한국 공식 통계표를 검색하고 메타데이터·데이터·대용량 자료를 조회한다. Use when the user asks for 한국 공식 통계 (인구, 가구, 물가, 고용 등) 수치 조회, not for analysis or visualization.\nlicense: MIT\nmetadata:\n  category: data\n  locale: ko-KR\n  phase: v1"
+}

package/skills/kr-whois-lookup/instruction.md

@@ -0,0 +1,107 @@
+# KR WHOIS Lookup
+
+## What this skill does
+
+공공데이터포털의 **WHOIS 도메인/IP 정보 API**(data.go.kr `15094277`)의 공식 endpoint를 `k-skill-proxy` 경유로 호출한다.
+
+지원 범위는 `.kr`/`.한국` 도메인, IPv4/IPv6 주소, `AS1234` 형식의 AS 번호다. 등록기관, 등록/할당일, 상태, 네임서버, 네트워크 범위, 국가 코드 등 공개 가능한 필드를 원문 기반으로 요약한다.
+
+## When to use
+
+- ".kr 도메인 WHOIS 조회해줘"
+- "kisa.or.kr 등록기관과 만료일 확인해줘"
+- ".한국 도메인 네임서버 확인해줘"
+- "202.30.50.51 IP WHOIS 조회해줘"
+- "AS9700 할당 기관 확인해줘"
+
+## When not to use
+
+- `.com`, `.net` 등 해외 gTLD WHOIS 조회
+- 개인정보 비공개 우회, 대량 수집, 연락처 자동 추출
+- 역방향 DNS, 지리 좌표, 위협 인텔리전스, 포트 스캔처럼 WHOIS 공개 등록정보가 아닌 조회
+
+## Prerequisites
+
+- 인터넷 연결
+- hosted/self-host `k-skill-proxy`의 `/v1/kr-whois/domain`, `/v1/kr-whois/ip`, `/v1/kr-whois/as` route 접근 가능
+
+## Credential requirements
+
+- 사용자 측 필수 시크릿 없음.
+- `KSKILL_PROXY_BASE_URL` — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+- `DATA_GO_KR_API_KEY` 는 프록시 운영 서버 환경에만 둔다. 공공데이터포털 `WHOIS 도메인/IP 정보 API`(15094277) 활용신청이 승인돼 있어야 한다.
+
+키 발급: <https://www.data.go.kr/data/15094277/openapi.do> 에서 활용신청 후 공공데이터포털 마이페이지의 일반 인증키를 확인한다. 포털 이용 가이드는 <https://www.data.go.kr/ugs/selectPublicDataUseGuideView.do> 를 참고한다.
+
+## Inputs
+
+- 도메인: `domain`, `query`, 또는 `q`에 조회할 `.kr`/`.한국` 도메인
+- IP: `ip`, `query`, 또는 `q`에 유효한 IPv4/IPv6 주소
+- AS: `asn`, `as`, `query`, 또는 `q`에 `AS9700` 같은 `AS<digits>` 형식의 AS 번호
+
+## Workflow
+
+### 1. Classify and normalize the query
+
+도메인 URL은 scheme/path를 제거하고 `.kr`/`.한국` 도메인만 남긴다. IP는 유효한 IPv4/IPv6인지 검증한다. AS 번호는 대소문자와 공백을 정리해 `AS<digits>` 형식으로 만든다.
+
+### 2. Query through the proxy
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "$BASE/v1/kr-whois/domain" \
+  --data-urlencode "domain=kisa.or.kr"
+
+curl -fsS --get "$BASE/v1/kr-whois/ip" \
+  --data-urlencode "ip=202.30.50.51"
+
+curl -fsS --get "$BASE/v1/kr-whois/as" \
+  --data-urlencode "asn=AS9700"
+```
+
+### 3. Summarize public fields only
+
+응답에서 다음 필드를 우선 확인한다.
+
+- `result_code`, `result_msg`: upstream 결과
+- 공통: `query`, `queryType`, `result_code`, `result_msg`
+- 도메인: `name`, `regName`, `agency`, `agency_url`
+- `regDate`, `endDate`, `lastUpdatedDate`
+- `domainStatus`, `dnssec`
+- `ns1`, `ns2`, `ip1`, `ip2` 등 네임서버/주소 필드
+- IP/AS: 할당 기관, 네트워크 범위, 국가 코드, 할당일과 공개 연락처 필드
+
+개인 연락처로 보이는 값은 그대로 확산하지 말고, 공개 API 응답에 포함된 정보라는 점과 남용 금지 문구를 함께 둔다.
+
+## Failure modes
+
+- `400 bad_request`: 필수 입력이 없거나 도메인/IP/AS 형식이 올바르지 않음.
+- `503 upstream_not_configured`: 프록시 서버에 `DATA_GO_KR_API_KEY` 가 없거나 15094277 활용신청이 승인되지 않음.
+- `502 upstream_forbidden`: data.go.kr gateway가 키를 거부함(`SERVICE KEY IS NOT REGISTERED ERROR` 등).
+- upstream `result_code`가 `10000`이 아님: `result_msg`를 확인하고 입력 형식과 할당 여부를 점검한다.
+- 빈 결과: 등록·할당되지 않았거나 WHOIS가 공개하지 않는 대상일 수 있다.
+
+## Done when
+
+- 입력 유형에 맞는 domain/IP/AS route를 사용했다.
+- `k-skill-proxy` route를 통해 호출했고 사용자에게 API key를 요구하지 않았다.
+- 등록·할당 기관, 날짜, 상태, 네임서버 또는 네트워크 범위를 원문 필드 기준으로 요약했다.
+- 개인정보·연락처 필드는 남용 금지와 공개 원천 한계를 함께 설명했다.
+
+## Maintainer review notes
+
+키 없이 가능한 검증:
+
+- `./scripts/validate-skills.sh`
+- `node --test packages/k-skill-proxy/test/server.test.js`
+- `curl -fsS --get "$KSKILL_PROXY_BASE_URL/v1/kr-whois/domain" --data-urlencode "domain=kisa.or.kr"`
+- `curl -fsS --get "$KSKILL_PROXY_BASE_URL/v1/kr-whois/ip" --data-urlencode "ip=202.30.50.51"`
+- `curl -fsS --get "$KSKILL_PROXY_BASE_URL/v1/kr-whois/as" --data-urlencode "asn=AS9700"`
+
+위 live smoke는 hosted/self-host proxy에 `DATA_GO_KR_API_KEY`와 15094277 활용신청이 있을 때 수행한다. 공식 upstream 경로는 각각 `B551505/whois/domain_name`, `B551505/whois/ip_address`, `B551505/whois/as_number`다.
+
+## Safety notes
+
+- 조회 전용 스킬이다.
+- 개인정보 비공개 우회, 연락처 대량 수집, 보안 공격 자동화에 사용하지 않는다.
+- 인증키는 프록시 서버에서만 다루며 repo/GitHub Actions/public docs에 저장하지 않는다.

package/skills/kr-whois-lookup/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "kr-whois-lookup",
+  "description": "공공데이터포털 WHOIS 도메인/IP 정보 API를 k-skill-proxy 경유로 호출해 .kr/.한국 도메인, IP 주소, AS 번호의 공개 등록정보를 조회한다. 조회 전용. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "action:communication"
+  ],
+  "frontmatter": "name: kr-whois-lookup\ndescription: 공공데이터포털 WHOIS 도메인/IP 정보 API를 k-skill-proxy 경유로 호출해 .kr/.한국 도메인, IP 주소, AS 번호의 공개 등록정보를 조회한다. 조회 전용. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: security\n  locale: ko-KR\n  phase: v1"
+}

package/skills/kstartup-search/instruction.md

@@ -0,0 +1,186 @@
+# 창업진흥원 K-Startup 조회
+
+## What this skill does
+
+공공데이터포털의 **창업진흥원_K-Startup(사업소개,사업공고,콘텐츠 등)_조회서비스** (`kisedKstartupService01`, dataset `15125364`)를 `k-skill-proxy` 경유로 호출해 다음 4개 endpoint를 조회한다.
+
+- `business-info` → `getBusinessInformation01` : 통합공고 지원사업 정보 (예산, 규모, 수행기관, 사업소개)
+- `announcements` → `getAnnouncementInformation01` : 지원사업 공고 정보 (공고명, 접수기간, 지역, 신청대상, 모집진행여부 등 — **가장 활용도 높음**)
+- `contents` → `getContentInformation01` : 창업관련 콘텐츠 (공지·뉴스·우수사례 등)
+- `statistics` → `getStatisticalInformation01` : 창업관련 통계보고서
+
+API helper는 조회 전용이다. 돌쇠에서 사용자가 사업 신청을 요청하면 조회 결과를 위 `Dolshoi action path`의 공식 CloakBrowser 신청 흐름으로 이어간다.
+
+## When to use
+
+- "이번 달 마감 예정인 청년 창업지원 공고 찾아줘"
+- "서울 소재 모집 진행 중인 1인 창조기업 지원사업 알려줘"
+- "K-Startup에서 사업화 단계 통합공고 사업 목록 뽑아줘"
+- "창업진흥원 최신 통계보고서 5건 보여줘"
+
+## When not to use
+
+- 돌쇠가 아니며 사업 신청·결제·자동 지원·계좌 연계 같은 쓰기 동작이 필요한 경우
+- K-Startup 외부 사이트(중기부, 창조경제혁신센터, 지자체 단독 공고) 조회 — 통합공고에 등록된 일부만 K-Startup API로 노출된다
+- 마감일·모집 상태를 분 단위로 추적해야 하는 작업 — 데이터 갱신은 공식 서비스설계서 기준 **일 1회**다 (공공데이터포털 dataset 메타데이터에는 "실시간"으로 표기되지만 두 표면이 일치하지 않는다)
+
+## Prerequisites
+
+- 인터넷 연결
+- `python3` (stdlib only)
+- 설치된 스킬 안의 `scripts/run_kstartup.py`
+- hosted/self-host `k-skill-proxy`의 `/v1/kstartup/*` 라우트 접근 가능 (4개)
+
+## Credential requirements
+
+- 사용자 측 필수 시크릿 없음.
+- `KSKILL_PROXY_BASE_URL` — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted `https://k-skill-proxy.nomadamas.org`.
+- `KSKILL_KSTARTUP_API_KEY` — `--direct`로 K-Startup을 직접 호출할 때만 필요. 공공데이터포털에서 `창업진흥원_K-Startup(사업소개,사업공고, 콘텐츠 등)_조회서비스` (`15125364`) 활용신청이 본인 계정으로 승인돼 있어야 한다(자동승인, 무료).
+- 프록시 운영자는 `DATA_GO_KR_API_KEY` 환경변수에 같은 조건의 키를 두고 활용신청을 추가해 둔다.
+
+### Credential resolution order (`--direct` 전용)
+
+1. 돌쇠 credential mode에서는 provisioned `vault-run` capability를 사용하고, 없으면 `request_vault_credential`로 K-Startup API key 입력 UI를 호출한다.
+2. 그 밖의 환경에서는 이미 주입된 환경변수 → host vault → `~/.config/k-skill/secrets.env` (`0600`) 순서로 사용한다.
+3. generic fallback에서 값이 없으면 호스트의 가장 안전한 입력 표면으로 받아 vault 또는 dotenv에 저장한다.
+
+일반 조회 helper는 proxy URL만 읽고, K-Startup 인증키는 프록시 서버에서만 주입한다. `--direct` 호출에서만 `KSKILL_KSTARTUP_API_KEY`를 읽는다.
+
+## Inputs
+
+서브커맨드: `business-info`, `announcements`, `contents`, `statistics`.
+
+공통 옵션:
+
+- `--page N` (기본 1, ≥ 1)
+- `--per-page N` (기본 10, 1–100)
+- `--text` 사람용 요약 / `--json` 구조화 결과(기본)
+- `--dry-run` 인증키 없이 요청 URL/파라미터만 출력
+- `--timeout N` HTTP 타임아웃 초 (기본 30)
+- `--proxy-base-url URL` 기본 hosted proxy 대신 self-host/alternate proxy
+- `--direct` proxy 우회, `KSKILL_KSTARTUP_API_KEY`로 직접 호출
+
+서브커맨드별 필터:
+
+- `business-info`
+  - `--biz-yr 2024` (사업 연도, 4자리)
+  - `--biz-category-cd cmrczn_Tab3` (사업 구분 코드)
+  - `--supt-biz-titl-nm "1인 창조기업"` (사업 명)
+- `announcements`
+  - `--biz-pbanc-nm "키워드"` (지원 사업 공고 명)
+  - `--supt-regin 서울특별시` (지역명. **K-Startup upstream이 이 필터를 서버 측에서 적용하지 않는 사례가 있다** — 응답을 받은 뒤 client에서 `supt_regin` 으로 한 번 더 거른다)
+  - `--supt-biz-clsfc 사업화` (지원 분야)
+  - `--pbanc-rcpt-bgng-dt 20240101` / `--pbanc-rcpt-end-dt 20241231` (공고 접수 시작/종료, YYYYMMDD)
+  - `--aply-trgt 일반인,예비창업자` (신청 대상)
+  - `--biz-enyy 예비창업자,1년미만` (창업 기간)
+  - `--biz-trgt-age "만 20세 이상 ~ 만 39세 이하"` (대상 연령)
+  - `--rcrt-prgs-yn Y|N` (모집진행여부)
+  - `--intg-pbanc-yn Y|N` (통합 공고 여부)
+- `contents`
+  - `--clss-cd notice_matr` (콘텐츠 구분 코드: notice_matr 등)
+  - `--titl-nm "공모전"` (제목 키워드)
+- `statistics`
+  - `--titl-nm "창업기업 실태조사"` (통계 자료 명)
+  - `--file-nm "PDF"` (파일 명/내용 키워드)
+
+## Workflow
+
+### 1. Ensure proxy access is available
+
+일반 조회는 기본 hosted `k-skill-proxy`를 사용하므로 사용자 K-Startup 키가 필요 없다. self-host를 쓰면 `KSKILL_PROXY_BASE_URL`을 설정한다. `--direct`가 필요할 때만 `KSKILL_KSTARTUP_API_KEY`를 credential resolution order에 따라 확보한다.
+
+### 2. Pick the right operation
+
+- 마감 임박/지역 필터/대상별 공고 추천 → `announcements`
+- 사업의 전반적 소개·예산 규모 → `business-info`
+- 정책 공지·우수사례 → `contents`
+- 보고서/통계 데이터 → `statistics`
+
+### 3. Fetch a small bounded slice first
+
+`--per-page 10` 정도로 먼저 한 페이지를 받아 응답 스키마를 확인한 뒤, 필터를 좁히거나 페이지를 넘긴다.
+
+```bash
+python3 scripts/run_kstartup.py announcements \
+  --supt-regin 서울특별시 --rcrt-prgs-yn Y --per-page 5 --text
+```
+
+### 4. Filter on the client side for richer questions
+
+API는 단순 필드 매칭만 지원하고, **그중 `supt_regin` 같은 일부 필터는 upstream이 서버 측에서 적용하지 않는 사례가 관측된다.** `--supt-regin 서울특별시`로 호출해도 타 지역 공고가 섞여 돌아오는 경우가 있어서, `supt_regin`·`aply_trgt`·`biz_enyy` 필드는 helper가 받은 응답을 client에서 한 번 더 거른다.
+
+- 응답 `supt_regin`은 upstream이 축약형(`서울`, `경기`, `충북`)으로 돌려준다. helper는 사용자가 `--supt-regin 서울특별시` 같은 표준 광역지자체명을 줘도 17개 광역시·도(+ `전국`) 매핑 테이블로 자동 정규화해 매치한다.
+- client filter가 적용되면 응답 JSON에 `client_filter: {fields, upstream_returned, after_filter}` 블록이 함께 붙는다. `upstream_returned`는 같지만 `after_filter`가 작으면 첫 페이지로는 부족하니 `--page`를 늘려 추가 페이지를 받는다.
+- 쉼표로 여러 값을 주면 AND 매치다 (`--aply-trgt 예비창업자,1년미만` → 두 토큰 모두 row에 있어야 통과).
+- `pbanc_rcpt_end_dt`는 `YYYYMMDD` 문자열이라 KST 기준으로 직접 비교한다. "이번 주 마감", "30대 대상", "특정 키워드 포함" 같은 복합 조건은 helper가 안 거르므로 응답 JSON에서 agent가 직접 처리한다.
+
+### 5. Cite the source
+
+응답을 요약할 때는 endpoint 이름, 호출 page/perPage, 응답의 `pbanc_sn` 또는 `detl_pg_url`을 함께 적는다. 상세는 https://www.k-startup.go.kr 의 해당 URL로 안내한다.
+
+## CLI examples
+
+```bash
+# 서울 모집 중 공고 5건
+python3 scripts/run_kstartup.py announcements \
+  --supt-regin 서울특별시 --rcrt-prgs-yn Y --per-page 5 --text
+
+# 2024년 사업화 분야 통합공고
+python3 scripts/run_kstartup.py business-info \
+  --biz-yr 2024 --biz-category-cd cmrczn_Tab3 --json
+
+# 정책·공지 최신 콘텐츠
+python3 scripts/run_kstartup.py contents \
+  --clss-cd notice_matr --per-page 10 --text
+
+# 창업기업 실태조사 통계보고서
+python3 scripts/run_kstartup.py statistics \
+  --titl-nm "창업기업 실태조사" --per-page 5 --json
+
+# 인증키 없이 dry-run 으로 요청 점검
+python3 scripts/run_kstartup.py announcements \
+  --supt-regin 부산광역시 --dry-run
+```
+
+## Direct proxy examples
+
+```bash
+curl -fsS "$KSKILL_PROXY_BASE_URL/v1/kstartup/announcements?supt_regin=$(python3 -c 'import urllib.parse;print(urllib.parse.quote(\"서울특별시\"))')&rcrt_prgs_yn=Y&perPage=5"
+```
+
+## Failure modes
+
+- `400 bad_request`: 잘못된 날짜(`YYYYMMDD` 아님), 잘못된 `Y/N`, perPage 범위 초과, 시작일 > 종료일 → 메시지대로 입력 보정.
+- `503 upstream_not_configured`: 프록시 서버에 `DATA_GO_KR_API_KEY`가 없거나 해당 데이터셋 활용신청이 미승인.
+- `502 upstream_error`: data.go.kr 응답이 `resultCode != "00"` 또는 `errMsg`/`SERVICE_KEY_IS_NOT_REGISTERED_ERROR` 등 인증/한도 오류.
+  - data.go.kr 에러 코드: 10(잘못된 파라미터), 20(접근거부), 22(요청제한 초과), 30(미등록 키), 31(만료), 32(미등록 IP).
+- `502 upstream_invalid_response`: data.go.kr이 JSON 대신 HTML/XML 본문을 보낸 경우(점검·차단 등). `upstream_body` 앞 500자가 함께 반환된다.
+- 빈 `data` 배열: 필터에 일치하는 공고/콘텐츠 없음. 키워드/지역/대상 범위를 완화한다.
+- 일 갱신 1회(서비스설계서 기준): 같은 날 같은 공고의 마감일·상태가 갱신되지 않을 수 있으므로, 마감/접수 상태는 응답의 `detl_pg_url` 페이지에서 최종 확인한다.
+
+## Done when
+
+- 사용자가 찾는 endpoint (`business-info` / `announcements` / `contents` / `statistics`)를 골랐다.
+- 작은 슬라이스로 첫 페이지를 받아 응답 스키마/필드를 확인했다.
+- 필터를 좁히거나 클라이언트에서 후처리해 답변에 필요한 핵심 행만 남겼다.
+- 결과에 출처(endpoint, page/perPage, `detl_pg_url` 또는 `pbanc_sn`)를 명시했다.
+
+## Maintainer review notes
+
+K-Startup 인증키 없이도 다음 검증이 가능하다.
+
+- `./scripts/validate-skills.sh`
+- `python3 -m py_compile kstartup-search/scripts/run_kstartup.py kstartup-search/tests/test_run_kstartup.py`
+- `python3 kstartup-search/scripts/run_kstartup.py --help`
+- `python3 kstartup-search/scripts/run_kstartup.py announcements --supt-regin 서울특별시 --dry-run`
+- `PYTHONPATH=kstartup-search/scripts python3 -m unittest discover -s kstartup-search/tests -p 'test_*.py' -v`
+- `node --test packages/k-skill-proxy/test/server.test.js` (K-Startup 라우트 5개 신규 케이스 포함)
+- `npm run ci`
+
+라이브 스모크는 hosted proxy 환경에 `DATA_GO_KR_API_KEY` 가 설정되고 `15125364` 활용신청이 승인된 뒤에 수행한다.
+
+## Safety notes
+
+- 조회 전용 스킬. 사업 신청·계좌 연결·결제 자동화는 하지 않는다.
+- 응답에 K-Startup 사이트 URL이 있으면 그대로 안내하고, 실제 신청은 사용자가 브라우저에서 직접 진행한다.
+- 인증키는 프록시 서버에서만 다루며, `--dry-run` 시에도 helper는 `<DRY-RUN>`로 대체한다.