@nomadamas/k-skill 0.1.0 → 0.2.1

package/skills/srt-booking/instruction.md

@@ -66,7 +66,7 @@ python3 -m pip install SRTrain
 먼저 helper 로 조회해서 후보를 요약한다.
 
 ```bash
-python3 scripts/srt_booking.py search 수서 부산 20260328 080000 --time-limit 120000 --limit 5
+npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- search 수서 부산 20260328 080000 --time-limit 120000 --limit 5
 ```
 
 ### 3. Summarize options before side effects
@@ -82,19 +82,19 @@ python3 scripts/srt_booking.py search 수서 부산 20260328 080000 --time-limit
 `search` 의 좌석 가능 여부는 열차 단위 플래그다. 사용자가 "남은 좌석 번호", "호차별 좌석", "특정 좌석", "창측/순방향 자리", "예약 전에 자리 확인"처럼 구체적인 좌석을 물으면 예약 전에 `seats` 를 호출한다.
 
 ```bash
-python3 scripts/srt_booking.py seats 수서 부산 20260328 080000 --train-id <train_id>
+npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- seats 수서 부산 20260328 080000 --train-id <train_id>
 ```
 
 특정 호차의 빈 좌석만 확인하려면 `--car-no` 와 `--available-only` 를 쓴다.
 
 ```bash
-python3 scripts/srt_booking.py seats 수서 부산 20260328 080000 --train-id <train_id> --car-no 5 --available-only
+npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- seats 수서 부산 20260328 080000 --train-id <train_id> --car-no 5 --available-only
 ```
 
 특정 좌석이 비었는지 확인하려면 `--seat` 를 붙인다.
 
 ```bash
-python3 scripts/srt_booking.py seats 수서 부산 20260328 080000 --train-id <train_id> --car-no 5 --seat 11A
+npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- seats 수서 부산 20260328 080000 --train-id <train_id> --car-no 5 --seat 11A
 ```
 
 특정 호차를 지정하지 않으면 가운데 호차부터 탐색한다. `--car-priority center|low|high` 로 호차 탐색 순서를 바꾸고, `--seat-priority forward-window|window-forward|row-low` 로 좌석 정렬 우선순위를 바꾼다.

package/skills/subway-lost-property/instruction.md

@@ -47,7 +47,7 @@ LOST112 검색 폼에서 확인되는 핵심 필드는 아래와 같다.
 repo helper를 그대로 써도 된다.
 
 ```bash
-python3 scripts/subway_lost_property.py \
+npx -y @nomadamas/k-skill@0 exec subway-lost-property scripts/subway_lost_property.py -- \
   --station 강남역 \
   --item 지갑 \
   --days 14
@@ -58,7 +58,7 @@ helper는 기본적으로 `SITE=V` 를 사용하고, 역명/물품명/기간을
 ### 3) Optionally verify live reachability
 
 ```bash
-python3 scripts/subway_lost_property.py \
+npx -y @nomadamas/k-skill@0 exec subway-lost-property scripts/subway_lost_property.py -- \
   --station 강남역 \
   --item 지갑 \
   --days 14 \

package/skills/subway-lost-property/skill.json

@@ -2,7 +2,7 @@
   "name": "subway-lost-property",
   "description": "Use when the user asks how to look up 지하철 분실물 or 유실물 by 역명/물품명. v1 is an 안내형/하이브리드 skill that structures the official LOST112 + 서울교통공사 flow conservatively. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
   "profiles": [
-    "action:communication"
+    "lookup"
   ],
   "frontmatter": "name: subway-lost-property\ndescription: Use when the user asks how to look up 지하철 분실물 or 유실물 by 역명/물품명. v1 is an 안내형/하이브리드 skill that structures the official LOST112 + 서울교통공사 flow conservatively. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: transit\n  locale: ko-KR\n  phase: v1"
 }

package/skills/ticket-availability/instruction.md

@@ -59,7 +59,7 @@ pip install httpx
 ### 2. 일정 조회 (`schedule`)
 
 ```bash
-python3 scripts/ticket_availability.py schedule "https://tickets.interpark.com/goods/26000541"
+npx -y @nomadamas/k-skill@0 exec ticket-availability scripts/ticket_availability.py -- schedule "https://tickets.interpark.com/goods/26000541"
 ```
 
 응답 — Interpark:
