@nomadamas/k-skill 0.1.0

package/skills/fsc-corporate-info/scripts/fsc_corporate_info.py

@@ -0,0 +1,113 @@
+"""FSC corporate-outline lookup via k-skill-proxy.
+
+The proxy holds DATA_GO_KR_API_KEY server-side; this helper only builds the
+query and reads the structured response. No user secret is required.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+PROXY_BASE_URL_ENV_VAR = "KSKILL_PROXY_BASE_URL"
+DEFAULT_PROXY_BASE_URL = "https://k-skill-proxy.nomadamas.org"
+PROXY_DOWN_MSG = "설정된 k-skill-proxy 서버가 응답하지 않습니다. 잠시 후 재시도하거나 운영자에게 문의하세요."
+PROXY_KEY_NOT_CONFIGURED_MSG = "k-skill-proxy에 필요한 API 키가 설정되어 있지 않습니다. 운영자에게 문의하세요."
+ROUTE = "/v1/fsc/corp-outline"
+
+
+class ApiError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+def _text_or_none(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def resolve_proxy_base_url(explicit: str | None = None, env: dict[str, str] | None = None) -> str:
+    env = os.environ if env is None else env
+    candidate = _text_or_none(explicit or env.get(PROXY_BASE_URL_ENV_VAR))
+    if candidate and candidate.casefold() in {"off", "false", "0", "disable", "disabled", "none"}:
+        raise ValueError("KSKILL_PROXY_BASE_URL 가 비활성화되어 있습니다.")
+    if candidate and candidate != "replace-me":
+        return candidate.rstrip("/")
+    return DEFAULT_PROXY_BASE_URL
+
+
+def read_json_response(request: urllib.request.Request) -> dict[str, Any]:
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            try:
+                payload = json.loads(response.read().decode("utf-8"))
+            except json.JSONDecodeError as error:
+                raise ApiError("fsc corp-outline proxy returned invalid JSON.") from error
+            if not isinstance(payload, dict):
+                raise ApiError("fsc corp-outline proxy returned a non-object JSON payload.")
+            return payload
+    except urllib.error.HTTPError as error:
+        body = error.read().decode("utf-8", errors="replace")
+        try:
+            payload = json.loads(body)
+        except json.JSONDecodeError:
+            payload = None
+        if error.code == 503 and isinstance(payload, dict) and payload.get("error") == "upstream_not_configured":
+            raise ApiError(PROXY_KEY_NOT_CONFIGURED_MSG, status_code=error.code) from error
+        if isinstance(payload, dict) and payload.get("message"):
+            raise ApiError(str(payload["message"]), status_code=error.code) from error
+        raise ApiError(f"fsc corp-outline proxy request failed with HTTP {error.code}", status_code=error.code) from error
+    except urllib.error.URLError as error:
+        raise ApiError(f"{PROXY_DOWN_MSG} (상세: {error.reason})") from error
+
+
+def query_corp_outline(name: str, b_no: str | None = None, *, base_url: str | None = None,
+                       read_json: Any = read_json_response) -> dict[str, Any]:
+    name = _text_or_none(name)
+    if not name:
+        raise ValueError("법인명(corpNm)을 입력하세요. 이 API는 사업자번호 단독 조회가 불가합니다.")
+    params = {"name": name}
+    if _text_or_none(b_no):
+        digits = re.sub(r"\D", "", str(b_no))
+        if not re.fullmatch(r"\d{10}", digits):
+            raise ValueError("사업자등록번호는 숫자 10자리여야 합니다 (하이픈 허용).")
+        params["b_no"] = digits
+    url = f"{resolve_proxy_base_url(base_url)}{ROUTE}?{urllib.parse.urlencode(params)}"
+    request = urllib.request.Request(url, headers={
+        "Accept": "application/json",
+        "User-Agent": "k-skill-fsc-corporate-info/1.0",
+    }, method="GET")
+    return read_json(request)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="금융위 기업기본정보(법인 개요) 조회 (k-skill-proxy 경유)")
+    parser.add_argument("--name", required=True, help="법인명(corpNm) — 필수")
+    parser.add_argument("--b-no", help="사업자등록번호 — 응답에 bzno가 있을 때 교차검증에만 사용")
+    parser.add_argument("--proxy-base-url")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        result = query_corp_outline(args.name, args.b_no, base_url=args.proxy_base_url)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    except (ValueError, ApiError) as error:
+        print(json.dumps({"error": str(error)}, ensure_ascii=False, indent=2), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/fsc-corporate-info/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "fsc-corporate-info",
+  "description": "금융위원회 기업기본정보(법인 개요)를 공공데이터포털 API(k-skill-proxy 경유)로 조회한다. 법인명으로 대표자·설립일·업종 등 법인 개요를 확인하고, 응답에 사업자번호가 있으면 입력 번호와 교차검증한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: fsc-corporate-info\ndescription: 금융위원회 기업기본정보(법인 개요)를 공공데이터포털 API(k-skill-proxy 경유)로 조회한다. 법인명으로 대표자·설립일·업종 등 법인 개요를 확인하고, 응답에 사업자번호가 있으면 입력 번호와 교차검증한다.\nlicense: MIT\nmetadata:\n  category: business\n  locale: ko-KR\n  phase: v1"
+}

package/skills/g2b-order-plan-search/instruction.md

@@ -0,0 +1,131 @@
+# 나라장터 발주계획 검색
+
+## What this skill does
+
+`g2b-order-plan-search`는 공공데이터포털의 **조달청_나라장터 발주계획현황서비스**(data.go.kr 15129462, `OrderPlanSttusService`)를 `k-skill-proxy` 경유로 호출해 나라장터에 등록된 발주계획 목록을 조회한다.
+
+- 대상 업무: 물품, 공사, 용역, 외자
+- 검색 조건: 발주년월 범위, 게시일시 범위, 발주기관명/코드, 사업명 키워드, 조달방식, 기관소재지, 세부품명번호, 업무유형, 공종 등
+- 반환: 발주년도/월, 발주기관, 사업명, 계약방법, 발주금액, 담당부서/담당자/전화번호, 입찰공고번호목록 등 upstream 원문 필드
+
+입찰 참가, 로그인, 입찰서 제출, 인증서 작업, 결제, 낙찰/계약 처리 자동화는 하지 않는다.
+
+## Public access path discovered
+
+### Primary source: 공공데이터포털 API through k-skill-proxy
+
+- data.go.kr dataset: <https://www.data.go.kr/data/15129462/openapi.do>
+- upstream base: `https://apis.data.go.kr/1230000/ao/OrderPlanSttusService`
+- proxy route: `GET /v1/g2b/order-plans`
+- API key location: proxy server only (`DATA_GO_KR_API_KEY`)
+
+Operations used:
+
+| kind | endpoint |
+| --- | --- |
+| `goods` / `물품` | `getOrderPlanSttusListThngPPSSrch` |
+| `construction` / `공사` | `getOrderPlanSttusListCnstwkPPSSrch` |
+| `service` / `용역` | `getOrderPlanSttusListServcPPSSrch` |
+| `foreign` / `외자` | `getOrderPlanSttusListFrgcptPPSSrch` |
+| `all` / `전체` | above four endpoints, merged with `_order_plan_kind` |
+
+The API is a free data.go.kr service that requires an application key, so it follows the repository's free-API proxy policy and does not expose the key to users.
+
+## When to use
+
+- "나라장터 발주목록에서 청소 용역 찾아줘"
+- "조달청 물품 발주계획 2025년 1월 목록 조회"
+- "서울 기관 공사 발주계획 검색"
+- "발주기관명으로 나라장터 발주계획 보여줘"
+
+## Prerequisites
+
+- 인터넷 연결, `python3`
+- hosted/self-host `k-skill-proxy`의 `/v1/g2b/order-plans` route 접근 가능
+- proxy 운영 서버의 `DATA_GO_KR_API_KEY`가 data.go.kr 15129462에 활용신청되어 있어야 함
+
+사용자 측 필수 시크릿은 없다. Self-host proxy를 쓸 때만 `KSKILL_PROXY_BASE_URL`을 설정한다.
+
+## Inputs
+
+CLI flags:
+
+- `--kind`: `goods`/`물품`, `construction`/`공사`, `service`/`용역`, `foreign`/`외자`, `all`/`전체` (default `goods`)
+- `--keyword`, `-q`: 사업명 검색어 (`bizNm`)
+- `--order-from`, `--order-to`: 발주년월 범위 (`YYYY-MM` 또는 `YYYYMM`)
+- `--posted-from`, `--posted-to`: 게시일시 범위 (`YYYY-MM-DD`, `YYYYMMDD`, `YYYYMMDDHHMM`)
+- `--institution`: 발주기관명
+- `--institution-code`: 발주기관코드
+- `--region`: 기관소재지명
+- `--procurement-method`: 조달방식
+- `--product-code`: 세부품명번호(물품)
+- `--business-type`: 업무유형명/업무유형코드(공사·용역·외자)
+- `--construction-type`: 공종구분명(공사)
+- `--page`, `--limit`: 페이지와 한 페이지 결과 수(최대 100)
+
+## Workflow
+
+### 1. Search order plans
+
+```bash
+python3 g2b-order-plan-search/scripts/g2b_order_plan.py \
+  --kind service \
+  --keyword 청소 \
+  --order-from 2025-01 \
+  --order-to 2025-03 \
+  --posted-from 2025-01-01 \
+  --posted-to 2025-01-31 \
+  --limit 10
+```
+
+### 2. Narrow by institution or location
+
+```bash
+python3 g2b-order-plan-search/scripts/g2b_order_plan.py \
+  --kind goods \
+  --institution 조달청 \
+  --region 대전 \
+  --order-from 2025-01 \
+  --order-to 2025-01
+```
+
+### 3. Read output conservatively
+
+The result is the proxy JSON response. Important fields:
+
+- `query`: normalized upstream parameters and selected operation
+- `total_count`, `page`, `page_size`
+- `items[]`: upstream order-plan rows
+- `items[].orderPlanUntyNo`: 발주계획통합번호
+- `items[].bizNm`: 사업명
+- `items[].orderInsttNm`: 발주기관명
+- `items[].orderMnth`: 발주월
+- `items[].sumOrderAmt`, `items[].orderContrctAmt`: 발주금액 fields when upstream provides them
+- `items[].bidNtceNoList`: linked bid notice numbers when upstream provides them
+
+When answering, show the official source (data.go.kr dataset and g2b.go.kr manual verification URL) and state that 발주계획은 사전계획이며 실제 사전규격/입찰공고/계약과 1:1로 보장되지 않는다.
+
+## Done when
+
+- The proxy route `/v1/g2b/order-plans` was queried.
+- The selected `kind` mapped to the correct PPS order-plan endpoint.
+- Date/month filters and keyword/institution filters are reflected in `query`.
+- Results include source fields and manual verification guidance.
+- No login, bidding, certificate, submission, or payment flow was automated.
+
+## Failure modes
+
+- `503 upstream_not_configured`: proxy server has no `DATA_GO_KR_API_KEY`.
+- `502 upstream_forbidden`: proxy key is not approved for data.go.kr service 15129462.
+- `400 bad_request`: invalid kind, date/month, page, or limit input.
+- `total_count = 0`: no order plans matched the selected conditions.
+- Upstream resultCode `03`: data.go.kr reports no data.
+- API changed endpoint names, parameters, or envelope shape.
+- 발주계획은 실제 입찰공고 등록의 필수 선행조건이 아니며, 발주계획에 없는 사전규격·입찰공고·계약도 있을 수 있다.
+
+## Official surfaces
+
+- 공공데이터포털: <https://www.data.go.kr/data/15129462/openapi.do>
+- upstream: `https://apis.data.go.kr/1230000/ao/OrderPlanSttusService`
+- 수동 대조: 나라장터 <https://www.g2b.go.kr>
+- proxy route: `GET /v1/g2b/order-plans`

package/skills/g2b-order-plan-search/scripts/g2b_order_plan.py

@@ -0,0 +1,158 @@
+"""나라장터 발주계획현황 조회 via k-skill-proxy.
+
+The helper calls k-skill-proxy /v1/g2b/order-plans so DATA_GO_KR_API_KEY stays
+server-side. It is read-only and does not automate g2b.go.kr login flows.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Mapping
+from typing import Any
+
+PROXY_BASE_URL_ENV_VAR = "KSKILL_PROXY_BASE_URL"
+DEFAULT_PROXY_BASE_URL = "https://k-skill-proxy.nomadamas.org"
+PROXY_DOWN_MSG = "설정된 k-skill-proxy 서버가 응답하지 않습니다. 잠시 후 재시도하거나 운영자에게 문의하세요."
+PROXY_KEY_NOT_CONFIGURED_MSG = "k-skill-proxy에 필요한 API 키가 설정되어 있지 않습니다. 운영자에게 문의하세요."
+ROUTE = "/v1/g2b/order-plans"
+USER_AGENT = "k-skill-g2b-order-plan-search/0.1 (+https://github.com/NomaDamas/k-skill)"
+
+
+class ApiError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+def _text_or_none(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def resolve_proxy_base_url(explicit: str | None = None, env: Mapping[str, str] | None = None) -> str:
+    env = os.environ if env is None else env
+    raw = _text_or_none(explicit) or _text_or_none(env.get(PROXY_BASE_URL_ENV_VAR))
+    if raw:
+        parsed = urllib.parse.urlparse(raw)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise ValueError(f"{PROXY_BASE_URL_ENV_VAR} must be an http(s) URL")
+        return raw.rstrip("/")
+    return DEFAULT_PROXY_BASE_URL
+
+
+def _normalize_month(value: str | None, label: str) -> str | None:
+    raw = _text_or_none(value)
+    if raw is None:
+        return None
+    digits = "".join(ch for ch in raw if ch.isdigit())
+    if len(digits) != 6 or not 1 <= int(digits[4:6]) <= 12:
+        raise ValueError(f"{label} must be YYYY-MM or YYYYMM")
+    return digits
+
+
+def _normalize_date(value: str | None, label: str) -> str | None:
+    raw = _text_or_none(value)
+    if raw is None:
+        return None
+    digits = "".join(ch for ch in raw if ch.isdigit())
+    if len(digits) not in {8, 12}:
+        raise ValueError(f"{label} must be YYYY-MM-DD, YYYYMMDD, or YYYYMMDDHHMM")
+    return digits
+
+
+def build_query(args: argparse.Namespace) -> dict[str, str]:
+    query: dict[str, str] = {
+        "kind": args.kind,
+        "page": str(args.page),
+        "limit": str(args.limit),
+    }
+    optional = {
+        "keyword": args.keyword,
+        "orderFrom": _normalize_month(args.order_from, "--order-from"),
+        "orderTo": _normalize_month(args.order_to, "--order-to"),
+        "postedFrom": _normalize_date(args.posted_from, "--posted-from"),
+        "postedTo": _normalize_date(args.posted_to, "--posted-to"),
+        "institution": args.institution,
+        "institutionCode": args.institution_code,
+        "region": args.region,
+        "procurementMethod": args.procurement_method,
+        "productCode": args.product_code,
+        "businessType": args.business_type,
+        "constructionType": args.construction_type,
+    }
+    for key, value in optional.items():
+        text = _text_or_none(value)
+        if text is not None:
+            query[key] = text
+    return query
+
+
+def read_json_response(request: urllib.request.Request) -> dict[str, Any]:
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            charset = response.headers.get_content_charset() or "utf-8"
+            return json.loads(response.read().decode(charset))
+    except urllib.error.HTTPError as error:
+        body = error.read().decode("utf-8", errors="replace")
+        try:
+            parsed = json.loads(body)
+        except json.JSONDecodeError:
+            parsed = {"message": body}
+        if error.code == 503 and parsed.get("error") == "upstream_not_configured":
+            raise ApiError(PROXY_KEY_NOT_CONFIGURED_MSG, status_code=error.code) from error
+        message = parsed.get("message") or parsed.get("error") or body or str(error)
+        raise ApiError(f"g2b order-plan proxy returned HTTP {error.code}: {message}", status_code=error.code) from error
+    except urllib.error.URLError as error:
+        raise ApiError(f"{PROXY_DOWN_MSG} (상세: {error.reason})") from error
+
+
+def search_order_plans(query: dict[str, str], *, base_url: str | None = None,
+                       read_json: Any = read_json_response) -> dict[str, Any]:
+    resolved_base = resolve_proxy_base_url(base_url)
+    url = f"{resolved_base}{ROUTE}?{urllib.parse.urlencode(query)}"
+    request = urllib.request.Request(url, headers={"Accept": "application/json", "User-Agent": USER_AGENT})
+    return read_json(request)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="나라장터 발주계획현황 조회 (k-skill-proxy 경유)")
+    parser.add_argument("--kind", default="goods", help="goods/물품, construction/공사, service/용역, foreign/외자, all/전체")
+    parser.add_argument("--keyword", "-q", help="사업명 검색어(bizNm)")
+    parser.add_argument("--order-from", help="발주시작년월 YYYY-MM 또는 YYYYMM")
+    parser.add_argument("--order-to", help="발주종료년월 YYYY-MM 또는 YYYYMM")
+    parser.add_argument("--posted-from", help="게시 시작일 YYYY-MM-DD 또는 YYYYMMDD[HHMM]")
+    parser.add_argument("--posted-to", help="게시 종료일 YYYY-MM-DD 또는 YYYYMMDD[HHMM]")
+    parser.add_argument("--institution", help="발주기관명")
+    parser.add_argument("--institution-code", help="발주기관코드")
+    parser.add_argument("--region", help="기관소재지명")
+    parser.add_argument("--procurement-method", help="조달방식")
+    parser.add_argument("--product-code", help="세부품명번호(물품)")
+    parser.add_argument("--business-type", help="업무유형명/업무유형코드(공사/용역/외자)")
+    parser.add_argument("--construction-type", help="공종구분명(공사)")
+    parser.add_argument("--page", type=int, default=1)
+    parser.add_argument("--limit", type=int, default=10)
+    parser.add_argument("--proxy-base-url", help=f"override {PROXY_BASE_URL_ENV_VAR}")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        result = search_order_plans(build_query(args), base_url=args.proxy_base_url)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    except (ApiError, ValueError) as error:
+        print(json.dumps({"error": error.__class__.__name__, "message": str(error)}, ensure_ascii=False), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/g2b-order-plan-search/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "g2b-order-plan-search",
+  "description": "조달청 나라장터 발주계획현황서비스로 물품·공사·용역·외자 발주계획 목록을 검색한다. 돌쇠에서는 가능한 가장 가까운 합법적 공식 단계까지 준비한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "hard-boundary"
+  ],
+  "frontmatter": "name: g2b-order-plan-search\ndescription: 조달청 나라장터 발주계획현황서비스로 물품·공사·용역·외자 발주계획 목록을 검색한다. 돌쇠에서는 가능한 가장 가까운 합법적 공식 단계까지 준비한다.\nlicense: MIT\nmetadata:\n  category: business\n  locale: ko-KR\n  phase: v1"
+}

