@nomadamas/k-skill 0.1.0

package/skills/myrealtrip-search/scripts/myrealtrip_mcp.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""마이리얼트립 공개 Streamable HTTP MCP 서버를 호출한다.
+
+엔드포인트는 https://docs.myrealtrip.com/#/api/mcp/overview 에 문서화되어
+있으며 현재 별도 API 키가 필요하지 않다. 이 래퍼는 k-skill 사용자가
+단순 조회와 도구 호출을 위해 MCP 클라이언트 코드를 직접 작성하지 않아도
+되게 해준다.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from typing import Any, Sequence
+
+DEFAULT_ENDPOINT = "https://mcp-servers.myrealtrip.com/mcp"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+
+class MyRealTripMcpError(RuntimeError):
+    """설정 또는 MCP 호출 실패 때 발생한다."""
+
+
+def parse_json_object(raw: str, *, arg_name: str) -> dict[str, Any]:
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise argparse.ArgumentTypeError(f"{arg_name}은 올바른 JSON이어야 합니다: {exc}") from exc
+    if not isinstance(value, dict):
+        raise argparse.ArgumentTypeError(f"{arg_name}은 JSON 객체여야 합니다")
+    return value
+
+
+def parse_positive_float(raw: str) -> float:
+    try:
+        value = float(raw)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("timeout은 숫자여야 합니다") from exc
+    if value <= 0:
+        raise argparse.ArgumentTypeError("timeout은 0보다 커야 합니다")
+    return value
+
+
+def parse_kv_pairs(pairs: Sequence[str]) -> dict[str, Any]:
+    args: dict[str, Any] = {}
+    for pair in pairs:
+        if "=" not in pair:
+            raise argparse.ArgumentTypeError(f"인자 '{pair}'는 key=value 형식이어야 합니다")
+        key, raw_value = pair.split("=", 1)
+        if not key:
+            raise argparse.ArgumentTypeError(f"인자 '{pair}'의 key가 비어 있습니다")
+        try:
+            value = json.loads(raw_value)
+        except json.JSONDecodeError:
+            value = raw_value
+        args[key] = value
+    return args
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Streamable HTTP로 마이리얼트립 MCP 도구를 호출합니다.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "예시:\n"
+            "  myrealtrip_mcp.py tools\n"
+            "  myrealtrip_mcp.py call getCurrentTime\n"
+            "  myrealtrip_mcp.py call searchTnas --arg query='오사카 유니버설 스튜디오' --arg perPage=5\n"
+            "  myrealtrip_mcp.py call searchDomesticFlights --json '{\"origin\":\"GMP\",\"destination\":\"CJU\",\"departDate\":\"2026-05-20\"}'\n"
+        ),
+    )
+    parser.add_argument(
+        "--endpoint",
+        default=os.getenv("MYREALTRIP_MCP_ENDPOINT", DEFAULT_ENDPOINT),
+        help="마이리얼트립 MCP 엔드포인트(기본값: %(default)s).",
+    )
+    parser.add_argument(
+        "--timeout-seconds",
+        type=parse_positive_float,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        help="MCP 연결/호출 전체 제한 시간(기본값: %(default)s초).",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser("tools", help="사용 가능한 MCP 도구와 입력 스키마를 JSON으로 출력합니다.")
+
+    call_parser = subparsers.add_parser("call", help="MCP 도구 하나를 호출하고 CallToolResult를 JSON으로 출력합니다.")
+    call_parser.add_argument("tool", help="도구명. 예: searchStays, searchTnas, searchDomesticFlights.")
+    call_parser.add_argument(
+        "--json",
+        dest="json_args",
+        type=lambda raw: parse_json_object(raw, arg_name="--json"),
+        default=None,
+        help="도구 인자를 JSON 객체로 전달합니다.",
+    )
+    call_parser.add_argument(
+        "--arg",
+        dest="kv_args",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="도구 인자입니다. VALUE는 가능하면 JSON으로 파싱하고, 아니면 문자열로 처리합니다. 반복 지정할 수 있습니다.",
+    )
+    return parser.parse_args(argv)
+
+
+async def _run_mcp_once(endpoint: str, command: str, tool: str | None, arguments: dict[str, Any] | None) -> Any:
+    try:
+        from mcp import ClientSession
+        from mcp.client.streamable_http import streamablehttp_client
+    except Exception as exc:  # pragma: no cover - environment dependent
+        raise MyRealTripMcpError(
+            "Python 패키지 'mcp'가 필요합니다. 다음 명령으로 설치하세요: python3 -m pip install mcp"
+        ) from exc
+
+    try:
+        async with streamablehttp_client(endpoint) as (read_stream, write_stream, _):
+            async with ClientSession(read_stream, write_stream) as session:
+                await session.initialize()
+                if command == "tools":
+                    result = await session.list_tools()
+                    return [
+                        {
+                            "name": item.name,
+                            "description": item.description,
+                            "inputSchema": item.inputSchema,
+                        }
+                        for item in result.tools
+                    ]
+                if command == "call" and tool:
+                    return await session.call_tool(tool, arguments or {})
+    except Exception as exc:
+        raise MyRealTripMcpError(f"마이리얼트립 MCP 엔드포인트 호출 실패 {endpoint}: {exc}") from exc
+
+    raise MyRealTripMcpError(f"지원하지 않는 명령입니다: {command}")
+
+
+async def run_mcp(
+    endpoint: str,
+    command: str,
+    tool: str | None = None,
+    arguments: dict[str, Any] | None = None,
+    *,
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+) -> Any:
+    try:
+        return await asyncio.wait_for(
+            _run_mcp_once(endpoint, command, tool, arguments),
+            timeout=timeout_seconds,
+        )
+    except TimeoutError as exc:
+        raise MyRealTripMcpError(
+            f"마이리얼트립 MCP 엔드포인트 호출 시간이 {timeout_seconds:g}초를 초과했습니다: {endpoint}"
+        ) from exc
+
+
+def jsonable(value: Any) -> Any:
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")
+    if hasattr(value, "dict"):
+        return value.dict()
+    return value
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = parse_args(argv)
+    tool_args: dict[str, Any] | None = None
+    if args.command == "call":
+        tool_args = dict(args.json_args or {})
+        tool_args.update(parse_kv_pairs(args.kv_args))
+
+    try:
+        result = asyncio.run(
+            run_mcp(
+                args.endpoint,
+                args.command,
+                getattr(args, "tool", None),
+                tool_args,
+                timeout_seconds=args.timeout_seconds,
+            )
+        )
+    except MyRealTripMcpError as exc:
+        print(f"myrealtrip_mcp.py: {exc}", file=sys.stderr)
+        return 2
+
+    print(json.dumps(jsonable(result), ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/myrealtrip-search/scripts/test_myrealtrip_mcp.py

@@ -0,0 +1,99 @@
+import argparse
+import asyncio
+import importlib.util
+import pathlib
+import unittest
+from unittest import mock
+
+MODULE_PATH = pathlib.Path(__file__).with_name("myrealtrip_mcp.py")
+spec = importlib.util.spec_from_file_location("myrealtrip_mcp", MODULE_PATH)
+myrealtrip_mcp = importlib.util.module_from_spec(spec)
+assert spec.loader is not None
+spec.loader.exec_module(myrealtrip_mcp)
+
+
+class ParseHelpersTest(unittest.TestCase):
+    def test_parse_json_object_requires_object(self):
+        self.assertEqual(myrealtrip_mcp.parse_json_object('{"gid": 123}', arg_name="--json"), {"gid": 123})
+
+        with self.assertRaises(argparse.ArgumentTypeError):
+            myrealtrip_mcp.parse_json_object('["not", "object"]', arg_name="--json")
+
+    def test_parse_kv_pairs_json_decodes_values_when_possible(self):
+        self.assertEqual(
+            myrealtrip_mcp.parse_kv_pairs(["query=오사카", "perPage=5", "directFlightOnly=true"]),
+            {"query": "오사카", "perPage": 5, "directFlightOnly": True},
+        )
+
+    def test_parse_kv_pairs_rejects_malformed_pairs(self):
+        with self.assertRaises(argparse.ArgumentTypeError):
+            myrealtrip_mcp.parse_kv_pairs(["missing_separator"])
+
+        with self.assertRaises(argparse.ArgumentTypeError):
+            myrealtrip_mcp.parse_kv_pairs(["=empty_key"])
+
+    def test_timeout_must_be_positive_number(self):
+        self.assertEqual(myrealtrip_mcp.parse_positive_float("1.5"), 1.5)
+
+        for raw in ["0", "-1", "not-a-number"]:
+            with self.subTest(raw=raw):
+                with self.assertRaises(argparse.ArgumentTypeError):
+                    myrealtrip_mcp.parse_positive_float(raw)
+
+
+class CliAssemblyTest(unittest.TestCase):
+    def test_json_and_arg_inputs_are_merged_before_call(self):
+        captured = {}
+
+        async def fake_run_mcp(endpoint, command, tool=None, arguments=None, *, timeout_seconds):
+            captured.update(
+                endpoint=endpoint,
+                command=command,
+                tool=tool,
+                arguments=arguments,
+                timeout_seconds=timeout_seconds,
+            )
+            return {"ok": True}
+
+        with mock.patch.object(myrealtrip_mcp, "run_mcp", side_effect=fake_run_mcp):
+            exit_code = myrealtrip_mcp.main(
+                [
+                    "--endpoint",
+                    "https://example.invalid/mcp",
+                    "--timeout-seconds",
+                    "2.5",
+                    "call",
+                    "searchTnas",
+                    "--json",
+                    '{"query":"오사카","perPage":3}',
+                    "--arg",
+                    "perPage=5",
+                ]
+            )
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(captured["endpoint"], "https://example.invalid/mcp")
+        self.assertEqual(captured["command"], "call")
+        self.assertEqual(captured["tool"], "searchTnas")
+        self.assertEqual(captured["arguments"], {"query": "오사카", "perPage": 5})
+        self.assertEqual(captured["timeout_seconds"], 2.5)
+
+
+class TimeoutTest(unittest.TestCase):
+    def test_run_mcp_reports_timeout(self):
+        async def never_finishes(*args, **kwargs):
+            await asyncio.sleep(60)
+
+        with mock.patch.object(myrealtrip_mcp, "_run_mcp_once", side_effect=never_finishes):
+            with self.assertRaisesRegex(myrealtrip_mcp.MyRealTripMcpError, "초과"):
+                asyncio.run(
+                    myrealtrip_mcp.run_mcp(
+                        "https://example.invalid/mcp",
+                        "tools",
+                        timeout_seconds=0.001,
+                    )
+                )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/myrealtrip-search/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "myrealtrip-search",
+  "description": "마이리얼트립 공식 Streamable HTTP MCP 서버로 항공권, 숙소, 투어/티켓/액티비티를 검색하고 상세·가격·예약 링크를 확인한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "browser",
+    "action:booking"
+  ],
+  "frontmatter": "name: myrealtrip-search\ndescription: 마이리얼트립 공식 Streamable HTTP MCP 서버로 항공권, 숙소, 투어/티켓/액티비티를 검색하고 상세·가격·예약 링크를 확인한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: travel\n  locale: ko-KR\n  phase: v1"
+}

package/skills/naming-house/instruction.md

@@ -0,0 +1,146 @@
+# Naming House
+
+## What this skill does
+
+`naming-house` npm package로 생년월일시 기반 사주 오행, 한자/한글 획수, 발음 흐름, 사용자 선호를 함께 보아 한국 이름 후보를 추천·채점한다. 사주 계산은 기존 `saju-fortune` package의 공개 `analyzeSaju` 결과를 사용하고, 이름 쪽 획수·오행 보조 계산은 `namefyi`와 `korean-stroke`를 로컬에서 호출한다.
+
+이 스킬은 작명 결과를 확정 운명이나 법적 이름 검증으로 제시하지 않는다. 후보별 점수, 근거, 한계를 투명하게 보여 주는 성명학 참고 워크플로우다.
+
+## When to use
+
+- "아이 이름 추천해줘"
+- "사주에 맞는 이름 후보를 골라줘"
+- "성명학으로 이 이름들이 어떤지 비교해줘"
+- "한자 이름 후보의 획수와 오행 흐름을 보고 싶어"
+
+## When not to use
+
+- 법적으로 사용 가능한 인명용 한자인지 확정해야 하는 경우
+- 사망, 질병, 불행, 성공 같은 운명을 단정해야 하는 경우
+- 생년월일시·성씨·후보 이름 없이 일반적인 예쁜 이름만 원하는 경우
+- 전문 작명가·법률·행정 판단을 대체해야 하는 경우
+
+## Prerequisites
+
+- Node.js 18+
+- 배포 후: `npm install -g naming-house`
+- 실행 전: `export NODE_PATH="$(npm root -g)"`
+- 이 저장소에서 개발할 때: 루트에서 `npm install`
+
+## Required interview inputs
+
+1. 성씨(한글)와 가능하면 성 한자
+2. 양력/음력 여부
+3. 생년월일 (`YYYY-MM-DD`)
+4. 태어난 시간 (`HH:mm`, 모르면 모른다고 기록하고 한계를 설명)
+5. 성별 (`male` 또는 `female`으로 package 호출)
+6. 출생 시군구(선택)
+7. 후보 이름 목록(한글 이름 필수, 한자 이름 선택)
+8. 선호 음절, 피하고 싶은 음절, 이름 스타일(선택)
+
+음력 생일이면 이 패키지 안에서 변환하지 않는다. 검증된 만세력으로 양력 생년월일을 먼저 확인한 뒤 `calendar: "solar"`로 호출한다.
+
+## Workflow
+
+### 1. Interview first
+
+정보가 부족하면 바로 작명하지 말고 필요한 값을 짧게 묻는다.
+
+```text
+작명을 위해 성씨, 양력 생년월일, 태어난 시간, 성별, 후보 이름을 알려주세요. 한자 후보가 있으면 함께 주시면 획수·오행 분석 정확도가 올라갑니다.
+```
+
+태어난 시간을 모르면:
+
+```text
+태어난 시간을 모르면 시주 기반 보완 오행은 확정하지 못해요. 연·월·일 중심의 보수적 추천으로 진행하고 한계를 함께 표시할게요.
+```
+
+### 2. Install package when missing
+
+`node -e 'require("naming-house")'`가 실패하면 웹 스크래핑이나 MCP 서버 실행으로 우회하지 말고 package 설치를 먼저 시도한다.
+
+```bash
+npm install -g naming-house
+export NODE_PATH="$(npm root -g)"
+```
+
+### 3. Recommend from candidates
+
+```bash
+NODE_PATH="$(npm root -g)" node - <<'JS'
+const { recommendNames } = require("naming-house")
+
+recommendNames({
+  surname: "김",
+  surnameHanja: "金",
+  birthDate: "2024-05-18",
+  birthTime: "09:20",
+  calendar: "solar",
+  gender: "female",
+  birthCity: "서울",
+  preferences: { style: "modern", maxCandidates: 10 },
+  candidates: [
+    { givenName: "서아", hanjaName: "瑞雅", tags: ["modern"] },
+    { givenName: "하린", hanjaName: "河潾" },
+    { givenName: "지유" }
+  ]
+}).then((result) => console.log(JSON.stringify(result, null, 2)))
+JS
+```
+
+### 4. Score one candidate
+
+```bash
+NODE_PATH="$(npm root -g)" node - <<'JS'
+const { callNamingHouseTool } = require("naming-house")
+
+callNamingHouseTool("score_name", {
+  input: {
+    surname: "박",
+    surnameHanja: "朴",
+    birthDate: "2024-05-18",
+    birthTime: "09:20",
+    calendar: "solar",
+    gender: "male",
+    candidates: [{ givenName: "서준", hanjaName: "瑞俊" }]
+  },
+  candidate: { givenName: "서준", hanjaName: "瑞俊" }
+}).then((result) => console.log(JSON.stringify(result, null, 2)))
+JS
+```
+
+### 5. Interpret results
+
+응답은 아래 구조를 따른다.
+
+1. 입력 정보와 정확도 한계: 음력 변환 여부, 태어난 시간, 한자 누락 여부를 확인한다.
+2. 사주 오행 요약: 부족/보완 오행과 일간 중심을 짧게 설명한다.
+3. 후보별 점수: 총점, 등급, `elementBalance`, `strokeHarmony`, `soundFlow`, `preferenceFit`를 보여 준다.
+4. 성명학 풀이: 한자 획수 또는 한글 fallback, 오행 상생/상극, 발음 흐름을 설명한다.
+5. 추천 순서: 점수가 높은 순서대로 장점과 주의점을 함께 적는다.
+6. 주의 문구: 성명학은 문화적 참고이며 법적 개명·인명용 한자 검증·운명 판단을 대신하지 않는다고 말한다.
+
+## Done when
+
+- 필요한 출생 정보와 이름 후보를 인터뷰로 확인했다.
+- `naming-house` package 결과 JSON을 근거로 점수와 순위를 설명했다.
+- 사주 보완 오행, 획수 조화, 발음 흐름, 선호 반영을 분리해 설명했다.
+- 음력, 태어난 시간 미상, 한자 누락, 한자 획수 불가 같은 한계를 명시했다.
+- MCP 서버, proxy, 웹 스크래핑을 실행하지 않았다.
+
+## Failure modes
+
+- package가 설치되지 않았고 네트워크도 없으면 설치 실패를 설명하고 진행하지 않는다.
+- 음력 또는 윤달 생일은 내장 계산으로 변환하지 않는다.
+- 태어난 시간이 없으면 시주와 시주 기반 해석은 확정할 수 없다.
+- 한자 이름이 없으면 `korean-stroke` 기반 한글 획수 fallback으로 채점하며 정확도가 낮다고 표시한다.
+- 한자 획수나 오행을 확인하지 못하면 해당 후보의 한자 수리 해석을 확정하지 않는다.
+- 후보 이름이 없으면 임의·무작위 생성 대신 선호 조건을 더 물어본다.
+
+## Notes
+
+- 입력한 생년월일시와 이름 후보는 풀이 중에만 사용하고 영구 저장하지 않는다.
+- 성명학 점수는 참고용이며 의료, 투자, 법률, 행정, 가족 의사결정을 대신하지 않는다.
+- 불안감을 키우는 흉언, 저주, 사망 예언, 질병 확정 표현은 하지 않는다.
+- v1은 공식 인명용 한자 적합성, 불용문자, 법원 개명 가능성을 보증하지 않는다.

package/skills/naming-house/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "naming-house",
+  "description": "생년월일시와 성씨·후보 이름을 바탕으로 사주 오행과 성명학 점수를 참고해 어울리는 한국 이름을 추천한다.",
+  "profiles": [
+    "local"
+  ],
+  "frontmatter": "name: naming-house\ndescription: 생년월일시와 성씨·후보 이름을 바탕으로 사주 오행과 성명학 점수를 참고해 어울리는 한국 이름을 추천한다.\nlicense: MIT\nmetadata:\n  category: utility\n  locale: ko-KR\n  phase: v1"
+}

package/skills/national-pension-workplace/instruction.md

@@ -0,0 +1,64 @@
+# 국민연금 가입 사업장 내역 조회
+
+## What this skill does
+
+공공데이터포털의 **국민연금공단_국민연금 가입 사업장 내역 서비스**(data.go.kr 3046071, V2)를 `k-skill-proxy` 경유로 호출해 다음을 조회한다.
+
+- 가입 사업장 후보: 사업장명 + 사업자번호 앞 6자리로 매칭된 사업장 목록 (자료생성년월별 중복은 사업장당 최신 월로 정리)
+- 단일 사업장이 특정되면 상세: 가입자수(`jnngpCnt`), 당월 고지금액(`crrmmNtcAmt`), 신규취득/상실 인원
+- 월별 가입 현황 시계열
+
+사업자등록번호는 **앞 6자리만 공개**(뒷자리 마스킹)되므로 사업장명이 필수이며, 후보가 여럿이면 특정하지 않고 목록 그대로 돌려준다.
+
+## Design principles
+
+- 점수·등급·"위험" 같은 해석 라벨을 만들지 않는다. upstream이 돌려준 사실만 담는다.
+- 후보가 여럿이면 동일성을 단정하지 않는다.
+
+## When to use
+
+- "○○ 회사 직원 규모가 얼마나 돼? 국민연금 가입자수로 보자"
+- "이 사업장 당월 국민연금 고지금액이 얼마야?"
+- "최근 인원이 늘었는지 줄었는지 월별로 보자"
+
+## Prerequisites
+
+- 인터넷 연결, `python3`
+- `scripts/national_pension_workplace.py` helper
+- hosted/self-host `k-skill-proxy`의 `/v1/national-pension/workplace` route 접근 가능
+
+## Credential requirements
+
+- 사용자 측 필수 시크릿 없음.
+- `KSKILL_PROXY_BASE_URL` — self-host 프록시를 쓸 때만 설정. 비우면 hosted `https://k-skill-proxy.nomadamas.org` 사용.
+- `DATA_GO_KR_API_KEY` 는 프록시 운영 서버 환경에만 둔다. 공공데이터포털에서 `국민연금공단_국민연금 가입 사업장 내역` 활용신청이 되어 있어야 한다.
+
+## Inputs
+
+- `--name`: 사업장명(상호) — 필수
+- `--b-no`: 사업자등록번호(하이픈 허용). 앞 6자리만 prefix 필터로 쓰인다.
+
+## Privacy boundary
+
+- 국민연금 데이터는 사업자번호 앞 6자리만 공개되므로, 6자리 일치 + 상호 유사 후보를 나열할 뿐 사업장 동일성을 단정하지 않는다.
+- 공개 범위는 법인·근로자 일정 규모 이상 사업장 위주이며, 소규모/개인 사업장은 미공개일 수 있다.
+
+## CLI examples
+
+```bash
+python3 national-pension-workplace/scripts/national_pension_workplace.py \
+  --name "삼성전자(주)" --b-no 124-81-00998
+```
+
+## Failure modes
+
+- `400 bad_request`: 사업장명을 주지 않음.
+- `503 upstream_not_configured`: 프록시 서버에 `DATA_GO_KR_API_KEY` 없음.
+- `502 upstream_forbidden`: 프록시 키가 3046071에 활용신청되지 않음.
+- 후보 다수: `selected_candidate`가 `null` — 사용자가 후보 목록에서 특정한다.
+
+## Official surfaces
+
+- 공공데이터포털: <https://www.data.go.kr/data/3046071/openapi.do>
+- upstream: `https://apis.data.go.kr/B552015/NpsBplcInfoInqireServiceV2` (요청 파라미터 camelCase)
+- 프록시 route: `GET /v1/national-pension/workplace`

