企业官网建设流程全解析

k-skill 架构总览：4 种技能实现类型与仓库目录结构图解

【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill

k-skill 是面向韩国人的 AI Agent 技能集合，把 SRT 列车查询、当근二手交易、Coupang 商品搜索、政府 24 等业务封装成 100+ 个"技能"，让 Claude Code、Codex 等编码 Agent 直接替你跑腿。本文带你一次看懂它的4 种技能实现类型与仓库目录结构，即使你是新手也能快速建立全局认知。

一、k-skill 是什么：把"琐事"交给 AI Agent

k-skill 的核心理念只有一句话：한국인을 위한 스킬 모음집（为韩国人准备的技能合集）。查 SRT/KTX 时刻表、查首尔地铁到站、对比 다나와最低价、查房贷抽签公告……这些原本要打开网页反复点击的事，说一句自然语言就能交给 Agent 完成。

安装只需要一条命令（要求 Node.js 18+）：

npx --yes skills add NomaDamas/k-skill --all -g

安装后每个技能会以/k-skill:<技能名>的命名空间被调用，例如/k-skill:lotto-results。详见安装文档。

二、仓库目录结构图解：技能都住在哪里

打开仓库，你会发现结构非常规律：仓库根目录下的每个文件夹就是一个技能，此外还有几个支撑目录。整体布局如下：

k-skill/ ├── srt-booking/ ← 技能目录（名字 = 技能名），根目录共 100+ 个 │ ├── skill.json ← 元数据单一来源 │ ├── instruction.md ← 技能专属工作流 │ ├── SKILL.md ← 生成物，勿手改 │ ├── scripts/ ← 可选：Python helper │ └── references/ ← 可选：参考资料 ├── packages/ ← npm 工作区：k-skill-cli、k-skill-proxy 等 ├── scripts/ ← 共享 Python 脚本与构建/校验工具 ├── docs/ ← 文档：安装、功能说明、贡献指南 ├── infra/ ← 代理服务器监控栈 ├── python-packages/ ← Python 包发布目录 └── examples/ ← 配置示例（如 secrets.env.example）

几个值得注意的设计：

• 自动发现，无注册表：技能不需要登记，Agent 通过"扫描根目录"就能找到全部技能，这也是为什么根目录能平铺 100+ 个技能文件夹。
• 功能文档与技能一一对应：每个技能都有对应的 docs/features/ 功能文档，例如 docs/features/srt-booking.md，方便按需查阅。
• 贡献规范集中管理：新增或修改技能前，先读贡献指南与新增技能指南。

三、4 种技能实现类型：一份对照表看懂

根据docs/adding-a-skill.md的官方定义，k-skill 的技能共有 4 种实现类型。它们的区别只在于"谁来做实际的活"：

类型 1：纯指令技能 —— 最轻量的"说明书"

技能目录里只放skill.json+instruction.md，Agent 读到指令后自己拼命令执行，不依赖任何额外库或服务器。例如 srt-booking/skill.json 声明了lookupprofile，srt-booking/instruction.md 则描述"只查时刻表与余票、不登录不预约"的边界。

类型 2：npm 包技能 —— 逻辑封装成库

复杂逻辑（解析、计算、接口封装）写在packages/<技能名>/下的 Node.js 工作区里，技能目录只保留说明书，说明书中调用库暴露的 CLI/API。这类包通过 Changesets 流程发布到 npm，见 docs/releasing.md。

类型 3：代理中转技能 —— 密钥不落地

很多免费政府 API 要求注册 Key。为了让普通用户"零配置"，k-skill 用自建的k-skill-proxy在服务端保管上游 Key，客户端只发 HTTP 请求。以 seoul-subway-arrival/instruction.md 为例：它明确写道"用户无需自己申请首尔 OpenAPI key，Key 只存放在代理服务器侧"。代理路由集中在 packages/k-skill-proxy 中维护，只允许免费的只读 API 过代理（该目录采用 AGPL-3.0-only 协议）。

类型 4：Python 脚本技能 —— 跑一个 helper

适合纯文本处理、公开网页表面抓取等场景。技能通过 CLI 统一调度：

npx -y @nomadamas/k-skill@0 exec korean-spell-check scripts/korean_spell_check.py -- --text "..."

scripts/ 目录下还存放着跨技能共享的脚本与校验工具，如 scripts/validate-skills.sh（CI 时自动校验每个技能目录的SKILL.md是否合规）。

四、技能目录的"三件套"：skill.json、instruction.md、SKILL.md

无论哪种类型，每个技能目录都有统一的三件套，这是理解整个架构的钥匙：

1. skill.json—— 唯一数据源。存放 name（必须与目录名一致）、description、profiles（要装配哪些公共能力：lookup / proxy / vault 等）、frontmatter 原文。
2. instruction.md—— 站点专属工作流。只写"这个网站怎么查"：入口、输入输出、fallback 顺序、失败模式，不重复公共规则。
3. SKILL.md—— 生成物。由 scripts/generate-skill-stubs.js 根据前两者自动拼装，不要手动修改；修改 source 后要跑npm run generate:skill-stubs和npm run sync:cli-skills重新同步。

这套"单一数据源 + 生成装配"的设计，让 100+ 个技能能保持完全一致的调用契约，Agent 无需针对每个技能做特殊适配。

五、新手上手路线图

建立架构认知后，建议按这条路线实际走一遍：

1. 安装：按 docs/install.md 全量安装技能。
2. 初始化：运行k-skill-setup技能，确认凭证与环境变量，指南见 docs/setup.md。
3. 挑一个用：从不需要登录的查询类技能入手，比如查天气（korea-weather）或查地铁到站（seoul-subway-arrival）。
4. 想贡献？：先读 CONTRIBUTING.md 和 docs/adding-a-skill.md，选 4 种类型中最贴合你目标技能的一种实现。

掌握"一个目录一个技能、三件套定契约、四种类型分工干活"这三点，你就读懂了 k-skill 的整个架构。接下来不妨翻一翻 README.md 里的能力总表，看看哪个技能能解决你今天的琐事。

【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill