k-skill 딥다이브
— 한국 서비스 95개를 AI 에이전트에게 시키는 '스킬 모음집'

1프로젝트 한줄 요약

"한국 서비스 95개를 AI 에이전트가 대신 처리하게 해주는 사용 설명서 묶음"입니다. 우리가 쓰는 코레일·당근마켓·쿠팡·정부24·홈택스 같은 서비스는 전부 한국어이고, 공식 API가 없거나 인증이 까다롭습니다. ChatGPT·Claude 같은 글로벌 LLM은 이런 한국 특화 서비스를 "어떻게 다뤄야 하는지"를 모릅니다. k-skill은 각 서비스마다 "이 사이트는 이렇게 접근하면 된다"는 레시피를 문서(SKILL.md)와 코드로 만들어 에이전트에게 쥐여 줍니다. 그러면 에이전트가 그 문서를 읽고 직접 명령어를 실행해 일을 끝냅니다.

이름 'k-skill'은 'Korea(한국) + skill(스킬)'입니다. 핵심은 한국 특화 + Agent Skills 표준 + 경량 실행이라는 조합입니다. 만든 곳은 한국 AI 오픈소스 그룹 NomaDamas(RAG 평가 프레임워크 AutoRAG로 유명)이고, 라이선스는 MIT(누구나 자유 사용)입니다. Claude Code 사용자는 명령 한 줄(/plugin install)로 95개 스킬을 통째로 설치할 수 있습니다.

2왜 주목받는가

2026년 들어 Claude Code·Codex·Gemini CLI 같은 에이전트형 도구가 대중화되면서, "스킬(skill)"이 가장 뜨거운 키워드가 됐습니다. TrendShift 트렌딩 상위권이 온통 '-skill' 레포로 채워질 정도입니다. 그 흐름 속에서 k-skill은 "한국인이라면 무조건 한 번은 쓸 일이 생긴다"는 명확한 타깃과, 95개라는 압도적 규모로 한국 AI 커뮤니티에서 화제가 됐습니다.

다른 접근 방식과의 비교

핵심 차별점 셋

3기술 스택 전체 지도

k-skill은 단일 언어 프로젝트가 아니라 Node.js(주력)와 Python이 한 저장소에 공존하는 다언어 모노레포입니다. 루트 package.json은 npm workspaces로 묶여 있고, 릴리스는 @changesets/cli로 자동화됩니다. 런타임 의존성은 의도적으로 최소화되어 있어, 프록시 서버만 fastify 하나에 의존하고 나머지 npm 스킬 패키지는 의존성 0개로 Node 18 내장 fetch만 씁니다.

전체 기술 구성

스킬은 4가지 방식 중 하나로 구현된다

k-skill의 진짜 기술적 묘미는 "스킬마다 구현 방식이 다르다"는 점입니다. 가장 단순한 건 문서만 있는 스킬이고, 복잡한 건 별도 npm 패키지나 프록시 라우트를 갖습니다.

4아키텍처 심화 분석

k-skill의 동작을 한 문장으로 줄이면 이렇습니다. "에이전트가 요청에 맞는 SKILL.md를 골라 읽고, 그 안에 적힌 가장 안정적인 통로(직접 HTTP / 프록시 / MCP)로 한국 서비스를 호출한다." 무거운 미들웨어가 없는 대신, 각 스킬 문서가 "어디로 어떻게 호출하라"는 라우팅 지식을 품고 있는 구조입니다.

① 전체 요청 흐름 — 4갈래 분기

여기서 가장 중요한 설계 원칙은 "키가 필요할 때만 프록시"입니다. 공개 endpoint(예: 부동산 실거래가)는 사용자 컴퓨터에서 직접 호출하고, 공공데이터포털처럼 키가 있어야만 열리는 곳만 프록시를 거칩니다. 유료·개인 계정 API는 프록시 금지입니다. 이 규칙이 프록시 서버의 부하와 책임 범위를 좁게 유지합니다.

② k-skill-proxy — 키 은닉 중계 서버

k-skill-proxy는 Fastify 기반 단일 서버로 Google Cloud Run(asia-northeast1, 서울 근처)에 떠 있습니다. 50개 이상의 /v1/... 라우트를 노출하며, 각 라우트는 upstream별 모듈(airkorea.js, krx-stock.js, kakao-map.js 등)로 분리돼 있습니다. 보안을 위해 허용 목록(allowlist)으로 호출 가능한 upstream 함수를 제한합니다.

// allowlist 예시 — 허용된 upstream 함수만 통과시킨다
const ALLOWED_AIRKOREA_ROUTES = new Map([
  ["MsrstnInfoInqireSvc", new Set([
    "getMsrstnList", "getNearbyMsrstnList", "getTMStdrCrdnt",
  ])],
  ["ArpltnInforInqireSvc", new Set([
    "getMsrstnAcctoRltmMesureDnsty", "getCtprvnRltmMesureDnsty",
  ])],
]);
// 목록에 없는 함수 호출은 거부 → upstream 키 오남용 차단

③ npm 패키지형 스킬 — 직접 HTML/JSON 파싱

로또 확인(lotto-results)은 k-lotto라는 npm 패키지로 구현됩니다. 의존성 없이 Node 내장 fetch만으로 동행복권 공식 endpoint를 직접 호출합니다. 파싱 로직은 별도 파일로 분리하고, 실제 HTML/JSON 샘플을 fixture로 두어 node --test로 회귀 테스트합니다.

