# What Is the k-skill Project? A Complete Guide to AI Agent Skills for Korean Tasks

> Explore the k-skill project, a modular skill ecosystem for AI agents. Enhance capabilities for Korean automation tasks like booking transport, querying data, and document handling.

- Repository: [NomaDamas/k-skill](https://github.com/NomaDamas/k-skill)
- Tags: getting-started
- Published: 2026-08-04

---

**The k-skill project is a modular skill ecosystem that equips AI agents like Claude Code and Open Code with ready-to-use capabilities for Korean-focused automation tasks, from booking transportation to querying public data and handling documents.**

The **k-skill** repository, developed by NomaDamas, solves a specific problem: AI coding assistants need concrete, localized tools to interact with Korean services. Rather than hard-coding integrations, k-skill provides a **plug-and-play architecture** where each capability is packaged as a self-contained skill that any compatible agent can discover and execute.

## Core Architecture: Three Building Blocks

The project organizes functionality around three interconnected layers. Understanding these components clarifies how k-skill delivers Korean-specific automation without forcing users to manage API keys or browser drivers manually.

### Skill Packages: Self-Contained Capabilities

Every skill lives in its own top-level folder—`zipcode-search/`, `korean-patron-search/`, `kstartup-search/`, and others. Each follows an identical schema with three required files:

- **[`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json)** — declares inputs, outputs, required login state, and runtime dependencies
- **[`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md)** — human-readable usage instructions the CLI renders for users
- **[`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md)** — minimal front-matter the core CLI consumes at runtime

This modular design means adding a new capability (like checking KBO baseball results or finding nearby public restrooms) requires creating one folder without touching existing code. The [`kstartup-search/skill.json`](https://github.com/NomaDamas/k-skill/blob/main/kstartup-search/skill.json) demonstrates this structure, specifying required parameters and whether user authentication is needed.

### Unified CLI: The Agent Interface

The `@nomadamas/k-skill` npm package exposes three primary commands that bridge AI agents to individual skills:

```bash

# Discover available capabilities

npx -y @nomadamas/k-skill@0 list

# Retrieve human-readable instructions for a specific skill

npx -y @nomadamas/k-skill@0 instruct zipcode-search

# Execute a skill with arguments

npx -y @nomadamas/k-skill@0 exec zipcode-search scripts/zipcode_search.py \
    -- --address "강남구 테헤란로 123"

```

The CLI handles runtime resolution automatically: checking whether a skill needs browser automation, proxy access, or credential vaulting before launching the appropriate helper. Installation and full CLI documentation appear in [`docs/install.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/install.md).

### Proxy and Runtime Infrastructure

Two supporting packages eliminate common friction points for AI agent integration:

| Component | Location | Function |
|-----------|----------|----------|
| **k-skill-proxy** | `packages/k-skill-proxy/` | HTTP gateway for public APIs requiring keys; shields users from secret management |
| **k-skill-browser-runtime** | `packages/k-skill-browser-runtime/` | Portable CDP/Playwright-based browser for scraping sites without stable APIs |

The proxy is particularly significant: most free Korean government and commercial APIs require registration and key management. By routing these through `k-skill-proxy`, end users interact with simplified interfaces while the hosted service handles authentication. Only skills explicitly requiring personal accounts (booking systems, member-only services) ask users for credentials via the `k-skill-setup` helper.

## Technical Implementation Details

### Dual-Language Runtime

The project leverages **Node.js ≥ 18** for CLI performance and **Python** for tasks relying on established libraries. Representative examples from the source:

**Python helper** ([`zipcode-search/scripts/zipcode_search.py`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/scripts/zipcode_search.py)): queries the official Korea Post API, returning both numeric postal codes and romanized English addresses.

**Node helper** ([`korean-character-count/scripts/korean_character_count.js`](https://github.com/NomaDamas/k-skill/blob/main/korean-character-count/scripts/korean_character_count.js)): analyzes UTF-8 byte counts, visible characters, and line breaks for Korean text processing.

This language-agnostic approach selects the optimal tool per task rather than forcing uniformity.

### Credential Management Strategy

The architecture minimizes secret exposure through tiered access:

1. **No credentials required** — majority of skills use the hosted proxy for public APIs
2. **Proxy-mediated access** — free tier APIs with key requirements
3. **User-provided secrets only when necessary** — login sessions, OAuth tokens for personal account actions

The `k-skill-setup` skill guides users through acquiring and configuring any required credentials, stored securely for subsequent CLI invocations.

### Release Automation

Versioning operates on dual tracks:

- **Node packages**: managed via Changesets with `npm run ci` validation in CI
- **Python packages**: managed via release-please

This separation respects the distinct ecosystems while maintaining synchronized capability releases.

## Key Files for Understanding k-skill

| File Path | Purpose |
|-----------|---------|
| [`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md) | Project overview, installation, complete skill inventory |
| [`docs/install.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/install.md) | CLI setup, environment configuration, usage patterns |
| [`packages/k-skill-proxy/README.md`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/README.md) | Proxy architecture and API coverage details |
| [`packages/k-skill-browser-runtime/README.md`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-browser-runtime/README.md) | Browser automation implementation and requirements |
| [`kstartup-search/skill.json`](https://github.com/NomaDamas/k-skill/blob/main/kstartup-search/skill.json) | Exemplar skill manifest showing schema structure |
| [`kstartup-search/instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/kstartup-search/instruction.md) | Template for human-readable skill documentation |
| [`kstartup-search/SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/kstartup-search/SKILL.md) | Runtime metadata assembly instructions |

## Summary

- **k-skill** provides ready-made capabilities for AI agents to perform Korean-specific tasks without custom integration work
- **Modular skill packages** ([`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json), [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md), [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md)) enable independent development and deployment of new capabilities
- **Unified CLI** (`@nomadamas/k-skill`) offers consistent discovery, instruction, and execution interfaces across all skills
- **Proxy and browser runtime** layers abstract API authentication and web scraping complexity from end users
- **Dual Node/Python implementation** selects optimal tools per task while maintaining single-package consumption

## Frequently Asked Questions

### What AI agents are compatible with k-skill?

Any agent supporting MCP (Model Context Protocol) or capable of executing CLI commands can use k-skill. The repository explicitly mentions **Claude Code** and **Open Code** as primary targets, but the standardized command interface (`k-skill list`, `instruct`, `exec`) works with any system that can spawn subprocesses and parse JSON output.

### Do I need API keys to use k-skill skills?

Most skills require **no user-managed API keys**. The `k-skill-proxy` service handles authentication for public APIs that normally require registration. You only provide personal credentials when a skill interacts with services requiring your specific account—booking trains, accessing member-only data, or posting on your behalf.

### How do I add a new skill to k-skill?

Create a new folder at repository root with the three required files: [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) (declare interface), [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) (document usage), and [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) (runtime metadata). Include helper scripts in a `scripts/` subdirectory. Follow the schema established in `kstartup-search/` and validate with `npm run ci` before submitting.

### What Korean services does k-skill currently support?

Per the source analysis, supported capabilities include **zipcode lookup**, **K-Startup company search**, **KBO baseball results**, **public restroom finder**, **Korean text analysis**, **patron search**, and **train schedule queries** via `SRTrain` integration. The [`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md) provides the authoritative current listing as the project expands.