@nomadamas/k-skill 0.1.0

package/skills/s2b-notice-search/instruction.md

@@ -0,0 +1,66 @@
+# S2B Notice Search
+
+## What this skill does
+
+S2B 학교장터(`www.s2b.kr`)의 공개 고객 공고/견적요청 표면에서 학교·교육기관 관련 물품, 공사, 용역 공고를 조회하는 read-only 스킬이다.
+
+- 키워드, 기관명, 지역, 게시일 범위, 물품/공사/용역, 1인/2인 수의계약 조건을 정규화한다.
+- `/S2BNCustomer/tcmo001.do` 검색 폼에 보낼 실제 `tcmo001Form` POST form recipe를 만든다.
+- 목록 fixture HTML에서 공고/견적 코드, 제목, 기관, 상태, 품목구분, 게시일, 마감일, 상세 JavaScript action metadata를 추출한다.
+- 상세 fixture HTML에서 제목, 공고번호, 기관명, 품목구분, 계약방법, 게시일, 마감일, 본문, 첨부 action metadata를 추출한다.
+
+입찰 참여, 견적 제출, 로그인, 결제, 낙찰/계약 처리 자동화는 하지 않는다.
+
+## Public path discovered from Aside
+
+Aside Browser로 S2B 공개 고객 화면을 확인할 때 우선 진입점은 다음이다.
+
+```text
+https://www.s2b.kr/S2BNCustomer/tcmo001.do
+```
+
+이 화면은 학교장터 고객용 공고/견적요청 조회 폼으로 동작하며, 브라우저에서 검색 조건을 채운 뒤 폼 제출 결과 표와 상세 이동 JavaScript action을 관찰한다. 확인된 form 이름은 `tcmo001Form`이고 주요 field는 `forwardName=list01`, `pageNo`, `search_yn=Y`, `process_yn=Y`, `tender_sep1`, `tender_name`, `company_name_s`, `tender_sep2`, `tender_date_start`, `tender_date_end`, `tender_item`, `estimate_kind`, `areaKind`다.
+
+## Fallback order
+
+1. Aside Browser REPL snapshot/action: 공개 페이지를 열고 snapshot으로 검색 폼과 결과 테이블을 확인한 뒤, 입력/제출/action metadata를 브라우저 표면에서 읽는다.
+2. BrowserOS CDP 또는 로컬 브라우저: Aside를 사용할 수 없으면 사용자가 띄운 BrowserOS 세션에 CDP로 붙거나 로컬 브라우저로 `https://www.s2b.kr/S2BNCustomer/tcmo001.do`를 열고 검색 폼을 제출한 뒤 렌더링된 목록/상세 HTML을 파싱한다.
+3. Direct HTTP best-effort: 같은 session cookie, referer, form token 조건이 브라우저와 동일하게 동작할 때만 `/S2BNCustomer/tcmo001.do`에 POST form body를 보낸다. session/form이 맞지 않으면 브라우저 경로로 돌아간다.
+
+## Inputs
+
+| Input | Values |
+| --- | --- |
+| `keyword` | 검색어 |
+| `organization` | 기관/학교명 |
+| `dateStart`, `dateEnd` | `YYYYMMDD` 또는 `YYYY-MM-DD`; 3 calendar months 초과 금지 |
+| `itemType` | `물품`, `공사`, `용역`, `all` |
+| `privateContract` | `1인`, `2인`, `all` |
+| `region` | 지역명 |
+| `page` | 1 이상의 정수 |
+
+## Package use
+
+```js
+const {
+  buildBrowserAutomationInstructions,
+  buildSearchRequest,
+  normalizeSearchOptions,
+  parseDetailHtml,
+  parseListHtml
+} = require("s2b-notice-search")
+```
+
+## Failure modes
+
+- malformed curl/client error: form body, cookies, referer, encoding, or client timeout이 잘못되어 S2B가 정상 HTML을 반환하지 않는다.
+- login/CAPTCHA/blocked: 로그인 벽, CAPTCHA, 차단/점검/보안 페이지가 나오면 우회하지 않고 실패로 분류한다.
+- empty: 검색 조건이 실제로 결과 없음이거나 session/form state가 맞지 않아 빈 목록이 반환된다.
+- upstream markup change: S2B table, 상세 action, hidden input, JavaScript 함수명이 바뀌면 파싱 결과가 부분적이거나 비어 있을 수 있다.
+
+## Done when
+
+- Aside Browser 또는 fallback browser에서 공개 S2B 조회 표면을 열었다.
+- 검색 기간이 유효하고 3 calendar months를 넘지 않는다.
+- 목록/상세 fixture parser가 필요한 필드를 추출했다.
+- 결과는 read-only lookup으로만 사용하고 제출/계약/로그인 자동화는 하지 않았다.

