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

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 — declares inputs, outputs, required login state, and runtime dependencies
• instruction.md — human-readable usage instructions the CLI renders for users
• 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 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:

# 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.

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): 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): 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	Project overview, installation, complete skill inventory
docs/install.md	CLI setup, environment configuration, usage patterns
packages/k-skill-proxy/README.md	Proxy architecture and API coverage details
packages/k-skill-browser-runtime/README.md	Browser automation implementation and requirements
kstartup-search/skill.json	Exemplar skill manifest showing schema structure
kstartup-search/instruction.md	Template for human-readable skill documentation
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, instruction.md, 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 (declare interface), instruction.md (document usage), and 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 provides the authoritative current listing as the project expands.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}