@@ -90,7 +90,7 @@ YES24 는 기본 3주 윈도우. 6개월 전체는 `--all-dates` 추가.
 ### 3. 잔여석 조회 (`seats`)
 
 ```bash
-python3 scripts/ticket_availability.py seats "interpark:26000541"
+npx -y @nomadamas/k-skill@0 exec ticket-availability scripts/ticket_availability.py -- seats "interpark:26000541"
 ```
 
 응답:
@@ -120,7 +120,7 @@ YES24 응답은 등급별 `price` (노출가) 도 포함:
 ### 4. 헬스체크 (`health`)
 
 ```bash
-python3 scripts/ticket_availability.py health
+npx -y @nomadamas/k-skill@0 exec ticket-availability scripts/ticket_availability.py -- health
 ```
 
 응답:

package/skills/ticket-availability/skill.json

@@ -2,8 +2,9 @@
   "name": "ticket-availability",
   "description": "YES24 / 인터파크 공연의 공개 일정 + 등급별 잔여석을 단일 HTTP 호출로 조회 (조회 전용, 예매·결제 없음). 돌쇠에서는 가능한 가장 가까운 합법적 공식 단계까지 준비한다.",
   "profiles": [
+    "vault",
     "browser",
-    "hard-boundary"
+    "action:booking"
   ],
   "frontmatter": "name: ticket-availability\ndescription: YES24 / 인터파크 공연의 공개 일정 + 등급별 잔여석을 단일 HTTP 호출로 조회 (조회 전용, 예매·결제 없음). 돌쇠에서는 가능한 가장 가까운 합법적 공식 단계까지 준비한다.\nlicense: MIT\nmetadata:\n  category: lifestyle\n  subcategory: ticket\n  locale: ko-KR\n  phase: v1"
 }

package/skills/yebigun-training/skill.json

@@ -2,8 +2,9 @@
   "name": "yebigun-training",
   "description": "사용자가 직접 로그인한 예비군 홈페이지(yebigun1.mil.kr) Chrome 세션을 재사용해 이번 훈련 일정/장소를 조회하고, 작년 이전 기록과 비교해 무엇이 달라졌는지 알려준다. 조회 전용이며 로그인이나 연기·보류 신청은 절대 자동화하지 않는다. 돌쇠에서는 가능한 가장 가까운 합법적 공식 단계까지 준비한다.",
   "profiles": [
+    "vault",
     "browser",
-    "hard-boundary"
+    "legal"
   ],
   "frontmatter": "name: yebigun-training\ndescription: 사용자가 직접 로그인한 예비군 홈페이지(yebigun1.mil.kr) Chrome 세션을 재사용해 이번 훈련 일정/장소를 조회하고, 작년 이전 기록과 비교해 무엇이 달라졌는지 알려준다. 조회 전용이며 로그인이나 연기·보류 신청은 절대 자동화하지 않는다. 돌쇠에서는 가능한 가장 가까운 합법적 공식 단계까지 준비한다.\nlicense: MIT\nmetadata:\n  category: legal\n  locale: ko-KR\n  phase: v1"
 }

package/skills/zipcode-search/instruction.md

@@ -98,8 +98,8 @@ PY
 저장소에는 같은 흐름을 감싼 실행 가능한 helper가 포함되어 있다.
 
 ```bash
-python3 scripts/zipcode_search.py "서울특별시 강남구 테헤란로 123"
-./scripts/zipcode_search.py "서울특별시 강남구 테헤란로 123"
+npx -y @nomadamas/k-skill@0 exec zipcode-search scripts/zipcode_search.py -- "서울특별시 강남구 테헤란로 123"
+npx -y @nomadamas/k-skill@0 exec zipcode-search scripts/zipcode_search.py -- "서울특별시 강남구 테헤란로 123"
 ```
 
 예시 출력:

package/src/assemble.js

@@ -6,6 +6,7 @@ const path = require("node:path");
 const packageRoot = path.join(__dirname, "..");
 const templatesDir = path.join(packageRoot, "templates");
 const skillsDir = path.join(packageRoot, "skills");
