@nomadamas/k-skill 0.1.0

package/skills/korean-jangbu-for/instruction.md

@@ -0,0 +1,133 @@
+# Korean Jangbu For (thin wrapper)
+
+## What this skill does
+
+[`kimlawtech/korean-jangbu-for`](https://github.com/kimlawtech/korean-jangbu-for) (Apache-2.0) 업스트림을 중심으로 한국 사업자 장부 자동화 흐름을 안내한다. 원저작자·관리자는 **[@kimlawtech](https://github.com/kimlawtech) (SpeciAI)** 이며, k-skill 측은 원본 발견·설치 진입점·출처/면책 고지·agent-neutral 사용 절차만 유지하는 **얇은 wrapper** 다.
+
+업스트림은 카드명세서 PDF, 은행 CSV, 엑셀 장부, 영수증/세금계산서 이미지·PDF를 표준 거래내역으로 정리하고, 계정과목 매핑, 세무용 BS/PL, 경영용 현금흐름·cash burn 리포트, 세무사 전달 CSV 생성을 목표로 한다.
+
+**중요:** 이 스킬을 사용할 때 모든 답변에는 원본 링크 `https://github.com/kimlawtech/korean-jangbu-for` 와 원저작자 **@kimlawtech (SpeciAI)** 를 반드시 멘션한다.
+
+## When to use
+
+- "사업자 장부 자동화해줘"
+- "카드 명세서 PDF를 장부로 바꿔줘"
+- "은행 CSV랑 영수증으로 세무사 전달 자료 만들어줘"
+- "개인사업자/프리랜서 종소세 준비 체크리스트 만들어줘"
+- "장부 데이터를 계정과목으로 분류하고 경영 리포트 만들어줘"
+- "CODEF 키로 홈택스·은행·카드 내역 자동 수집 설정하고 싶어"
+
+## When not to use
+
+- 공식 회계감사, 세무신고 대행, 기장대리, 절세 자문 자체를 요청하는 경우 → 세무사/공인회계사 상담을 안내한다.
+- 사용자가 자격증명 입력, 간편인증, 금융기관 로그인 등 side-effect 를 명시적으로 승인하지 않은 상태.
+- 정식 외부 제출용 재무제표·공시자료를 자동 산출물만으로 확정하려는 경우.
+- 한국 사업자 장부가 아닌 해외 회계 기준(IFRS/US GAAP 등) 중심 작업.
+
+## Prerequisites
+
+- 인터넷 연결 (업스트림 clone 용)
+- `git` 2.20+
+- `bash`
+- Python 3.11+
+- macOS 또는 Linux
+- OCR/PDF 처리를 위한 업스트림 의존성 (install.sh 가 안내/설치)
+- 자동 수집을 쓰는 경우: 사용자가 직접 발급한 CODEF Client ID/Secret (**BYOK**)
+
+## Install (dual-install)
+
+업스트림을 `~/.claude/skills/korean-jangbu-for/upstream/` 와 `~/.agents/skills/korean-jangbu-for/upstream/` 양쪽에 pinned SHA 로 체크아웃한다. 또한 업스트림 `skills/jangbu-*` 를 양쪽 홈 디렉터리의 top-level skill 로 등록해 `/jangbu-connect`, `/jangbu-import`, `/jangbu-tag`, `/jangbu-tax`, `/jangbu-dash`, `/jangbu-jongso` 라우팅이 agent-compatible 런타임에서도 발견되게 한다. `/korean-jangbu-for` 는 이 wrapper 의 top-level skill 로 유지한다. 레포 내부에는 업스트림 payload 를 커밋하지 않는다.
+
+홈 디렉터리 wrapper 에는 `SKILL.md`, `scripts/install.sh`, `scripts/upstream.pin`, `LICENSE.upstream`, `DISCLAIMER.md`, `NOTICE` 를 함께 설치한다. Promoted `jangbu-*` top-level 경로에 사용자가 만든 다른 스킬이 이미 있으면 installer 는 덮어쓰지 않고 중단한다. wrapper 가 이전에 설치한 managed 스킬만 자동 갱신하며, 의도적으로 교체해야 할 때만 `KOREAN_JANGBU_FOR_OVERWRITE_SKILLS=1` 을 설정한다.
+
+```bash
+bash korean-jangbu-for/scripts/install.sh
+```
+
+레포를 로컬에 clone 하지 않고 이미 홈 디렉토리 스킬 번들만 가진 상태에서도 설치할 수 있다:
+
+```bash
+bash ~/.claude/skills/korean-jangbu-for/scripts/install.sh
+# 또는
+bash ~/.agents/skills/korean-jangbu-for/scripts/install.sh
+```
+
+설치 확인:
+
+```bash
+cat korean-jangbu-for/scripts/upstream.pin
+git -C ~/.claude/skills/korean-jangbu-for/upstream rev-parse HEAD
+git -C ~/.agents/skills/korean-jangbu-for/upstream rev-parse HEAD
+```
+
+세 SHA 가 모두 같으면 wrapper 설치가 성공한 것이다. 업스트림 런타임 의존성까지 검증해야 할 때만 아래를 이어서 실행한다. 업스트림 `scripts/install.sh` 는 Claude Code 스킬 symlink 를 등록하므로, k-skill wrapper 개발 중이면 실행 후 wrapper 디렉토리를 다시 sync 한다.
+
+```bash
+bash ~/.claude/skills/korean-jangbu-for/upstream/scripts/install.sh
+bash ~/.claude/skills/korean-jangbu-for/upstream/scripts/verify.sh
+```
+
+오프라인 환경에서는 upstream clone 이 실패하므로 실행할 수 없다.
+
+## Mandatory intake first
+
+사용자가 장부 자동화나 세무사 전달 자료 생성을 요청하면 바로 파일을 만들지 말고 먼저 아래를 확인한다. 한 번에 1~3문항씩, 사용자가 모르면 "넘어가도 됩니다" 로 열어 둔다.
+
+- 사업자 유형: 개인사업자 / 법인 / 프리랜서 / 복수 사업장
+- 목표 산출물: 표준 거래내역 / 계정과목 분류 / 세무사 전달 CSV / BS·PL / 현금흐름·경영 리포트 / 종소세 체크리스트
+- 입력 자료: 은행 CSV, 카드 PDF, 엑셀, 영수증 이미지, 세금계산서 PDF, 홈택스·은행·카드 자동 수집(CODEF)
+- 기간과 통화: 대상 월/분기/연도, KRW 외 통화 여부
+- 민감정보 처리: 원본 보관 위치, 마스킹 필요 수준, 외부 LLM 경유 허용 여부
+- 자동 수집 사용 여부: CODEF BYOK 준비 여부, 인증/로그인/간편인증은 사용자가 직접 승인해야 함
+- 공식 제출 예정 여부: 세무사 검토 / 공인회계사 감사 필요성을 함께 확인
+
+## Workflow
+
+1. 위 intake 로 목표와 입력 자료를 확정한다.
+2. `bash korean-jangbu-for/scripts/install.sh` 로 업스트림을 dual-install 한다.
+3. 사용 목적에 맞게 업스트림 스킬을 선택한다:
+   - `/korean-jangbu-for` — 전체 메뉴 라우팅
+   - `/jangbu-connect` — CODEF API 자격증명 설정(BYOK, 홈택스·은행·카드 자동 수집)
+   - `/jangbu-import` — 원본 데이터(엑셀·CSV·이미지·PDF) → 표준 거래내역
+   - `/jangbu-tag` — 표준 거래내역 → 계정과목 매핑
+   - `/jangbu-tax` — 세무용 BS·PL / 세무사 전달 CSV
+   - `/jangbu-dash` — 경영용 현금흐름·대시보드·카드별 분석
+   - `/jangbu-jongso` — 종합소득세 준비 체크리스트 및 홈택스 다운로드 경로 안내
+4. 민감정보는 업스트림의 Level 2 마스킹 원칙을 따른다. 사업자번호·주민번호·카드번호·계좌번호·account_id 는 토큰화/마스킹한 뒤 LLM fallback 에 전달한다.
+5. 자동 수집은 CODEF BYOK 원칙을 따른다. 자격증명은 macOS Keychain 또는 `~/.jangbu/credentials.env`(0o600) 같은 로컬 저장소에만 두며, 사용자의 명시 승인 없이 외부 인증·금융 조회를 실행하지 않는다.
+6. 완료 보고에는 아래 Response policy 의 고정 블록을 반드시 포함한다.
+
+## Response policy
+
+모든 답변 말미에 아래 정보를 포함한다.
+
+- 원본: https://github.com/kimlawtech/korean-jangbu-for
+- 원저작자: **@kimlawtech (SpeciAI)**
+- 라이선스: Apache-2.0 (`korean-jangbu-for/LICENSE.upstream`)
+- 생성된 장부·재무제표·경영 리포트·세무사 전달 CSV 는 **참고용 초안**이며, **공식 회계감사** 또는 **세무신고** 를 대체하지 않는다.
+- 법인세·종합소득세 신고 전 **세무사 검토** 가 필요하고, 외감 대상 법인은 **공인회계사 감사** 가 필요하다.
+
+## Done when
+
+- 목표 산출물, 입력 자료, 사업자 유형, 기간, 민감정보 처리 수준이 확인되었다.
+- `scripts/install.sh` 이 업스트림을 dual-install 했고 양쪽 `upstream/` 경로가 `scripts/upstream.pin` 과 같은 SHA 를 가리킨다.
+- 업스트림 `skills/jangbu-*` 가 `~/.claude/skills/<skill-name>` 및 `~/.agents/skills/<skill-name>` top-level 경로에 등록되어 slash skill discovery 가 가능하다.
+- 업스트림의 해당 하위 스킬(`/jangbu-import`, `/jangbu-tag`, `/jangbu-tax`, `/jangbu-dash`, `/jangbu-jongso`, `/jangbu-connect`) 흐름을 사용했다.
+- 사용자가 공식 제출/신고 목적이라고 밝힌 경우 세무사 검토 또는 공인회계사 감사 필요성을 명시했다.
+- 최종 답변에 원본 링크, 원저작자 @kimlawtech (SpeciAI), Apache-2.0, 회계·세무 면책 고지가 포함되었다.
+
+## Failure modes
+
+- 네트워크 차단: upstream clone/pin checkout 실패 → 네트워크 확보 후 `scripts/install.sh` 재실행.
+- Python/OCR 의존성 실패: 업스트림 `scripts/verify.sh` 출력 기준으로 Python 3.11+, poppler, Vision/PaddleOCR 환경을 점검.
+- CODEF 인증 실패: 사용자의 BYOK 자격증명과 간편인증 상태를 확인하되, 자격증명 값을 채팅에 노출하지 않는다.
+- OCR 오인식/분류 신뢰도 낮음: 원본 파일과 표준 거래내역을 사용자에게 검토시키고, 자동 확정하지 않는다.
+- 공식 제출이 필요한 경우: 자동 산출물을 최종본으로 단정하지 말고 세무사/공인회계사 검토 단계로 넘긴다.
+
+## Notes
+
+- upstream pin: `korean-jangbu-for/scripts/upstream.pin`
+- upstream disclaimer: `korean-jangbu-for/DISCLAIMER.md`
+- upstream license copy: `korean-jangbu-for/LICENSE.upstream`
+- attribution notice: `korean-jangbu-for/NOTICE`
+- k-skill 루트 `LICENSE` 는 이 저장소 wrapper 의 기본 라이선스이고, 이 스킬 하위 upstream 자료는 Apache-2.0 고지와 재배포 조건을 따른다.

package/skills/korean-jangbu-for/scripts/install.sh

@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+#
+# korean-jangbu-for upstream installer.
+#
+# k-skill 측은 얇은 wrapper 만 유지하고, 장부 자동화 구현은 업스트림
+# kimlawtech/korean-jangbu-for (Apache-2.0, @kimlawtech / SpeciAI) 에 위임한다.
+# 이 스크립트는 scripts/upstream.pin 에 기록된 커밋 SHA 를 두 홈 디렉토리
+# 스킬 경로 아래에 동일하게 체크아웃한다.
+#
+#   ~/.claude/skills/korean-jangbu-for/upstream/
+#   ~/.agents/skills/korean-jangbu-for/upstream/
+#
+# 사용법:
+#   bash korean-jangbu-for/scripts/install.sh
+
+set -euo pipefail
+
+UPSTREAM_REPO="${KOREAN_JANGBU_FOR_UPSTREAM_REPO:-https://github.com/kimlawtech/korean-jangbu-for.git}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WRAPPER_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+PIN_FILE="${SCRIPT_DIR}/upstream.pin"
+SKILL_NAME="korean-jangbu-for"
+MANAGED_MARKER="k-skill wrapper attribution and disclaimer"
+
+if [[ ! -f "${PIN_FILE}" ]]; then
+  echo "[korean-jangbu-for] upstream.pin not found at ${PIN_FILE}" >&2
+  exit 1
+fi
+
+UPSTREAM_SHA="${KOREAN_JANGBU_FOR_UPSTREAM_SHA:-$(tr -d '[:space:]' <"${PIN_FILE}")}"
+
+if [[ ! "${UPSTREAM_SHA}" =~ ^[0-9a-f]{40}$ ]]; then
+  echo "[korean-jangbu-for] upstream.pin must contain a 40-char git SHA (got: ${UPSTREAM_SHA})" >&2
+  exit 1
+fi
+
+CACHE_DIR="${HOME}/.cache/k-skill/${SKILL_NAME}"
+CLONE_DIR="${CACHE_DIR}/upstream"
+UPSTREAM_SUBSKILLS=(
+  "jangbu-connect"
+  "jangbu-dash"
+  "jangbu-import"
+  "jangbu-jongso"
+  "jangbu-tag"
+  "jangbu-tax"
+)
+
+sync_dir() {
+  local source_dir="$1"
+  local target_dir="$2"
+
+  if [[ -e "${target_dir}" || -L "${target_dir}" ]]; then
+    rm -rf "${target_dir}"
+  fi
+
+  if command -v rsync >/dev/null 2>&1; then
+    rsync -a --delete "${source_dir}/" "${target_dir}/"
+  else
+    cp -a "${source_dir}/" "${target_dir}/"
+  fi
+}
+
+copy_file_if_different() {
+  local source_file="$1"
+  local target_file="$2"
+
+  if [[ -e "${target_file}" ]] && [[ "$(cd "$(dirname "${source_file}")" && pwd -P)/$(basename "${source_file}")" == "$(cd "$(dirname "${target_file}")" && pwd -P)/$(basename "${target_file}")" ]]; then
+    return 0
+  fi
+
+  cp "${source_file}" "${target_file}"
+}
+
+install_wrapper_payload() {
+  local target_dir="$1"
+
+  mkdir -p "${target_dir}/scripts"
+  copy_file_if_different "${WRAPPER_DIR}/SKILL.md" "${target_dir}/SKILL.md"
+  copy_file_if_different "${WRAPPER_DIR}/LICENSE.upstream" "${target_dir}/LICENSE.upstream"
+  copy_file_if_different "${WRAPPER_DIR}/DISCLAIMER.md" "${target_dir}/DISCLAIMER.md"
+  copy_file_if_different "${WRAPPER_DIR}/NOTICE" "${target_dir}/NOTICE"
+  copy_file_if_different "${WRAPPER_DIR}/scripts/install.sh" "${target_dir}/scripts/install.sh"
+  copy_file_if_different "${WRAPPER_DIR}/scripts/upstream.pin" "${target_dir}/scripts/upstream.pin"
+  chmod +x "${target_dir}/scripts/install.sh"
+}
+
+is_managed_promoted_skill() {
+  local target_dir="$1"
+  local skill_file="${target_dir}/SKILL.md"
+
+  [[ -f "${skill_file}" ]] && grep -q "${MANAGED_MARKER}" "${skill_file}"
+}
+
+assert_promoted_skill_writable() {
+  local target_dir="$1"
+
+  if [[ -e "${target_dir}" || -L "${target_dir}" ]]; then
+    if [[ "${KOREAN_JANGBU_FOR_OVERWRITE_SKILLS:-}" != "1" ]] && ! is_managed_promoted_skill "${target_dir}"; then
+      echo "[korean-jangbu-for] refusing to overwrite unrelated skill: ${target_dir}" >&2
+      echo "  Set KOREAN_JANGBU_FOR_OVERWRITE_SKILLS=1 to replace this top-level skill." >&2
+      exit 1
+    fi
+  fi
+}
+
+sync_promoted_skill() {
+  local source_dir="$1"
+  local target_dir="$2"
+
+  assert_promoted_skill_writable "${target_dir}"
+  sync_dir "${source_dir}" "${target_dir}"
+}
+
+preflight_promoted_skill() {
+  local source_dir="$1"
+  local target_dir="$2"
+
+  if [[ ! -f "${source_dir}/SKILL.md" ]]; then
+    echo "[korean-jangbu-for] missing upstream skill: ${source_dir}/SKILL.md" >&2
+    exit 1
+  fi
+
+  assert_promoted_skill_writable "${target_dir}"
+}
+
+preflight_promoted_skills() {
+  local home_skill_dir
+  local home_skills_root
+  local upstream_skill
+  local upstream_skill_dir
+  local home_upstream_skill_dir
+
+  for home_skill_dir in "${HOME_DIRS[@]}"; do
+    home_skills_root="$(dirname "${home_skill_dir}")"
+
+    for upstream_skill in "${UPSTREAM_SUBSKILLS[@]}"; do
+      upstream_skill_dir="${CLONE_DIR}/skills/${upstream_skill}"
+      home_upstream_skill_dir="${home_skills_root}/${upstream_skill}"
+      preflight_promoted_skill "${upstream_skill_dir}" "${home_upstream_skill_dir}"
+    done
+  done
+}
+
+append_response_policy() {
+  local skill_file="$1"
+
+  cat >>"${skill_file}" <<'POLICY'
+
+## k-skill wrapper attribution and disclaimer
+
+This top-level skill is registered by the k-skill `korean-jangbu-for` thin wrapper so agent-compatible runtimes can discover the upstream `jangbu-*` workflows. Preserve the upstream workflow above, but every response that uses this skill must include:
+
+- 원본: https://github.com/kimlawtech/korean-jangbu-for
+- 원저작자: **@kimlawtech (SpeciAI)**
+- 라이선스: Apache-2.0 (`korean-jangbu-for/LICENSE.upstream`)
+- 생성된 장부·재무제표·경영 리포트·세무사 전달 CSV 는 **참고용 초안**이며, **공식 회계감사** 또는 **세무신고** 를 대체하지 않는다.
+- 법인세 신고 전에는 **세무사 검토** 가 필요하고, 외감 대상 법인은 **공인회계사 감사** 가 필요하다.
+POLICY
+}
+
+mkdir -p "${CACHE_DIR}"
+
+if [[ ! -d "${CLONE_DIR}/.git" ]]; then
+  echo "[korean-jangbu-for] cloning upstream into ${CLONE_DIR}"
+  if ! git clone --filter=blob:none "${UPSTREAM_REPO}" "${CLONE_DIR}" >&2; then
+    echo "" >&2
+    echo "[korean-jangbu-for] upstream clone failed (network required)." >&2
+    echo "  upstream: ${UPSTREAM_REPO}" >&2
+    echo "  오프라인 환경에서는 이 스킬의 장부 자동화 흐름을 실행할 수 없다." >&2
+    exit 1
+  fi
+fi
+
+echo "[korean-jangbu-for] syncing upstream to pinned SHA ${UPSTREAM_SHA}"
+git -C "${CLONE_DIR}" fetch --tags origin "${UPSTREAM_SHA}" >&2 || git -C "${CLONE_DIR}" fetch origin >&2
+git -C "${CLONE_DIR}" checkout --force --detach "${UPSTREAM_SHA}" >&2
+
+HEAD_SHA="$(git -C "${CLONE_DIR}" rev-parse HEAD)"
+
+if [[ "${HEAD_SHA}" != "${UPSTREAM_SHA}" ]]; then
+  echo "[korean-jangbu-for] HEAD (${HEAD_SHA}) does not match pinned SHA (${UPSTREAM_SHA})" >&2
+  exit 1
+fi
+
+HOME_DIRS=(
+  "${HOME}/.claude/skills/${SKILL_NAME}"
+  "${HOME}/.agents/skills/${SKILL_NAME}"
+)
+
+preflight_promoted_skills
+
+for HOME_SKILL_DIR in "${HOME_DIRS[@]}"; do
+  HOME_UPSTREAM="${HOME_SKILL_DIR}/upstream"
+  HOME_SKILLS_ROOT="$(dirname "${HOME_SKILL_DIR}")"
+  if [[ -L "${HOME_SKILL_DIR}" ]]; then
+    rm -f "${HOME_SKILL_DIR}"
+  fi
+  install_wrapper_payload "${HOME_SKILL_DIR}"
+
+  sync_dir "${CLONE_DIR}" "${HOME_UPSTREAM}"
+
+  INSTALLED_SHA="$(git -C "${HOME_UPSTREAM}" rev-parse HEAD)"
+
+  if [[ "${INSTALLED_SHA}" != "${UPSTREAM_SHA}" ]]; then
+    echo "[korean-jangbu-for] ${HOME_UPSTREAM} HEAD (${INSTALLED_SHA}) does not match pin (${UPSTREAM_SHA})" >&2
+    exit 1
+  fi
+
+  echo "[korean-jangbu-for] installed upstream@${UPSTREAM_SHA} -> ${HOME_UPSTREAM}"
+
+  for UPSTREAM_SKILL in "${UPSTREAM_SUBSKILLS[@]}"; do
+    UPSTREAM_SKILL_DIR="${CLONE_DIR}/skills/${UPSTREAM_SKILL}"
+    HOME_UPSTREAM_SKILL_DIR="${HOME_SKILLS_ROOT}/${UPSTREAM_SKILL}"
+
+    if [[ ! -f "${UPSTREAM_SKILL_DIR}/SKILL.md" ]]; then
+      echo "[korean-jangbu-for] missing upstream skill: ${UPSTREAM_SKILL_DIR}/SKILL.md" >&2
+      exit 1
+    fi
+
+    sync_promoted_skill "${UPSTREAM_SKILL_DIR}" "${HOME_UPSTREAM_SKILL_DIR}"
+    append_response_policy "${HOME_UPSTREAM_SKILL_DIR}/SKILL.md"
+
+    echo "[korean-jangbu-for] registered upstream skill /${UPSTREAM_SKILL} -> ${HOME_UPSTREAM_SKILL_DIR}"
+  done
+done
+
+echo ""
+echo "[korean-jangbu-for] done."
+echo "  pinned upstream SHA: ${UPSTREAM_SHA}"
+echo "  upstream repo:       ${UPSTREAM_REPO}"
+echo "  runtime install:     bash ~/.claude/skills/korean-jangbu-for/upstream/scripts/install.sh"
+echo "  verify command:      bash ~/.claude/skills/korean-jangbu-for/upstream/scripts/verify.sh"
+echo "  namespace note:      Re-run this wrapper installer after upstream runtime install to restore wrapper-managed top-level skills."
+echo "  subskills:           /korean-jangbu-for /jangbu-connect /jangbu-import /jangbu-tag /jangbu-tax /jangbu-dash /jangbu-jongso"
+echo "  원저작자: @kimlawtech (SpeciAI) — 응답마다 원본 링크와 함께 언급해야 한다."
+echo "  생성물은 참고용 초안이며 공식 회계감사·세무신고를 대체하지 않는다."
+echo "  법인세 신고 전 세무사 검토, 외감 대상은 공인회계사 감사가 필요하다."

package/skills/korean-jangbu-for/scripts/upstream.pin

@@ -0,0 +1 @@
+d8c2875ace84e212672e2d6206df254c5048b927

package/skills/korean-jangbu-for/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "korean-jangbu-for",
+  "description": "kimlawtech/korean-jangbu-for (Apache-2.0) 업스트림을 중심으로 한국 스타트업·1인 법인·프리랜서·개인사업자 장부 자동화와 사업자 세무 자료 정리, 원본 데이터 가져오기, 계정과목 태깅, 세무사 전달 CSV, 경영 리포트 생성을 안내하는 thin wrapper 스킬. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "action:submission"
+  ],
+  "frontmatter": "name: korean-jangbu-for\ndescription: kimlawtech/korean-jangbu-for (Apache-2.0) 업스트림을 중심으로 한국 스타트업·1인 법인·프리랜서·개인사업자 장부 자동화와 사업자 세무 자료 정리, 원본 데이터 가져오기, 계정과목 태깅, 세무사 전달 CSV, 경영 리포트 생성을 안내하는 thin wrapper 스킬. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: Apache-2.0\nmetadata:\n  category: finance\n  locale: ko-KR\n  phase: v1"
+}

package/skills/korean-law-search/instruction.md

@@ -0,0 +1,126 @@
+# Korean Law Search
+
+## What this skill does
+
+기본적으로 `https://k-skill-proxy.nomadamas.org/v1/korean-law/...` 로 요청해서 한국 법령/조문/판례/유권해석/자치법규를 조회한다. 법제처(국가법령정보센터) 공식 Open API(`open.law.go.kr` 의 DRF `lawSearch.do`/`lawService.do`)를 기반으로 하며, 설계는 `chrisryugj/korean-law-mcp` 의 read-only 도구 표면을 참고했다.
+
+사용자는 별도 API key(`LAW_OC`)나 로컬 CLI 설치가 필요 없다. `LAW_OC` 와 브라우저 User-Agent/Referer 주입은 proxy 서버에서만 처리한다.
+
+- 검색/목록: `GET /v1/korean-law/search`
+- 본문/상세: `GET /v1/korean-law/detail`
+
+## When to use
+
+- "산업안전보건법 찾아줘"
+- "관세법 제38조 보여줘"
+- "부당해고 판례 찾아줘"
+- "개인정보보호법 시행령 조문 확인해줘"
+- "한국 법령/판례/자치법규 검색해줘"
+
+## When not to use
+
+- 미국/일본/EU 등 비한국 법령 검색
+- 실제 법률 자문·소송 전략을 단정적으로 제공해야 하는 경우
+- 법령 원문이 아니라 일반 상식 설명만 필요한 경우
+
+## Prerequisites
+
+없음. 사용자는 별도 API key를 준비할 필요가 없다. upstream `LAW_OC` 는 proxy 서버에서만 주입한다.
+
+## Default path
+
+추가 client API 레이어는 불필요하다. 그냥 프록시 서버에 HTTP 요청만 넣으면 된다.
+
+`KSKILL_PROXY_BASE_URL` 환경변수가 있으면 그 값을 사용하고, 없으면 기본 경로 `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+
+## Supported endpoints
+
+### 검색/목록 조회
+
+```
+GET /v1/korean-law/search?target={target}&query={검색어}
+```
+
+`target` 은 read-only 법령정보 종류다.
+
+| target | 설명 |
+|---|---|
+| `law` | 현행법령 |
+| `eflaw` | 시행일 법령 |
+| `elaw` | 영문법령 |
+| `prec` | 판례 |
+| `detc` | 헌재결정례 |
+| `expc` | 법령해석례(유권해석) |
+| `admrul` | 행정규칙 |
+| `ordin` | 자치법규 |
+| `trty` | 조약 |
+| `lstrm` | 법령용어 |
+
+지원 필터: `query`(검색어), `display`, `page`, `sort`, `date`, `prncYd`(선고일자), `nb`(사건번호), `datSrcNm`(데이터출처명), `curt`(법원), `org`, `knd`, `gana`, `nw`, `efYd`, `ancYd`. 응답은 법제처 DRF JSON 그대로에 `proxy` 메타데이터만 덧붙인다. 요약 전에 반환 메타데이터를 먼저 확인한다.
+
+### 본문/상세 조회
+
+```
+GET /v1/korean-law/detail?target={target}&ID={일련번호}
+```
+
+검색 결과의 식별자(`ID` 또는 `MST`/`LID`)를 넘겨 상세 본문을 가져온다. 조문 지정은 `JO`(예: `000200` = 제2조), 언어는 `LANG` 로 넘긴다.
+
+## Example requests
+
+법령명 검색:
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-law/search' \
+  --data-urlencode 'target=law' \
+  --data-urlencode 'query=관세법'
+```
+
+판례 검색:
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-law/search' \
+  --data-urlencode 'target=prec' \
+  --data-urlencode 'query=부당해고'
+```
+
+판례 본문 조회:
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-law/detail' \
+  --data-urlencode 'target=prec' \
+  --data-urlencode 'ID=228541'
+```
+
+## Response policy
+
+- 한국 법령 관련 요청은 이 proxy endpoint로 처리한다. 별도 크롤러나 검색엔진 우회로 넘어가지 않는다.
+- 약칭(`화관법`)이면 `target=law` 로 정식 법령명을 먼저 확인한다.
+- 조문 요청이면 검색 결과의 식별자(`MST`/`ID`)를 확인한 뒤 `detail` 로 본문을 가져온다.
+- 판례는 `target=prec`, 유권해석은 `target=expc`, 자치법규는 `target=ordin` 로 조회한다.
+- 판례 본문이 필요하면 검색 결과의 판례 일련번호를 `detail?target=prec&ID=...` 로 이어서 조회한다.
+- 검색 결과가 0건이어도 "관련 규범이 없다"고 단정하지 말고 검색어·법원·사건번호·선고일자·출처명을 바꿔 다시 시도한다.
+- 일부 출처는 본문을 제공하지 않을 수 있다. 본문을 못 가져오면 목록 메타데이터(사건번호·법원·선고일자·출처·요지)까지만 제공하고 본문이 없다는 점을 명시한다(없는 본문을 지어내지 않는다).
+- 법적 판단이 필요한 경우 `검색 결과 요약`과 `원문 출처`까지만 제공하고 법률 자문처럼 단정하지 않는다.
+
+## Failure modes
+
+- `target` 이 없거나 허용되지 않은 값이면 400 응답
+- 검색어/식별자가 없으면 400 응답
+- 프록시 서버에 `LAW_OC` 가 없으면 503 응답
+- 법제처 API가 사용자 검증 실패(`사용자 정보 검증 실패`)를 반환하면 502 + `law_user_verification_failed` (서버 OC/UA/Referer 점검)
+- 법제처 API가 일시적으로 빈/HTML 응답이면 proxy가 재시도 후 502 + `upstream_unstable`
+
+## Done when
+
+- 한국 법령 관련 질의를 proxy endpoint로 라우팅했다.
+- 법령/조문은 `target=law` + 필요 시 `detail`, 판례는 `target=prec`, 유권해석은 `target=expc`, 자치법규는 `target=ordin` 로 맞는 종류를 조회했다.
+- 판례/조문 본문이 필요하면 식별자로 `detail` 본문까지 연결했다.
+- 결과를 요약하고 원문 출처(법제처 국가법령정보센터)를 함께 남겼다.
+
+## Notes
+
+- 설계 참고(upstream): `https://github.com/chrisryugj/korean-law-mcp`
+- official data source: 법제처 Open API (`https://open.law.go.kr`, DRF `lawSearch.do`/`lawService.do`)
+- 운영자(proxy) 전용 시크릿: `LAW_OC` (사용자는 불필요). 무료 발급: `https://open.law.go.kr`
+- 이 저장소 안에는 한국 법령 전용 npm package나 python package를 추가하지 않는다.