// packages/k-lotto/src/index.js (요지)
const LATEST_URL = "https://www.dhlottery.co.kr/lt645/result";
const DETAIL_URL = "https://www.dhlottery.co.kr/lt645/selectPstLt645InfoNew.do";

async function getLatestRound() {
  const html = await fetchText(LATEST_URL);
  return extractLatestRoundFromHtml(html);   // HTML에서 최신 회차 추출
}
async function getDetailResult(round) {
  const url = new URL(DETAIL_URL);
  url.searchParams.set("srchLtEpsd", String(round));
  return normalize(await fetchJson(url.toString())); // 공식 JSON endpoint
}

④ SKILL.md는 "실행 가능한 문서"다

가장 핵심적인 발상입니다. SKILL.md 안에는 설명뿐 아니라 에이전트가 그대로 복붙해 실행할 명령 블록이 들어 있습니다. 로또 스킬의 경우:

# 0단계: 없으면 전역 설치 (다른 구현으로 우회 금지)
npm install -g k-lotto
export NODE_PATH="$(npm root -g)"

# 1단계: 최신 회차 조회
node - <<'JS'
const lotto = require("k-lotto");
lotto.getLatestRound().then((r) => console.log(r));
JS

5디렉토리 구조 해부

저장소 루트에는 스킬 폴더 95개가 평면적으로 나열되고, 그와 별개로 공유 인프라(packages/, scripts/, docs/, .claude-plugin/)가 있습니다. 별도 레지스트리 파일 없이 "최상위에 SKILL.md를 가진 폴더 = 스킬"로 자동 발견하는 구조라, 폴더만 추가하면 곧 스킬이 됩니다.

주목할 점은 같은 스킬이라도 구현은 세 곳에 흩어질 수 있다는 것입니다. 예컨대 미세먼지 스킬은 ① 루트의 fine-dust-location/SKILL.md(에이전트가 읽는 매뉴얼), ② scripts/fine_dust.py(좌표→측정소 변환 등 실행 코드), ③ k-skill-proxy의 /v1/fine-dust/report 라우트(키 은닉 중계)로 구성됩니다. "문서·실행·인프라"가 역할별로 분리된 설계입니다.

6학습 포인트

① Agent Skills 표준 — "AI에게 일을 가르치는 법"

k-skill은 Anthropic Agent Skills 표준(SKILL.md frontmatter)의 대규모 실전 교본입니다. 95개 스킬을 비교하며 읽으면, 좋은 스킬 description(에이전트가 정확히 골라내게 하는 문구), When to use / When not to use의 경계 설정, Done when·Failure modes로 완료/실패를 정의하는 법을 익힐 수 있습니다.

② 키 은닉 프록시 아키텍처 — 보안 설계

k-skill-proxy를 파면 "민감한 키를 클라이언트에 노출하지 않는" 실전 패턴을 배웁니다. Fastify 라우팅, allowlist로 호출 범위 제한, GCP Secret Manager, Cloud Run 배포, /health 스모크 테스트까지 — 작은 코드베이스에 보안 프록시의 정석이 담겨 있습니다.

③ site-agnostic discovery — 안정적인 데이터 통로 찾기

k-skill의 기여 가이드는 "화면 구조를 감으로 고정하지 말라"고 강조합니다. 공식 API → 공개 JSON → RSS/sitemap → 모바일 페이지 순으로 안정적인 입구를 먼저 찾고, 화면 스크래핑은 최후로 미룹니다. 이 방법론은 모든 크롤링·자동화 작업에 그대로 전이됩니다.

④ 모노레포 릴리스 자동화 — Changesets / CI

npm 패키지 24개를 어떻게 일관되게 버전 올리고 배포하는지(Changesets), 프록시가 main 병합 시 어떻게 자동 재배포되는지(GitHub Actions + WIF) 살펴보면, 오픈소스 운영의 자동화 파이프라인을 통째로 배웁니다.

7하드웨어 / 시스템 요구사항

8직접 해볼 수 있는 실습 과제

🟢 입문 Lv.1 · 20분

🟢 입문 Lv.2 · 40분

🟡 중급 Lv.3 · 반나절

🟡 중급 Lv.4 · 하루

🔴 고급 Lv.5 · 주말 프로젝트

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

공식 — 깃허브 NomaDamas/k-skill · 만든 그룹 NomaDamas(AutoRAG 제작) · 라이선스 MIT

설치 — Claude Code: /plugin marketplace add NomaDamas/k-skill → /plugin install k-skill@k-skill · 범용 CLI: npx --yes skills add NomaDamas/k-skill --all -g · Manus.ai: .skill 번들 드래그-드롭. 설치 후 k-skill-setup으로 인증 셋업.

기여·문서 — 저장소의 CONTRIBUTING.md(한국어 소통, PR은 dev 브랜치) · docs/adding-a-skill.md(새 스킬 추가 가이드) · docs/security-and-secrets.md(비밀 관리) · docs/releasing.md(릴리스 자동화).

관련 배경 — Anthropic Agent Skills 개념 · Model Context Protocol(MCP) · 공공데이터포털(여러 스킬의 upstream).