k-skill：把韩国人的日常生活搬进 AI 编码代理的 133 个技能包

133 个技能 · 面向韩国本地生活 · 支持 Claude Code / Codex / OpenCode / OpenClaw 仓库地址：https://github.com/NomaDamas/k-skill

一、一个让人哭笑不得的痛点

想象一下这个场景：你在首尔，晚上十点，想知道明天首尔的气温到底是 3 度还是 0 度。

对于普通人，打开气象网站点两下的事；但对于一个 AI 编码代理来说，它必须联网搜索、解析韩文网页、绕过可能存在的反爬机制，最后给你一个大概率正确但完全无法溯源的答复。真正让人抓狂的是——它连"罗生门"气象数据到底该信谁都判断不了。

k-skill 的作者 Jeffrey (Dongkyu) Kim 在 2026 年 3 月 24 日创建了这个仓库，理由朴素得近乎直白：韩国人的日常生活被锁在一个个彼此隔离的政府门户、电商平台和本地服务里，而这些服务基本都不提供中文或英文可用的结构化接口。于是这个仓库做了一件事——把这些服务一个个封装成 AI 代理可以直接调用的技能（Skill）。

7 个半月后，它拿到了 8226 个 Star、996 个 Fork、49 位贡献者和超过 1223 次提交。这在"工具类仓库"里是一个相当罕见的速度。

二、它到底长什么样：一个"技能包"的全貌

仓库根目录一眼望过去是 133 个以连字符命名的文件夹：korea-weather、real-estate-search、korean-law-search、k-dart、seoul-subway-arrival、toss-investment、nhis-care-checkup-search……每个文件夹里通常只有三个文件：

• SKILL.md —— 给代理读的元信息（何时触发、需要什么）
• instruction.md —— 真正的操作手册，分步骤说明调用哪个 API、怎么解析返回
• skill.json —— 声明式的技能描述

这个结构是 Agent Skills 规范下的标准形态，和 Anthropic 官方的 skill 格式兼容，因此能直接装进 Claude Code、Codex、OpenCode 等主流编码代理。

图：项目在 README 中展示了 BC카드 等真实机构的配合。

三、类比理解：它是一套"韩国民生活 API 字典"

如果把常见的 AI 工具比作"会说话的百科全书"，那 k-skill 更像是一本写给机器看的韩国生活办事手册。

区别在于：百科全书告诉你"首尔 11 月平均气温 8 度"，办事手册告诉你"要查首尔逐小时实况，走 airkorea.js 这个代理路由；湿度字段在 humidity，风速要乘 0.2 换算成 m/s"。前者给结论，后者给可执行的路径。

133 个技能横跨 12 个生活领域，从交通出行（KTX 列车时刻表、市内巴士座位预订、首尔地铁实时到站、共享单车可用桩、快递查询）、不动产（实成交价、政府公示价、청약 积分与保证金、法拍公告）、法律与公共（韩国法令检索、专利检索、国会议案表决）、事业与税务（사업자등록 真伪核查、金融委法人信息、税务欠缴名单公开）、政府采购（나라장터 发包计划、招标公告）、招聘（잡코리아/사람인 人才库）、金融投资（KRX 股价、DART 电子 Disclosure 14 类接口、KOSIS 统计、央行 ECOS 宏观指标、晨间多资产简报）、医疗健康（急诊床位、医保长期护理机构、药品与食品安全召回）、购物比价（Coupang、Naver Shopping、다나와、Olive Young）到生活杂项（韩语拼写检查、萨满算命、麻将战报、棒球 KBO 赛果），几乎覆盖了一个韩国人从起床到睡觉会碰到的全部数字服务。

四、技术架构：三层结构，各司其职

仓库采用 npm workspaces 单仓多包结构，packages/ 下有 31 个子包，核心是三个：

1. k-skill-cli（npm 包 @nomadamas/k-skill，v0.10.4） 安装与运行入口。npx skills add NomaDamas/k-skill --all -g 一次性把 133 个技能铺到全局。它做的事不是"代理 API"，而是 运行时感知组装：探测当前宿主是 Claude Code 还是 Codex，生成对应的 skill 指令路径、把 helper 脚本落到合适位置，再维护一份更新通道。它还内置了用量统计（analytics.js + analytics-policy.json），可通过 KSKILL_ANALYTICS_DISABLED=1 关闭，且声明不采集命令参数原文、文件内容与认证信息。

2. k-skill-proxy（v0.12.0，Fastify 5，AGPL-3.0-only） 这是整个项目的技术心脏。一个 18.9 万字节的 server.js 加上 40 多个按领域拆分的路由模块（kakao-map.js、naver-shopping.js、lh-notice.js、g2b-order-plan.js、vworld.js、mfds.js…），对那些没有官方 API、只有网页数据面的韩国政府门户做 反爬绕过 + HTML/JSON 解析 + 数据归一化。公共实例部署在 k-skill-proxy.nomadamas.org，配套一份独立的隐私政策页；技能侧只需把 HTTP 请求丢过去即可，因此使用者本地不必持有任何韩国服务凭据。

3. infra/k-skill-proxy-dashboard 用 docker-compose 编排的 Grafana + Loki + Promtail 三件套，把代理的 JSON 日志做成按端点的调用量看板，只对宿主机 127.0.0.1:3200 暴露、再由 Cloudflared 隧道对外。

辅助层：k-skill-rhwp 负责韩国 HWP（한글 문서）格式的生成与解析——这是韩国政务文件的实际流通格式，也是纯 Python 生态基本没有覆盖的空白；k-skill-browser-runtime 提供浏览器兜底能力，处理必须走 JS 渲染才能拿到的页面；packages/ 下另有 28 个技能私有的 Node 小包。