package/skills/korean-law-search/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "korean-law-search",
+  "description": "Search Korean statutes, articles, precedents, interpretations, and local ordinances via k-skill-proxy. Use when the user asks for Korean law/article/precedent lookups.",
+  "profiles": [
+    "proxy",
+    "browser",
+    "lookup"
+  ],
+  "frontmatter": "name: korean-law-search\ndescription: Search Korean statutes, articles, precedents, interpretations, and local ordinances via k-skill-proxy. Use when the user asks for Korean law/article/precedent lookups.\nlicense: MIT\nmetadata:\n  category: legal\n  locale: ko-KR\n  phase: v1"
+}

package/skills/korean-marathon-schedule/instruction.md

@@ -0,0 +1,111 @@
+# Korean Marathon Schedule
+
+## What this skill does
+
+한국 마라톤/러닝 대회 일정을 조회하고, 가능한 경우 대한철인3종협회 공개 일정에서 철인3종 대회도 함께 확인한다.
+
+응답에는 최소한 아래 필드를 포함한다.
+
+- 대회명
+- 개최일
+- 장소/지역
+- 신청 마감일 또는 접수 기간
+- 종목/코스(예: Half, 10km, 5km, 스탠다드)
+- 공식/상세 링크
+- 조회 시점 기준 정보라는 주의 문구
+
+## When to use
+
+- "서울 마라톤 일정 찾아줘"
+- "10km 대회 접수 마감일 알려줘"
+- "가을 마라톤 일정과 장소 정리해줘"
+- "철인3종 경기 일정도 가능하면 같이 봐줘"
+
+## Prerequisites
+
+- 인터넷 연결
+- Node.js 18+
+- 이 저장소의 `korean-marathon-schedule` npm package 또는 동일 로직
+
+## Public access path discovered
+
+### Primary marathon source: GoRunning
+
+- list entry point: `https://gorunning.kr/races/`
+- detail pages: same-host `gorunning.kr` links matching `/races/<id>/<slug>/`
+- detail fields used: title, event date, region/venue, registration period, registration deadline, status, organizer, website, categories.
+- reason selected: public unauthenticated race list/detail pages include the required venue, deadline/registration period, and event categories. It works with direct HTTP requests and does not require a proxy or API key.
+
+### Optional triathlon source: 대한철인3종협회
+
+- list entry point: `https://triathlon.or.kr/events/tour/?sYear=<YYYY>&vType=list`
+- detail pages: same-host `triathlon.or.kr` links matching `/events/tour/overview/?mode=overview&tourcd=<id>`
+- detail fields used: title, event date, venue, registration period, organizer, and course/category labels. Non-competition list entries such as education, seminars, notices, and referee/leader sessions are filtered out before detail fetch.
+- reason selected: the official federation page is public and unauthenticated, and provides triathlon schedules when available.
+
+## Workflow
+
+### 1. Search schedules
+
+```js
+const { searchEvents } = require("korean-marathon-schedule")
+
+const result = await searchEvents({
+  query: "서울",              // title, venue, region, or category filter. Optional.
+  from: "2026-05-01",       // optional YYYY-MM-DD
+  to: "2026-12-31",         // optional YYYY-MM-DD
+  includeTriathlon: true,    // optional; default false
+  limit: 10,                 // optional; default 10
+  maxDetailsPerSource: 100   // optional crawl budget; default max(300, limit * 10)
+})
+
+console.log(result.items)
+```
+
+CLI:
+
+```bash
+node packages/korean-marathon-schedule/src/cli.js 서울 --from 2026-05-01 --to 2026-12-31 --include-triathlon --limit 10 --max-details-per-source 100
+```
+
+### 2. Summarize conservatively
+
+For each event, show:
+
+```text
+- 대회명: ...
+  일정: ...
+  장소: ...
+  신청 마감: ...
+  종목: ...
+  링크: ...
+```
+
+If no deadline is present, say `신청 마감일을 공개 페이지에서 확인하지 못함` instead of guessing.
+
+### 3. Use fallback order
+
+1. GoRunning list → same-host GoRunning detail pages for marathon/road-running schedules; continue through the public list until enough matching results are collected, the list is exhausted, or the explicit per-source detail budget is reached.
+2. If the user asks for triathlon or `includeTriathlon` is useful, query the 대한철인3종협회 year list and same-host public detail pages; skip non-competition list entries and continue until enough matching results are collected, the selected year lists are exhausted, or the explicit per-source detail budget shared across selected years is reached.
+3. If either source returns an empty, blocked, changed page, or detail-budget warning, report the source-specific failure/warning and return any successfully parsed results from the other source.
+
+## Done when
+
+- User's location/date/category filter was applied or explicitly left broad.
+- At least one available result is summarized, or a clear empty-result/failure reason is given.
+- Venue, registration deadline/period, and categories are included when present.
+- Triathlon events were included when requested or when the user asked for them as "가능하면".
+
+## Failure modes
+
+- 일정/접수 정보는 수시로 바뀔 수 있다; always state results are based on the current public page read.
+- GoRunning or triathlon.or.kr HTML structure may change; then parsing may return empty fields or fail. Off-origin detail links are ignored to keep the lookup bounded to documented public sources. If a public list is larger than the per-source detail budget, results can be partial and a warning is returned; triathlon applies that budget once across all selected years.
+- Some official event websites may be linked only from the detail page; if absent, return the source detail URL.
+- Registration may already be closed even if the event date is upcoming.
+- Login, payment, CAPTCHA, or private member-only pages are outside scope and must not be automated.
+
+## Notes
+
+- This is a read-only lookup skill.
+- No k-skill-proxy route is used because the upstream surfaces are public and do not require API keys.
+- Do not register, reserve, pay for, or modify race entries.

package/skills/korean-marathon-schedule/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "korean-marathon-schedule",
+  "description": "고러닝과 대한철인3종협회 공개 표면으로 한국 마라톤·철인3종 경기 일정, 장소, 신청 마감일, 종목을 조회한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "proxy",
+    "action:booking"
+  ],
+  "frontmatter": "name: korean-marathon-schedule\ndescription: 고러닝과 대한철인3종협회 공개 표면으로 한국 마라톤·철인3종 경기 일정, 장소, 신청 마감일, 종목을 조회한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: sports\n  locale: ko-KR\n  phase: v1"
+}