package/skills/g2b-sanctioned-supplier/instruction.md

@@ -0,0 +1,61 @@
+# 나라장터 부정당제재업체정보 조회
+
+## What this skill does
+
+공공데이터포털의 **조달청 나라장터 사용자정보 서비스**(data.go.kr 15129466, `getUnptRsttCorpInfo02`)를 `k-skill-proxy` 경유로 호출해, 사업자등록번호 정확 일치(`inqryDiv=1`)로 **조회시점 현재 유효한** 부정당제재를 조회한다.
+
+- 반환: 제재 시작/종료일자, 제재기관명, 계약법구분, 제재근거법률 등 upstream 필드 원문
+
+## Coverage boundary
+
+upstream 명세상 다음은 **제공되지 않는다** — 과거 이력 조회가 아니다.
+
+- 조회시점에 제재만료·해제된 건
+- 나라장터 미등록업체·개인에 대한 제재
+
+만료 이력까지 보려면 나라장터(<https://www.g2b.go.kr>)에서 수동 확인이 필요하다.
+
+## Design principles
+
+- 점수·등급·해석 라벨을 만들지 않는다. upstream 사실 + 출처 + 적용범위 한계만 담는다.
+
+## When to use
+
+- "이 회사 입찰 제재(부정당제재) 이력 있어?"
+- "거래/계약 전에 부정당업자 제재 여부 확인해줘"
+
+## Prerequisites
+
+- 인터넷 연결, `python3`
+- `scripts/g2b_sanctioned_supplier.py` helper
+- hosted/self-host `k-skill-proxy`의 `/v1/g2b/sanctioned-supplier` route 접근 가능
+
+## Credential requirements
+
+- 사용자 측 필수 시크릿 없음.
+- `KSKILL_PROXY_BASE_URL` — self-host 프록시를 쓸 때만 설정. 비우면 hosted `https://k-skill-proxy.nomadamas.org` 사용.
+- `DATA_GO_KR_API_KEY` 는 프록시 운영 서버 환경에만 둔다. 공공데이터포털에서 `조달청_나라장터 사용자정보 서비스`(부정당제재업체정보조회 포함) 활용신청이 되어 있어야 한다.
+
+## Inputs
+
+- `--bizno`: 사업자등록번호 10자리(하이픈 허용) — 필수
+
+## CLI examples
+
+```bash
+python3 g2b-sanctioned-supplier/scripts/g2b_sanctioned_supplier.py --bizno 124-81-00998
+```
+
+## Failure modes
+
+- `400 bad_request`: 사업자번호가 10자리가 아님.
+- `503 upstream_not_configured`: 프록시 서버에 `DATA_GO_KR_API_KEY` 없음.
+- `502 upstream_forbidden`: 프록시 키가 15129466에 활용신청되지 않음.
+- `total_count = 0`: 조회시점 현재 유효한 제재 없음 (만료·미등록업체는 미제공임에 유의).
+
+## Official surfaces
+
+- 공공데이터포털: <https://www.data.go.kr/data/15129466/openapi.do>
+- upstream: `https://apis.data.go.kr/1230000/ao/UsrInfoService02/getUnptRsttCorpInfo02`
+- 수동 대조: 나라장터 <https://www.g2b.go.kr>
+- 프록시 route: `GET /v1/g2b/sanctioned-supplier`

package/skills/g2b-sanctioned-supplier/scripts/g2b_sanctioned_supplier.py

@@ -0,0 +1,114 @@
+"""Procurement (나라장터) sanctioned-supplier lookup via k-skill-proxy.
+
+The proxy holds DATA_GO_KR_API_KEY server-side; this helper only builds the
+query and reads the structured response. No user secret is required.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+PROXY_BASE_URL_ENV_VAR = "KSKILL_PROXY_BASE_URL"
+DEFAULT_PROXY_BASE_URL = "https://k-skill-proxy.nomadamas.org"
+PROXY_DOWN_MSG = "설정된 k-skill-proxy 서버가 응답하지 않습니다. 잠시 후 재시도하거나 운영자에게 문의하세요."
+PROXY_KEY_NOT_CONFIGURED_MSG = "k-skill-proxy에 필요한 API 키가 설정되어 있지 않습니다. 운영자에게 문의하세요."
+ROUTE = "/v1/g2b/sanctioned-supplier"
+
+
+class ApiError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+def _text_or_none(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def resolve_proxy_base_url(explicit: str | None = None, env: dict[str, str] | None = None) -> str:
+    env = os.environ if env is None else env
+    candidate = _text_or_none(explicit or env.get(PROXY_BASE_URL_ENV_VAR))
+    if candidate and candidate.casefold() in {"off", "false", "0", "disable", "disabled", "none"}:
+        raise ValueError("KSKILL_PROXY_BASE_URL 가 비활성화되어 있습니다.")
+    if candidate and candidate != "replace-me":
+        return candidate.rstrip("/")
+    return DEFAULT_PROXY_BASE_URL
+
+
+def normalize_bizno(value: Any) -> str:
+    raw = _text_or_none(value)
+    if not raw:
+        raise ValueError("사업자등록번호(bizno)를 입력하세요.")
+    normalized = re.sub(r"\D", "", raw)
+    if not re.fullmatch(r"\d{10}", normalized):
+        raise ValueError("사업자등록번호는 숫자 10자리여야 합니다.")
+    return normalized
+
+
+def read_json_response(request: urllib.request.Request) -> dict[str, Any]:
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            try:
+                payload = json.loads(response.read().decode("utf-8"))
+            except json.JSONDecodeError as error:
+                raise ApiError("g2b sanction proxy returned invalid JSON.") from error
+            if not isinstance(payload, dict):
+                raise ApiError("g2b sanction proxy returned a non-object JSON payload.")
+            return payload
+    except urllib.error.HTTPError as error:
+        body = error.read().decode("utf-8", errors="replace")
+        try:
+            payload = json.loads(body)
+        except json.JSONDecodeError:
+            payload = None
+        if error.code == 503 and isinstance(payload, dict) and payload.get("error") == "upstream_not_configured":
+            raise ApiError(PROXY_KEY_NOT_CONFIGURED_MSG, status_code=error.code) from error
+        if isinstance(payload, dict) and payload.get("message"):
+            raise ApiError(str(payload["message"]), status_code=error.code) from error
+        raise ApiError(f"g2b sanction proxy request failed with HTTP {error.code}", status_code=error.code) from error
+    except urllib.error.URLError as error:
+        raise ApiError(f"{PROXY_DOWN_MSG} (상세: {error.reason})") from error
+
+
+def query_sanctions(bizno: str, *, base_url: str | None = None,
+                    read_json: Any = read_json_response) -> dict[str, Any]:
+    normalized = normalize_bizno(bizno)
+    url = f"{resolve_proxy_base_url(base_url)}{ROUTE}?{urllib.parse.urlencode({'bizno': normalized})}"
+    request = urllib.request.Request(url, headers={
+        "Accept": "application/json",
+        "User-Agent": "k-skill-g2b-sanctioned-supplier/1.0",
+    }, method="GET")
+    return read_json(request)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="나라장터 부정당제재업체정보 조회 (k-skill-proxy 경유)")
+    parser.add_argument("--bizno", required=True, help="사업자등록번호 10자리(하이픈 허용)")
+    parser.add_argument("--proxy-base-url")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        result = query_sanctions(args.bizno, base_url=args.proxy_base_url)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    except (ValueError, ApiError) as error:
+        print(json.dumps({"error": str(error)}, ensure_ascii=False, indent=2), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/g2b-sanctioned-supplier/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "g2b-sanctioned-supplier",
+  "description": "조달청 나라장터 부정당제재업체정보를 공공데이터포털 API(k-skill-proxy 경유)로 조회한다. 사업자등록번호 정확 일치로 조회시점 현재 유효한 입찰참가자격 제한(부정당제재)의 기간·제재기관·근거법률을 확인한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: g2b-sanctioned-supplier\ndescription: 조달청 나라장터 부정당제재업체정보를 공공데이터포털 API(k-skill-proxy 경유)로 조회한다. 사업자등록번호 정확 일치로 조회시점 현재 유효한 입찰참가자격 제한(부정당제재)의 기간·제재기관·근거법률을 확인한다.\nlicense: MIT\nmetadata:\n  category: business\n  locale: ko-KR\n  phase: v1"
+}