k-skill-setup

k-skill Setup

Purpose

完成全套 k-skill 安裝後，處理共用的後續設定工作。

• 取得憑證（Agent Vault 或預設 secrets.env）
• 確認執行階段（Runtime）環境變數
• 選項：自動化定期檢查更新
• 選項：確認 GitHub Star 意願，並在獲得同意後執行

此 Skill 的基本原則：

• 若缺少 Secret，明確告知使用者所需的變數名稱
• 依據憑證解析順序（Credential resolution order）取得憑證
• 若缺少必要的套件，優先嘗試全域安裝，而非尋求替代實現方案
• 涉及 cron、launchd、schtasks、gh 等持久化設定或變更外部狀態的操作，切勿自動執行，必須先取得使用者同意
• 僅在使用者明確同意時，才執行 GitHub Star

Credential resolution order

所有需要憑證的 Skill 皆遵循以下優先順序：

1. 若已存在於環境變數中，直接使用。
2. 若 Agent 正使用獨立的 Secret Vault（如 1Password CLI、Bitwarden CLI、macOS Keychain 等），可從中取出並注入至環境變數。
3. ~/.config/k-skill/secrets.env（預設備用方案／Fallback）— 純文字 dotenv 檔案，權限設為 0600。
4. 若皆未設定，詢問使用者並儲存至上述第 2 或第 3 項。

儲存至預設路徑僅作為備用機制（Fallback），非強制要求。

Standard file location

• Secret 檔案（預設 Fallback）：~/.config/k-skill/secrets.env

Install

本 Skill 預設在完成全套 k-skill 安裝後執行。

範例：

npx --yes skills add <owner/repo> --all -g

安裝完成後，調用本 Skill 繼續進行下述的 Setup 設定步驟。

Setup steps

1. Create the default secrets file (if no vault is in use)

當 Agent 未使用獨立 Vault 時，建立預設的 Fallback 檔案。

mkdir -p ~/.config/k-skill
cat > ~/.config/k-skill/secrets.env <<'EOF'
KSKILL_SRT_ID=replace-me
KSKILL_SRT_PASSWORD=replace-me
KSKILL_KTX_ID=replace-me
KSKILL_KTX_PASSWORD=replace-me
KSKILL_FORESTTRIP_ID=replace-me
KSKILL_FORESTTRIP_PASSWORD=replace-me
LAW_OC=replace-me
KIPRIS_PLUS_API_KEY=replace-me
AIR_KOREA_OPEN_API_KEY=replace-me
KSKILL_PROXY_BASE_URL=
EOF
chmod 0600 ~/.config/k-skill/secrets.env

詢問使用者以填入實際數值。

首爾地鐵到站資訊、首爾即時擁擠度查詢、首爾 따릉이 (Ttareungyi) 即時單車租賃站查詢、韓國天氣、細懸浮微粒 (PM2.5/미세먼지)、漢江水位、加油站油價、生活垃圾排放資訊查詢、學校營養午餐菜單查詢、藥品安全檢查、食品安全檢查等功能，若將 KSKILL_PROXY_BASE_URL 留空，將預設使用官方託管路徑 (k-skill-proxy.nomadamas.org)。僅在自行託管 Proxy (Self-host proxy) 時才需填寫 KSKILL_PROXY_BASE_URL。

韓國法規檢索功能會經由預設 Hosted Proxy (k-skill-proxy.nomadamas.org) 的 /v1/korean-law/... 端點 (Endpoint)，因此使用者端無需設定 LAW_OC。僅自建 Self-host Proxy 的管理者才需在伺服器端填寫環境變數 LAW_OC（可至 https://open.law.go.kr 免費申請）。

韓國不動產實際交易價查詢會經由預設 Hosted Proxy (k-skill-proxy.nomadamas.org)，因此使用者端無需設定 DATA_GO_KR_API_KEY。

韓國股票資訊查詢會經由預設 Hosted Proxy (k-skill-proxy.nomadamas.org)，因此使用者端無需設定 KRX_API_KEY。僅自建 Self-host Proxy 的管理者需使用伺服器端的 KRX_API_KEY 環境變數。

圖書館圖書查詢會經由預設 Hosted Proxy (k-skill-proxy.nomadamas.org)，因此使用者端無需設定 DATA4LIBRARY_AUTH_KEY。僅自建 Self-host Proxy 的管理者需使用伺服器端的 DATA4LIBRARY_AUTH_KEY 環境變數。

生活垃圾排放資訊查詢會調用 k-skill-proxy 的 /v1/household-waste/info 路由，並由 Proxy 伺服器注入與管理 serviceKey (DATA_GO_KR_API_KEY)，因此使用者端無需設定 DATA_GO_KR_API_KEY。

學校營養午餐菜單查詢會調用 k-skill-proxy 的 /v1/neis/school-search 與 /v1/neis/school-meal，且 KEDU_INFO_KEY 僅留存於 Proxy 伺服器端，使用者端無需設定。

圖書館圖書查詢會調用 k-skill-proxy 的 /v1/data4library/* 路由，且 DATA4LIBRARY_AUTH_KEY 僅留存於 Proxy 伺服器端，使用者端無需設定。

尋找附近最便宜加油站功能會經由預設 Hosted Proxy，因此使用者端無需設定 OPINET_API_KEY。

藥品安全檢查會調用 k-skill-proxy 的 /v1/mfds/drug-safety/lookup 路由，且 DATA_GO_KR_API_KEY 僅由 Proxy 伺服器注入與管理，使用者端無需設定。

食品安全檢查會調用 k-skill-proxy 的 /v1/mfds/food-safety/search 路由，且 DATA_GO_KR_API_KEY 與可選的 FOODSAFETYKOREA_API_KEY 僅由 Proxy 伺服器注入與管理，使用者端無需設定。

創業振興院 K-Startup 查詢會調用 k-skill-proxy 的 /v1/kstartup/* 路由，且 ServiceKey (DATA_GO_KR_API_KEY) 僅由 Proxy 伺服器注入與管理，因此一般查詢使用者端無需密鑰。僅在進行 --direct 直接調用時，才需填寫 KSKILL_KSTARTUP_API_KEY。

韓國專利資訊檢索在搭配 KIPRIS Plus Open API 路徑使用時，需填寫 KIPRIS_PLUS_API_KEY。Helper 會讀取此數值並在實際請求中作為 ServiceKey 查詢參數 (Query parameter) 傳送。直接貼上從公共數據門戶 (Public Data Portal) 複製的 Percent-encoded key 亦可使用。

Missing secret response template

當認證類 Skill 缺少所需數值時，應依據憑證解析順序 (Credential resolution order) 進行取得。

所需變數範例：

• SRT: KSKILL_SRT_ID, KSKILL_SRT_PASSWORD
• KTX: KSKILL_KTX_ID, KSKILL_KTX_PASSWORD
• 自然休養林空房查詢: KSKILL_FORESTTRIP_ID, KSKILL_FORESTTRIP_PASSWORD
• 韓國法規檢索: 使用者端無需 Secret（使用預設 Hosted Proxy，僅管理者需 LAW_OC）
• 韓國不動產實際交易價查詢: 使用者端無需 Secret（使用預設 Hosted Proxy）
• 韓國專利資訊檢索: KIPRIS_PLUS_API_KEY
• 韓國股票資訊查詢: 使用者端無需 Secret（使用預設 Hosted Proxy，僅管理者需 KRX_API_KEY）
• 生活垃圾排放資訊查詢: 使用者端無需 Secret（serviceKey 由 Proxy 伺服器注入，調用時必須包含 pageNo=1 與 numOfRows=100）
• 學校營養午餐菜單查詢: 使用者端無需 Secret（KEDU_INFO_KEY 僅存於 Proxy 伺服器）
• 圖書館圖書查詢: 使用者端無需 Secret（DATA4LIBRARY_AUTH_KEY 僅存於 Proxy 伺服器）
• 藥品安全檢查: 使用者端無需 Secret（DATA_GO_KR_API_KEY 僅存於 Proxy 伺服器）
• 食品安全檢查: 使用者端無需 Secret（DATA_GO_KR_API_KEY 與選擇性 FOODSAFETYKOREA_API_KEY 僅存於 Proxy 伺服器）
• 創業振興院 K-Startup 查詢: 使用者端無需 Secret（DATA_GO_KR_API_KEY 僅存於 Proxy 伺服器；僅使用 --direct 調用時需 KSKILL_KSTARTUP_API_KEY）
• 尋找附近最便宜加油站: 使用者端無需 Secret（使用預設 Hosted Proxy）
• 首爾地鐵: 使用者端無需 Secret（使用預設 Hosted Proxy，僅管理者需 SEOUL_OPEN_API_KEY）
• 首爾即時擁擠度: 使用者端無需 Secret（使用預設 Hosted Proxy，僅管理者需 SEOUL_OPEN_API_KEY）
• 韓國天氣: 使用者端無需 Secret（使用預設 Hosted Proxy，僅管理者需 KMA_OPEN_API_KEY）
• 使用者位置細懸浮微粒查詢: KSKILL_PROXY_BASE_URL 或 AIR_KOREA_OPEN_API_KEY

切勿僅因 Secret 留空，就自動改選其他服務或非官方的繞道途徑。

2. Verify runtime environment

bash scripts/check-setup.sh

3. Offer scheduled update checks

設定完成後，主動詢問使用者是否需要自動化定期檢查更新。若不需要則跳過。

基本原則：

• 預設僅建議「檢查更新」，而非自動安裝更新
• 未取得同意前，不得套用任何具持久性的系統變更 (crontab、launchd、schtasks)
• 預設檢查指令為 npx --yes skills check
• 僅在使用者明確要求「自動更新」時，才另外提供基於 npx --yes skills update 的排程建議

macOS / Linux 範例：

mkdir -p ~/.config/k-skill/bin ~/.config/k-skill/logs
cat > ~/.config/k-skill/bin/check-skill-updates.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
mkdir -p "$HOME/.config/k-skill/logs"
{
  date '+[%Y-%m-%d %H:%M:%S]'
  npx --yes skills check
  printf '\n'
} >> "$HOME/.config/k-skill/logs/skills-check.log" 2>&1
EOF
chmod +x ~/.config/k-skill/bin/check-skill-updates.sh
(crontab -l 2>/dev/null; echo "0 9 * * * $HOME/.config/k-skill/bin/check-skill-updates.sh") | crontab -

Windows 範例：

New-Item -ItemType Directory -Force "$HOME/.config/k-skill/bin" | Out-Null
New-Item -ItemType Directory -Force "$HOME/.config/k-skill/logs" | Out-Null
@'
npx --yes skills check >> "$HOME/.config/k-skill/logs/skills-check.log" 2>&1
'@ | Set-Content "$HOME/.config/k-skill/bin/check-skill-updates.cmd"
schtasks /Create /SC DAILY /TN "k-skill-update-check" /TR "\"$HOME/.config/k-skill/bin/check-skill-updates.cmd\"" /ST 09:00 /F

設定完成後，簡要提示日誌檔案位置：

• ~/.config/k-skill/logs/skills-check.log

4. Offer GitHub starring with explicit consent

設定流程的最後，簡短詢問使用者如下：

要幫您在 k-skill 儲存庫 (NomaDamas/k-skill) 點選 GitHub Star 嗎？
若您同意，將透過 `gh` 直接處理；若不需要則跳過。

規則：

• 未取得使用者明確同意前，切勿執行 gh repo star
• 若未安裝 gh 或未通過驗證，僅提供安裝與登入指引，切勿自動繞道執行
• Star 的目標儲存庫為 NomaDamas/k-skill

若已同意且 gh auth status 狀態正常：

gh repo star NomaDamas/k-skill

成功後簡短通知完成即可。

Completion checklist

• ~/.config/k-skill/secrets.env 存在且權限為 0600（或 Agent 正使用自身的 Vault 管理憑證）
• 已設定所需的環境變數
• 僅在使用者同意時，才設定自動檢查更新或 GitHub Star

Notes

• 基本流程為「安裝全套 Skill → 執行此 Setup Skill → 使用各項個別功能」
• 儲存庫內切勿存放 Secret 檔案