package/skills/s2b-notice-search/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "s2b-notice-search",
+  "description": "S2B 학교장터 공개 고객 공고/견적요청 목록을 브라우저 우선으로 조회하고 fixture HTML을 파싱해 공고 메타데이터를 정리한다. 돌쇠에서는 가능한 가장 가까운 합법적 공식 단계까지 준비한다.",
+  "profiles": [
+    "browser",
+    "hard-boundary"
+  ],
+  "frontmatter": "name: s2b-notice-search\ndescription: S2B 학교장터 공개 고객 공고/견적요청 목록을 브라우저 우선으로 조회하고 fixture HTML을 파싱해 공고 메타데이터를 정리한다. 돌쇠에서는 가능한 가장 가까운 합법적 공식 단계까지 준비한다.\nlicense: MIT\nmetadata:\n  category: procurement\n  locale: ko-KR\n  phase: v1"
+}

package/skills/saju-fortune/instruction.md

@@ -0,0 +1,177 @@
+# Saju Fortune
+
+## What this skill does
+
+`saju-fortune` npm package로 사주팔자 기본 구조, 오행 분포, 용신 조율점, 주제별 운세, 궁합 풀이를 제공한다. 사용자를 바로 점치는 대신 먼저 필요한 정보를 인터뷰하고, 패키지 결과를 근거로 사주 풀이 에이전트처럼 대화한다.
+
+이 스킬은 `hjsh200219/fortuneteller` MCP 서버의 도구 모델(`analyze_saju`, `check_compatibility`, `get_daily_fortune`, `get_dae_un`, `get_fortune_by_period`)을 참고하지만 **MCP 서버를 따로 실행하지 않는다**. 에이전트는 로컬/전역 npm package를 직접 호출한다.
+
+## When to use
+
+- "사주 봐줘"
+- "올해 운세 어때?"
+- "연애운/재물운/직업운/건강운 봐줘"
+- "우리 궁합 봐줘"
+- "생년월일시로 사주팔자 풀이해줘"
+
+## When not to use
+
+- 의학적 진단, 투자 수익 보장, 법적 판단처럼 전문 책임이 필요한 결정을 대신해야 하는 경우
+- 사용자가 출생 정보를 제공하지 않고 사주 계산 없이 일반 조언만 원하는 경우
+- 사주 풀이를 사실 확정이나 운명 결정론으로 제시해야 하는 경우
+
+## Prerequisites
+
+- Node.js 18+
+- 배포 후: `npm install -g saju-fortune`
+- 실행 전: `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. 보고 싶은 주제: 종합운, 연애운, 재물운, 직업운, 건강운, 한해 운세, 궁합
+
+궁합은 두 사람 각각의 생년월일시와 성별을 확인한다.
+
+## Workflow
+
+### 1. Interview first
+
+정보가 부족하면 풀이를 시작하지 말고 짧게 묻는다.
+
+권장 질문:
+
+```text
+사주 풀이를 위해 양력/음력, 생년월일, 태어난 시간, 성별을 알려주세요. 보고 싶은 주제도 골라주세요: 연애운, 재물운, 직업운, 건강운, 한해 운세, 궁합.
+```
+
+태어난 시간을 모르면:
+
+```text
+태어난 시간을 모르면 시주는 확정하지 못해요. 가능한 시간대가 있으면 알려주시고, 없으면 연·월·일 중심의 보수적 풀이로 진행할게요.
+```
+
+음력 생일이면 이 패키지 안에서 변환하지 않는다. 검증된 만세력으로 양력 생년월일을 먼저 확인한 뒤 `calendar: "solar"`로 호출하고, 변환 근거와 윤달 여부를 한계로 적는다.
+
+### 2. Install package when missing
+
+`node -e 'require("saju-fortune")'`가 실패하면 다른 웹 스크래핑이나 MCP 서버 실행으로 우회하지 말고 전역 package 설치를 먼저 시도한다.
+
+```bash
+npm install -g saju-fortune
+export NODE_PATH="$(npm root -g)"
+```
+
+### 3. Analyze one person's saju
+
+```bash
+NODE_PATH="$(npm root -g)" node - <<'JS'
+const { analyzeSaju } = require("saju-fortune")
+
+const result = analyzeSaju({
+  name: "민준",
+  birthDate: "1990-03-15",
+  birthTime: "10:30",
+  calendar: "solar", // 음력은 검증된 만세력으로 양력 변환 후 입력
+  gender: "male",
+  birthCity: "서울"
+}, {
+  analysisType: "fortune",
+  fortuneType: "wealth",
+  targetYear: 2026
+})
+
+console.log(JSON.stringify(result, null, 2))
+JS
+```
+
+`fortuneType` mapping:
+
+- 종합운: `general`
+- 연애운: `love`
+- 재물운: `wealth`
+- 직업운: `career`
+- 건강운: `health`
+- 한해 운세: `general` + `targetYear`
+
+### 4. Check compatibility
+
+```bash
+NODE_PATH="$(npm root -g)" node - <<'JS'
+const { checkCompatibility } = require("saju-fortune")
+
+const result = checkCompatibility({
+  person1: { name: "민준", birthDate: "1990-03-15", birthTime: "10:30", gender: "male" },
+  person2: { name: "서연", birthDate: "1992-07-20", birthTime: "14:30", gender: "female" }
+})
+
+console.log(JSON.stringify(result, null, 2))
+JS
+```
+
+### 5. MCP-style tool names without serving MCP
+
+패키지는 upstream MCP 서버의 대표 도구명을 로컬 함수로 흉내 낸다. MCP 서버를 따로 띄우지 않는다.
+
+```js
+const { callSajuTool } = require("saju-fortune")
+
+const result = callSajuTool("analyze_saju", {
+  birthDate: "1990-03-15",
+  birthTime: "10:30",
+  gender: "male",
+  analysisType: "fortune",
+  fortuneType: "love"
+})
+```
+
+지원 도구명:
+
+- `analyze_saju`
+- `check_compatibility`
+- `get_daily_fortune`
+- `get_dae_un`
+- `get_fortune_by_period`
+- `convert_calendar`
+- `manage_settings`
+
+### 6. Interpret like a fortune-reading agent
+
+응답은 아래 구조를 따른다.
+
+1. 입력 정보와 정확도 한계: 양력/음력, 시간, 출생지 누락 여부를 확인한다.
+2. 사주팔자 요약: 연주·월주·일주·시주와 일간을 짧게 설명한다.
+3. 오행 분포: 강한 오행과 부족한 오행을 생활 언어로 번역한다.
+4. 주제별 풀이: 연애운/재물운/직업운/건강운/한해 운세 중 사용자가 고른 주제만 깊게 본다.
+5. 실천 조언: 결정론 대신 대화, 습관, 리스크 관리 조언을 준다.
+6. 주의 문구: 사주 풀이는 재미와 자기점검용이며 의료·투자·법률 판단을 대신하지 않는다고 말한다.
+
+## Done when
+
+- 필요한 출생 정보를 인터뷰로 확인했다.
+- `saju-fortune` package 결과를 근거로 사주팔자와 오행 분포를 확인했다.
+- 사용자가 요청한 주제(연애운, 재물운, 한해 운세 등)에 맞춰 풀이했다.
+- 모르는 시간, 음력 윤달, 출생지 누락 같은 한계를 명시했다.
+- MCP 서버를 실행하거나 별도 서버를 서빙하지 않았다.
+
+## Failure modes
+
+- 태어난 시간이 없으면 시주와 시주 기반 해석은 확정할 수 없다.
+- 음력 또는 윤달 생일은 내장 계산으로 변환하지 않는다. 검증된 만세력으로 양력 날짜를 먼저 확인하지 못하면 풀이하지 않는다.
+- 출생지가 없으면 경도 보정은 생략되거나 기본값으로 해석된다.
+- package가 설치되지 않았고 네트워크도 없으면 설치 실패를 설명하고 진행하지 않는다.
+- 사주 풀이는 전통 해석 기반의 참고 자료이며 의료, 투자, 법률, 안전 결정을 대체하지 않는다.
+
+## Notes
+
+- 입력한 생년월일시는 풀이 중에만 사용하고 영구 저장하지 않는다.
+- 사용자가 불안해할 만한 단정적 흉언, 저주, 사망 예언, 질병 확정 표현은 하지 않는다.
+- 궁합 점수는 관계 대화의 참고자료일 뿐 이별/결혼 결정을 대신하지 않는다.

package/skills/saju-fortune/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "saju-fortune",
+  "description": "사주팔자 정보를 인터뷰로 확인한 뒤 saju-fortune npm package를 사용해 연애운, 재물운, 직업운, 건강운, 한해 운세, 궁합을 대화형으로 풀이한다.",
+  "profiles": [
+    "local"
+  ],
+  "frontmatter": "name: saju-fortune\ndescription: 사주팔자 정보를 인터뷰로 확인한 뒤 saju-fortune npm package를 사용해 연애운, 재물운, 직업운, 건강운, 한해 운세, 궁합을 대화형으로 풀이한다.\nlicense: MIT\nmetadata:\n  category: utility\n  locale: ko-KR\n  phase: v1"
+}

package/skills/saramin-talent-search/instruction.md

@@ -0,0 +1,119 @@
+# saramin-talent-search
+
+## Use when
+
+- 사용자가 사람인 인재풀에서 후보를 찾아달라고 요청한다.
+- 기업회원 로그인/2차 인증이 완료된 브라우저 세션에서 후보를 검색해야 한다.
+- 유료 열람 전 shortlist, 점수, 근거, 리스크, 후보 URL이 필요하다.
+
+## Hard boundaries
+
+Allowed:
+- 사람인 인재풀 브라우저 세션 열기 및 검색 필터 입력
+- 현재 보이는 마스킹 후보 목록/프로필/이력서 읽기
+- 후보 분석, 점수화, shortlist 작성, 유료 열람 추천
+
+Never do without explicit user handoff/confirmation:
+- 유료 이력서 열람, 연락처 확인, 마스킹 해제
+- 포지션/입사 제안 발송
+- 스크랩, 관심후보 등록, 메모, 후보 상태 변경
+- 결제/유료 상품 사용
+- 비밀번호, OTP, 인증번호, 세션 쿠키 요청/저장
+- 후보 개인정보 장기 저장 또는 대량 수집
+
+If a control may spend credits, reveal contact/private info, send a proposal, or mutate account state, stop before clicking it.
+
+## Primary access
+
+Open:
+
+```text
+https://www.saramin.co.kr/zf_user/memcom/talent-pool/main/search
+```
+
+If login or first-device verification is required, pause and show:
+
+```text
+사람인 인재풀 검색은 기업회원 로그인과, 처음 사용하는 브라우저/기기에서는 2차 인증이 필요할 수 있습니다.
+제가 브라우저로 사람인 인재풀 검색 페이지를 열어둘게요.
+열린 브라우저에서 직접 로그인과 필요한 경우 2차 인증을 완료해 주세요.
+비밀번호, 인증번호, 세션 쿠키는 저에게 알려주지 마세요.
+인재풀 검색 화면이 보이면 “인증 완료했어”라고 알려주세요.
+그 다음 같은 브라우저 세션에서 검색을 이어가겠습니다.
+```
+
+Resume only in the same browser session after the user confirms the search UI is visible.
+
+## Input normalization
+
+Extract or infer:
+
+- role_title
+- must_have / nice_to_have
+- negative_keywords
+- career min/max
+- location/work_area
+- role-specific evaluation signals
+- limit / requested Top N
+
+Do not block on missing details when a reasonable first search is possible.
+
+## Workflow
+
+1. Open the primary URL and verify corporate login plus search UI visibility.
+2. Ask the user to log in/verify manually only when required; never handle credentials.
+3. Apply filters: keyword, 직무/직종, 경력, 지역, recent update/activity/relevance sorting, exclusions when supported.
+4. Build a candidate pool from visible rows.
+5. Before final Top N, open normal profile/resume detail links for promising candidates when this does not trigger paid unlock/contact/proposal actions.
+6. Read only visible free/masked details: career, responsibilities, project/achievement evidence, skills, education/certs/languages, desired location/salary/job-seeking state, portfolio links if visible, recent activity.
+7. Score role-adaptively: must-have fit, career depth, concrete achievement/project evidence, location/activity fit, nice-to-have signals, and risk penalty.
+8. Return Korean shortlist with direct URL per recommended candidate.
+
+Do not finalize Top N from list rows only unless details are inaccessible or paid-walled. If so, label results as `목록 기반 1차 shortlist` and lower confidence. If detail text was inspected, label as `상세 이력 확인 기반 shortlist`.
+
+## Permission guidance
+
+Safe after normal tool/browser approval: opening the search page, typing filters, pressing search/apply, scrolling results, opening normal candidate detail links, reading currently visible masked/free text.
+
+Must stop/handoff: paid unlock, contact reveal, proposal/send, scrap/interest, memo/status changes, payment, credential/OTP/cookie handling.
+
+## URL extraction guidance
+
+Every recommended candidate needs a direct Saramin profile/resume URL whenever available. If browser extraction fails, inspect anchors, onclick handlers, data attributes, card containers, and detail-page `location.href`. If still missing, write `URL: 추출 실패` and explain why.
+
+## Output shape
+
+```text
+사람인 인재풀 shortlist
+
+검색 조건
+- 포지션: ...
+- 필수/우대/제외 조건: ...
+- 경력/지역: ...
+- 모드: 상세 이력 확인 기반 shortlist / 목록 기반 1차 shortlist
+
+유료 열람 추천 Top N
+1. 후보 A
+   - 점수: 88/100
+   - 근거: ...
+   - 보이는 경력/성과: ...
+   - 리스크: ...
+   - 추천 액션: 채용 담당자가 유료 열람 검토
+   - URL: ...
+
+보류 후보
+- ...
+
+검색 한계
+- 마스킹/현재 표시 정보만 분석했음
+- 연락처/실명/비공개 정보는 열람하지 않음
+- 유료 액션은 실행하지 않음
+```
+
+## Failure modes
+
+- Login/2FA required: open the page and let the user complete it manually.
+- Browser/session unavailable: explain that the agent needs browser/computer-use access; do not silently switch to no-login scraping.
+- Paid wall/contact wall: stop and mark as manual paid review needed.
+- Empty results: adjust keywords, career, region, update/relevance filters.
+- UI changed: rediscover the visible form/data flow before updating instructions.

package/skills/saramin-talent-search/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "saramin-talent-search",
+  "description": "사람인 기업회원 인재풀 로그인 세션에서 마스킹된 후보 정보를 검색·비교해 유료 열람 전 shortlist를 만듭니다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "browser",
+    "action:communication"
+  ],
+  "frontmatter": "name: saramin-talent-search\ndescription: 사람인 기업회원 인재풀 로그인 세션에서 마스킹된 후보 정보를 검색·비교해 유료 열람 전 shortlist를 만듭니다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: recruiting\n  locale: ko-KR\n  phase: v1"
+}

package/skills/seoul-bike/instruction.md

@@ -0,0 +1,83 @@
+# Seoul Bike (따릉이)
+
+## What this skill does
+
+서울 열린데이터 광장의 따릉이 실시간 대여정보를 `k-skill-proxy` 경유로 조회해 대여 가능 자전거 수와 빈 거치대 수를 요약한다.
+
+## When to use
+
+- "지금 여기서 따릉이 빌릴 수 있어?"
+- "광화문 근처 빈 거치대 있어?"
+- "강남역 따릉이 대여소에 자전거 몇 대 남았어?"
+
+## Prerequisites
+
+- Python 3 표준 라이브러리만 사용한다.
+- optional: `KSKILL_PROXY_BASE_URL` (self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted `https://k-skill-proxy.nomadamas.org` 를 사용한다.)
+
+## Required environment variables
+
+없음. 사용자가 개인 서울 열린데이터 광장 OpenAPI key를 직접 발급할 필요는 없다. `/v1/seoul-bike/*` routes는 기본 hosted proxy에서 호출하고, upstream key는 proxy 서버 쪽에만 보관한다.
+
+## Single entrypoint
+
+```bash
+python3 "$SKILL_DIR/scripts/seoul_bike.py" <subcommand> [args]
+```
+
+첫 사용 시 `Bash(python3 *seoul_bike.py:*)` 패턴 한 번만 승인하면 이후 호출은 모두 자동 허용된다.
+
+## Subcommands
+
+| 명령 | 설명 |
+|---|---|
+| `nearby --lat LAT --lon LON [--radius-m 500] [--limit 10] [--json]` | 좌표 주변 실시간 대여소 조회 |
+| `search <키워드> [--limit 10] [--json]` | 대여소 이름에 키워드가 포함된 실시간 상태 검색 |
+| `realtime [--start-index 1 --end-index 1000]` | 실시간 대여정보 원문 JSON 페이지 조회 |
+
+## Workflow
+
+### 1. 현재 위치 주변 대여소 조회
+
+```bash
+python3 "$SKILL_DIR/scripts/seoul_bike.py" nearby --lat 37.5717 --lon 126.9763 --radius-m 500
+```
+
+요약 항목:
+
+- 대여소명
+- 대여 가능 자전거 수 (`parkingBikeTotCnt`)
+- 빈 거치대 수 (`rackTotCnt - parkingBikeTotCnt`)
+- 거리(m)
+- 조회 시각(`proxy.requested_at`)
+
+### 2. 대여소 이름 검색
+
+```bash
+python3 "$SKILL_DIR/scripts/seoul_bike.py" search "광화문" --limit 5
+```
+
+### 3. Proxy endpoints
+
+- `GET /v1/seoul-bike/realtime?startIndex=1&endIndex=1000` → 서울 `bikeList` 실시간 대여정보
+- `GET /v1/seoul-bike/stations?startIndex=1&endIndex=1000` → 서울 `tbCycleStationInfo` 대여소 마스터 정보
+- `GET /v1/seoul-bike/nearby?lat=37.5717&lon=126.9763&radius_m=500&limit=10` → proxy-side 주변 대여소 필터링
+
+## Done when
+
+- 대여 가능 자전거 수와 빈 거치대 수가 정리되어 있다.
+- live data 기준 조회 시각이 명시되어 있다.
+- upstream key가 클라이언트에 노출되지 않았다.
+
+## Failure modes
+
+- proxy upstream key 미설정 (`SEOUL_OPEN_API_KEY` 없음)
+- 서울 열린데이터 광장 quota 초과
+- 실시간 API가 빈 행 또는 일시 오류를 반환
+- 좌표가 없거나 반경 안에 대여소가 없음
+
+## Notes
+
+- 실시간 데이터는 계속 변하므로 답변에 조회 시각을 함께 적는다.
+- 예약/대여 자동화는 하지 않는다. 조회 전용 스킬이다.
+- proxy 운영/환경변수 설정은 `docs/features/k-skill-proxy.md` 를 참고한다.