整个仓库的语言构成是 JavaScript 289.7 万字节 + Python 262.5 万字节 + TypeScript 26.3 万字节，Node.js ≥ 18（部分包要求 ≥ 20）、KTX 时刻表 helper 需要 Python 3.11+ 与 uv。

五、上手门槛：装容易，深度用需要一点耐心

门槛分两档。

轻量档（多数人用这个）：装 Node.js 18+ 和 npx，跑一条 npx --yes skills add NomaDamas/k-skill --all -g 即可，不需要服务器、不需要 API Key、不需要 Docker。这也是项目刻意追求的形态——README 里反复强调"추가 클라이언트 API 레이어는 불필요합니다"（不需要额外的客户端 API 层）。

自托管档：想把代理跑在自己机器上，需要 Node.js 20、构建 packages/k-skill-proxy/Dockerfile（多阶段构建，node:20-alpine，最终镜像只保留生产依赖并以非 root 的 node 用户运行，监听 8080），再配好 Grafana 栈。这条路还牵涉 AGPL-3.0 授权，商用前需要过法务。

上线路径的成熟度值得点赞：k-skill-setup 这个技能会主动询问你要装哪几个、装到哪些宿主；仓库有 install.md、setup.md、security-and-secrets.md、runtime-action-audit.md、usage-analytics.md、sources.md（4.9 万字节的数据源清单）等 30 多篇文档，还有 docs/superpowers/specs 下的设计规格。

六、争议与局限：不回避问题

第一，语言与地域的排他性。 这是一个纯韩语、纯韩国本地服务的集合。中文用户和英文用户拿到的价值几乎为零——它的 133 个技能里没有一个能直接服务中国或国际场景。这不是缺陷，但决定了它的用户盘子有天然天花板。

第二，代理层的合规灰区。 为了拿到数据，k-skill-proxy 大量采用网页抓取与解析的方式绕过官方接口。虽然项目在 README 中明确标注了" railroad 统一时刻表是查询专用""不会执行登录、预订、预约、支付、取消"，并对就业信息等敏感场景设置了短名单与付费墙前的筛选，但整体仍处在"抓取公开页面"与"违反服务条款"之间的擦边地带。公共代理实例的稳定性也直接决定所有下游技能的可用性——作者用一个 fetch-with-retry.js 来兜底，这本身就说明了上游经常不稳。

第三，许可不统一。 仓库根目录是 MIT，但 packages/k-skill-proxy 与 dashboard 是 AGPL-3.0-only，korean-privacy-terms 等技能又是 Apache-2.0 上游的 thin wrapper。多许可混装在商业使用时会带来实际麻烦。

第四，维护者集中度。 1223 次提交里绝大部分来自 Jeffrey (Dongkyu) Kim 一人，49 位贡献者中真正长期投入的更少。虽然项目用 Changesets 管理多包版本发布、有 GitHub Actions 全流程 CI（lint → typecheck → test → 打包演练），但 bus factor 依然是单点。

第五，数据源随时会变。 政府门户改版一次，某个技能就可能失效。sources.md 记录了每个技能的来源，store-longevity-r2-mirror 甚至专门做了 R2 镜像来对抗"长尾技能的数据源消失"。这是聪明的做法，但也说明问题的真实存在。

七、行业意义：本地化 AI 的"最后一公里"

k-skill 揭示了一个正在成型的趋势：通用大模型的能力已经足够，真正的稀缺性在于"最后一公里"的地方性连接。

当一个代理能在 3 秒内告诉你"这套房的政府公示价是多少、这套房最近三个月真实成交价区间是多少、附近有没有在管的公共租赁房源"，它提供的不只是信息，而是把一个普通人原本要开五个网站、填四张表格才能拼出来的答案压缩成了一句话。

它选择的路径也很聪明——不与平台竞争，而是做平台的 API 适配层。既不与 Coupang 抢电商，也不与 Toss 抢金融，只在"AI 代理需要什么"这个维度上提供一层薄薄的封装。这种定位让它在极短时间内获得了远超其技术含量的社区关注。

从 2026 年 3 月的 0 星到 8 月的 8000+ 星，k-skill 证明了本地化 AI 工具的爆发力。而它留下的更大启示是：任何一个国家/地区都可能长出一个自己的 "k-skill"——把本国国民每天要打交道的那些政府与商业服务，逐个变成 AI 代理可以调用的技能。谁先把这个"最后一公里"铺完，谁就在本地 AI 生态里占据了入口。

八、给开发者的实用建议

如果你在韩国：这是目前最完整的韩国生活代理工具包，装全量技能后配合 korea-weather、real-estate-search、seoul-subway-arrival 这类高频技能，能明显改变日常效率。

如果你在做 Agent 生态：这个仓库是最值得研究的"规模化技能工程"样本。133 个技能如何保持一致性（generate-skill-stubs.js、generate-skill-list.js 自动生成骨架）、如何做数据源溯源、如何在代理与真实世界之间架一层 HTTP 中枢——这些工程实践比业务本身更有迁移价值。

如果你是中国开发者：它的架构可以直接借鉴。中文语境下的目标是"把 12306、医保、公积金、公积金提取、相亲、抢票、政务办事"变成技能包——同样的问题，同样的解法。

---

数据快照：8226 Star / 996 Fork / 70 Open Issues / 49 位贡献者 / 1223 次提交 · 主语言 JavaScript · 许可证 MIT（代理组件 AGPL-3.0） · 创建于 2026-03-24，最近推送 2026-11-01