package/skills/national-pension-workplace/scripts/national_pension_workplace.py

@@ -0,0 +1,113 @@
+"""National Pension Service workplace-coverage 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/national-pension/workplace"
+
+
+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("national-pension proxy returned invalid JSON.") from error
+            if not isinstance(payload, dict):
+                raise ApiError("national-pension 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"national-pension 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_workplace(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("사업장명(상호)을 입력하세요. 국민연금 API는 사업자번호 앞 6자리만 공개해 상호가 필수입니다.")
+    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-national-pension-workplace/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="사업장명(상호) — 필수")
+    parser.add_argument("--b-no", help="사업자등록번호(앞 6자리만 prefix 필터로 사용)")
+    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_workplace(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/national-pension-workplace/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "national-pension-workplace",
+  "description": "국민연금공단 국민연금 가입 사업장 내역을 공공데이터포털 API(k-skill-proxy 경유)로 조회한다. 사업장명으로 가입자수·당월 고지금액·월별 취득/상실 추이를 확인해 그 회사의 직원 규모와 변화를 본다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: national-pension-workplace\ndescription: 국민연금공단 국민연금 가입 사업장 내역을 공공데이터포털 API(k-skill-proxy 경유)로 조회한다. 사업장명으로 가입자수·당월 고지금액·월별 취득/상실 추이를 확인해 그 회사의 직원 규모와 변화를 본다.\nlicense: MIT\nmetadata:\n  category: business\n  locale: ko-KR\n  phase: v1"
+}