+const CLI_INVOCATION = "npx -y @nomadamas/k-skill@0";
 
 const KNOWN_PROFILES = [
   "core",
@@ -14,12 +15,13 @@ const KNOWN_PROFILES = [
   "vault",
   "action:booking",
   "action:commerce",
-  "action:communication",
   "action:submission",
   "action:account",
-  "hard-boundary",
+  "action:recruiting",
+  "legal",
   "lookup",
   "local",
+  "operations",
 ];
 
 function profileTemplatePath(profile) {
@@ -64,6 +66,133 @@ function loadSkill(skillName) {
   };
 }
 
+function assetRelativePaths(skillName) {
+  const { dir } = loadSkill(skillName);
+  return bundledFiles(skillName).map((filePath) => path.relative(dir, filePath).split(path.sep).join("/"));
+}
+
+function resolveBundledAsset(skillName, relativePath, allowedRoots = ["scripts", "references", "tests"]) {
+  const { dir } = loadSkill(skillName);
+  const normalized = path.posix.normalize(String(relativePath).replaceAll("\\", "/"));
+  const root = normalized.split("/")[0];
+
+  if (
+    normalized === "." ||
+    normalized.startsWith("../") ||
+    path.posix.isAbsolute(normalized) ||
+    !allowedRoots.includes(root)
+  ) {
+    const error = new Error(
+      `asset path "${relativePath}" must stay inside ${allowedRoots.join(", ")} for skill "${skillName}"`,
+    );
+    error.code = "EASSETPATH";
+    throw error;
+  }
+
+  const candidate = path.resolve(dir, ...normalized.split("/"));
+  if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
+    const error = new Error(`asset "${normalized}" is not bundled for skill "${skillName}"`);
+    error.code = "EASSETNOTFOUND";
+    throw error;
+  }
+
+  const realDir = fs.realpathSync(dir);
+  const realCandidate = fs.realpathSync(candidate);
+  if (!realCandidate.startsWith(`${realDir}${path.sep}`)) {
+    const error = new Error(`asset "${normalized}" escapes skill "${skillName}"`);
+    error.code = "EASSETPATH";
+    throw error;
+  }
+
+  return realCandidate;
+}
+
+function readBundledAsset(skillName, relativePath) {
+  return fs.readFileSync(resolveBundledAsset(skillName, relativePath, ["references", "scripts"]), "utf8");
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function scriptPathPattern(skillName, relativePath) {
+  const rel = escapeRegex(relativePath);
+  const skill = escapeRegex(skillName);
+  return `(?:"?\\$SKILL_DIR/|\\./${skill}/|${skill}/|\\./)?${rel}"?`;
+}
+
+function rewriteAssetCommandReferences(raw, skillName) {
+  let output = raw;
+  const assets = assetRelativePaths(skillName);
+  const scripts = assets.filter((relativePath) => relativePath.startsWith("scripts/"));
+  const references = assets.filter((relativePath) => relativePath.startsWith("references/"));
+
+  for (const relativePath of scripts.sort((a, b) => b.length - a.length)) {
+    const assetPattern = scriptPathPattern(skillName, relativePath);
+    const execCommand = `${CLI_INVOCATION} exec ${skillName} ${relativePath} --`;
+
+    output = output.replace(
+      new RegExp(`(?:python3?|node|bash|uv\\s+run)\\s+${assetPattern}`, "g"),
+      execCommand,
+    );
+    output = output.replace(
+      new RegExp(`(^|[|;&]\\s*)${assetPattern}(?=\\s|$)`, "gm"),
+      `$1${execCommand}`,
+    );
+  }
+
+  for (const relativePath of assets.filter((item) => /\.(?:md|txt|pin)$/i.test(item))) {
+    const assetPattern = scriptPathPattern(skillName, relativePath);
+    const readCommand = `${CLI_INVOCATION} read ${skillName} ${relativePath}`;
+
+    output = output.replace(new RegExp(`cat\\s+${assetPattern}`, "g"), readCommand);
+  }
+
+  for (const relativePath of references.sort((a, b) => b.length - a.length)) {
+    const escaped = escapeRegex(relativePath);
+    const readCommand = `${CLI_INVOCATION} read ${skillName} ${relativePath}`;
+
+    output = output.replace(
+      new RegExp(`\\[([^\\]]+)\\]\\((?:\\./)?${escaped}\\)`, "g"),
+      (_match, label) =>
+        label.includes(relativePath) ? `\`${readCommand}\`` : `${label} (\`${readCommand}\`)`,
+    );
+    output = output.replace(
+      new RegExp(`\`(?:\\./)?${escaped}\``, "g"),
+      `\`${readCommand}\``,
+    );
+  }
+
+  return output;
+}
+
+// Source instructions are migrated to the CLI surface, and assembly repeats
+// the normalization defensively so a newly added relative command cannot leak
+// into a released instruction before CI catches it.
+function rewriteBundledAssetInstructions(raw, skillName) {
+  const assets = assetRelativePaths(skillName);
+  const scripts = assets.filter((relativePath) => relativePath.startsWith("scripts/"));
+  const references = assets.filter((relativePath) => relativePath.startsWith("references/"));
+  let output = rewriteAssetCommandReferences(raw, skillName);
+
+  if (scripts.length || references.length) {
+    const accessRules = [
+      "## Bundled asset access",
+      "",
+      `- Execute bundled helpers only through \`${CLI_INVOCATION} exec ${skillName} scripts/<file> -- <args>\`; do not assume a repository-relative or installed-skill-relative path.`,
+      `- Resolve an asset path with \`${CLI_INVOCATION} path ${skillName} <relative-path>\` only when another tool explicitly requires a filesystem path.`,
+    ];
+    if (references.length) {
+      accessRules.push(
+        `- Read bundled references through \`${CLI_INVOCATION} read ${skillName} references/<file>\`.`,
+      );
+    }
+    output = `${accessRules.join("\n")}\n\n${output}`;
+  }
+
+  return output;
+}
+
 // Template files interleave `<!-- mode:always -->`, `<!-- mode:dolshoi -->`,
 // and `<!-- mode:generic -->` markers. Only the sections matching the detected
 // mode (plus always-sections) are emitted.
@@ -107,7 +236,8 @@ function assemble(skillName, runtime) {
   ].join("\n");
 
   // instruction.md may also use mode markers for mode-specific sections.
-  return `${header}\n\n${renderTemplate(instruction, runtime.mode)}\n`;
+  const renderedInstruction = renderTemplate(instruction, runtime.mode);
+  return `${header}\n\n${rewriteBundledAssetInstructions(renderedInstruction, skillName)}\n`;
 }
 
 function bundledFiles(skillName) {
@@ -121,6 +251,7 @@ function bundledFiles(skillName) {
     while (stack.length) {
       const currentDir = stack.pop();
       for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+        if (entry.name === "__pycache__" || entry.name.startsWith(".") || entry.name.endsWith(".pyc")) continue;
         const full = path.join(currentDir, entry.name);
         if (entry.isDirectory()) stack.push(full);
         else results.push(full);
@@ -131,4 +262,17 @@ function bundledFiles(skillName) {
   return results.sort();
 }
 
-module.exports = { assemble, bundledFiles, listSkills, loadSkill, renderTemplate, KNOWN_PROFILES };
+module.exports = {
+  CLI_INVOCATION,
+  KNOWN_PROFILES,
+  assemble,
+  assetRelativePaths,
+  bundledFiles,
+  listSkills,
+  loadSkill,
+  readBundledAsset,
+  renderTemplate,
+  resolveBundledAsset,
+  rewriteAssetCommandReferences,
+  rewriteBundledAssetInstructions,
+};

package/src/execute.js

@@ -0,0 +1,81 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const childProcess = require("node:child_process");
+
+const { resolveBundledAsset } = require("./assemble");
+
+function splitShebang(value) {
+  return value.trim().split(/\s+/).filter(Boolean);
+}
+
+function resolveRunner(scriptPath, env = process.env) {
+  const firstLine = fs.readFileSync(scriptPath, "utf8").split(/\r?\n/, 1)[0];
+
+  if (firstLine.startsWith("#!")) {
+    const parts = splitShebang(firstLine.slice(2));
+    if (parts[0] === "/usr/bin/env") {
+      const args = parts.slice(parts[1] === "-S" ? 2 : 1);
+      if (args.length) {
+        const [command, ...prefixArgs] = args;
+        return {
+          command: command === "node" ? process.execPath : command,
+          args: [...prefixArgs, scriptPath],
+        };
+      }
+    }
+
+    if (parts[0]) {
+      return { command: parts[0], args: [...parts.slice(1), scriptPath] };
+    }
+  }
+
+  switch (path.extname(scriptPath).toLowerCase()) {
+    case ".py":
+      return { command: env.KSKILL_PYTHON || "python3", args: [scriptPath] };
+    case ".js":
+    case ".cjs":
+    case ".mjs":
+      return { command: process.execPath, args: [scriptPath] };
+    case ".sh":
+      return { command: env.KSKILL_BASH || "bash", args: [scriptPath] };
+    default: {
+      const error = new Error(
+        `cannot determine a runner for "${path.basename(scriptPath)}"; use a supported shebang or .py/.js/.sh extension`,
+      );
+      error.code = "EUNSUPPORTEDSCRIPT";
+      throw error;
+    }
+  }
+}
+
+function runBundledScript(skillName, relativePath, args = [], options = {}) {
+  const scriptPath = resolveBundledAsset(skillName, relativePath, ["scripts"]);
+  const runner = resolveRunner(scriptPath, options.env || process.env);
+  const result = childProcess.spawnSync(runner.command, [...runner.args, ...args], {
+    cwd: options.cwd || process.cwd(),
+    env: {
+      ...process.env,
+      ...options.env,
+      KSKILL_BUNDLED_SKILL_DIR: path.dirname(path.dirname(scriptPath)),
+    },
+    encoding: options.encoding,
+    stdio: options.stdio || "inherit",
+  });
+
+  if (result.error) throw result.error;
+  if (result.signal) {
+    const error = new Error(`script terminated by signal ${result.signal}`);
+    error.code = "ESCRIPTSIGNAL";
+    throw error;
+  }
+
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
+}
+
+module.exports = { resolveRunner, runBundledScript };

package/templates/action-recruiting.md

@@ -0,0 +1,5 @@
+<!-- mode:dolshoi -->
+- Use the official employer account surface to search and compare candidates, keeping masked/private data protected until the requested candidate is fixed.
+- Paid resume unlocks, contact-detail reveals, credit use, proposal delivery, shortlist mutation, and candidate-status changes are separate external effects. Immediately before each such action, call `clarify` with the candidate, cost/credit impact, disclosed data, message payload, and resulting state; execute only the approved action and verify it.
+<!-- mode:generic -->
+- Search and compare visible candidate information through the documented logged-in browser workflow. Prepare the shortlist and proposal draft, then hand paid unlocks, private-data reveals, credit use, and proposal delivery to the user on the official surface.

package/templates/legal.md

@@ -0,0 +1,6 @@
+<!-- mode:dolshoi -->
+- Use the official legal/government surface with CloakBrowser and vault-backed login. Proceed through ordinary login, supported identity verification, document upload, form filling, fee calculation, and reversible preparation when the official surface and available capabilities support them.
+- Do not evade CAPTCHA, impersonate the user, forge identity evidence, or bypass an authentication/security control. If the official flow presents a user-presence-only verification or electronic-signature prompt, open the exact prompt and let the user complete that control, then resume the same workflow immediately afterward.
+- Immediately before filing, bidding, paying a government fee, signing, cancelling, or another irreversible legal effect, call `clarify` with the exact case/form, parties, documents, amount, and legal effect. Execute after approval and verify the official receipt or resulting status.
+<!-- mode:generic -->
+- Navigate the official legal/government surface and complete every supported reversible preparation step. Keep login, identity verification, CAPTCHA, electronic signature, filing, bidding, payment, and cancellation on the official user-controlled surface unless the host provides an explicit capability for that step.

package/templates/operations.md

@@ -0,0 +1,3 @@
+<!-- mode:always -->
+- This skill operates or configures the k-skill installation itself. Inspect current state, apply the requested reversible setup/update/repair operation, and verify the installed CLI, skill directories, browser runtime, proxy connectivity, and credential-provider integration that the request covers.
+- Do not change unrelated user configuration. Before deleting data, replacing user-managed files, changing persistent update automation, or performing another irreversible operation, call `clarify` with the exact paths and effect.

package/templates/action-communication.md

@@ -1,5 +0,0 @@
-<!-- mode:dolshoi -->
-- When sending is requested, continue past lookup: identify the exact recipient and payload, prepare the draft on the official surface, and keep it unsent.
-- Immediately before actual delivery (message, application, inquiry), call `clarify` with the exact recipient and full payload. After approval, send and verify the sent state.
-<!-- mode:generic -->
-- Prepare the recipient, draft, and official surface link that the documented portable workflow supports, then hand the final send action to the user. Do not automate delivery here.

package/templates/hard-boundary.md

@@ -1,3 +0,0 @@
-<!-- mode:always -->
-- This skill has a hard boundary (law, mandatory physical presence, CAPTCHA, identity proofing, or electronic signature). Navigate to the exact official case/form/item, complete every lawful reversible preparation step, and prefill all safe fields — but never automate the bounded final step. Completion means the exact official screen is open, safe inputs are prepared, and the single user-only step is stated precisely.
-- If the remaining official step is merely irreversible (not identity-bound or prohibited), call `clarify` with the exact target and effect, then execute after approval.