How to Use the k-skill API: CLI and HTTP Proxy Methods Explained

The k-skill API provides a unified interface to Korean public data sources through a Fastify-based proxy server that handles authentication, caching, and rate-limiting automatically.

The k-skill API is a collection of thin wrappers around public Korean data services. Built by NomaDamas, it abstracts away the complexity of dealing with diverse upstream APIs by providing a single, consistent interface. Whether you prefer command-line tools or direct HTTP calls, the API normalizes requests, injects secrets securely, and returns sanitized JSON payloads.

Architecture Overview

Understanding how the k-skill API works helps you choose the right integration path. The system consists of three main layers working together.

CLI and Skill Dispatcher

The k-skill CLI resolves skill names to executable scripts or proxy endpoints. When you run a command, it either executes a local helper or forwards the request to the proxy server. This layer is ideal for automation scripts and AI agents that need reliable data access.

Proxy Server Core

The heart of the system lives in packages/k-skill-proxy/src/server.js. This Fastify-based server implements:

• makeConfig – Reads environment variables and builds route configurations
• createMemoryCache – Caches responses keyed by SHA-256 hash of request payload
• buildRateLimiter – Tracks per-IP request counts to prevent abuse
• Normalization helpers – Functions like trimOrNull, parseInteger, and normalizeFineDustQuery ensure valid parameters reach upstream APIs

Each route follows a consistent pattern: normalize parameters, proxy the request with injected credentials, cache successful responses, and return sanitized data.

Hosted vs. Local Deployment

Deployment	URL	Use Case
Hosted proxy	https://k-skill-proxy.nomadamas.org	Quick start, no API keys needed
Local proxy	http://localhost:4020	Development, custom secrets, debugging

The hosted instance at k-skill-proxy.nomadamas.org is maintained by the project operators. It contains pre-configured secrets for most skills, so you can call endpoints immediately without managing credentials.

Method 1: Using the k-skill CLI

The CLI is the recommended approach for agents and automation workflows. It handles skill resolution, argument passing, and output formatting.

Installation and Setup

# Install all k-skill abilities globally (run once)

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

This command downloads skill definitions and helper scripts to your local environment.

Executing a Skill

# Search Korean law using the built-in script

k-skill exec korean-law-search scripts/search_law.py -- --query "민법"

The CLI resolves korean-law-search to its implementation, passes your arguments through, and prints the JSON response. The -- separator ensures flags are forwarded to the skill script rather than consumed by the CLI itself.

Method 2: Direct HTTP Requests to the Hosted Proxy

For applications that need simple HTTP access, call the hosted proxy directly. No API keys required—the proxy injects operator-managed secrets.

Fine Dust Information Endpoint

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/fine-dust/info' \
  --data-urlencode 'regionHint=서울' \
  --data-urlencode 'stationName=종로구청'

This endpoint queries the Air Korea service through proxyAirKoreaRequest, which normalizes parameters, adds the backend API key, and returns standardized air quality data.

Korean Law Search Endpoint

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-law/search' \
  --data-urlencode 'query=민법' \
  --data-urlencode 'pageNo=1' \
  --data-urlencode 'numOfRows=10'

The proxy validates your parameters with normalizeData4LibraryIsbn13-style helpers, contacts open.law.go.kr, and returns a clean JSON envelope with search results.

Method 3: JavaScript/Node.js Integration

Modern applications can consume the k-skill API using standard fetch patterns.

import fetch from 'node-fetch';

async function koreanLawSearch(term) {
  const url = new URL('https://k-skill-proxy.nomadamas.org/v1/korean-law/search');
  url.searchParams.set('query', term);
  url.searchParams.set('pageNo', '1');
  url.searchParams.set('numOfRows', '5');

  const resp = await fetch(url);
  const data = await resp.json();
  console.log(data);
}

koreanLawSearch('민법');

This request flows through the same Fastify pipeline as CLI and curl calls: normalization in normalizeFineDustQuery (or equivalent), rate-limiting via buildRateLimiter, and caching through createMemoryCache.

Method 4: Local Proxy with Custom Secrets

Some skills require user-provided credentials. Run the proxy locally to inject your own API keys.

Setting Up Environment Variables

# Obtain from https://www.data.go.kr/ (Air Korea service)

export AIR_KOREA_OPEN_API_KEY=YOUR_KEY_HERE

Never commit secrets to version control. The proxy reads these via buildConfig in server.js.

Starting the Local Proxy

# Start proxy on default port 4020

node packages/k-skill-proxy/src/server.js

Calling the Local Instance

curl -fsS --get 'http://localhost:4020/v1/fine-dust/info' \
  --data-urlencode 'regionHint=부산' \
  --data-urlencode 'stationName=해운대'

The proxyAirKoreaRequest function injects your AIR_KOREA_OPEN_API_KEY into the request to apis.data.go.kr, keeping your credentials server-side.

Error Handling and Response Format

The k-skill API wraps all errors into a consistent envelope. Functions like isFailureResponse and getSeoulOpenApiSemanticError in server.js ensure you receive predictable error objects:

{
  "error": "UPSTREAM_ERROR",
  "message": "Invalid station name provided",
  "upstream": "AirKorea API returned 400"
}

Successful responses contain the normalized data directly or in a data field, depending on the skill.

Key Source Files and References

File	Purpose
packages/k-skill-proxy/src/server.js	Core Fastify server, normalization, caching, rate-limiting
README.md	Skill catalog and quick-start commands
docs/install.md	CLI installation and k-skill-setup configuration
docs/features/k-skill-proxy.md	Hosted proxy documentation and security details
docs/setup.md	Credential resolution order and environment setup
packages/k-skill-proxy/src/airkorea.js, korean-law.js	Individual upstream API implementations

Summary

• CLI method: Install with npx skills add NomaDamas/k-skill --all -g, then run k-skill exec <skill-name>

• Hosted proxy: Call https://k-skill-proxy.nomadamas.org/v1/{endpoint} with URL-encoded parameters—no API keys needed

• JavaScript integration: Standard fetch to hosted endpoints with automatic caching and rate-limiting

• Local proxy: Export secrets like AIR_KOREA_OPEN_API_KEY, run server.js locally, call localhost:4020

• Core architecture: Fastify server in packages/k-skill-proxy/src/server.js handles normalization via helpers like normalizeFineDustQuery, caching via createMemoryCache, and proxying via functions like proxyAirKoreaRequest

Frequently Asked Questions

What is the difference between the hosted proxy and running the proxy locally?

The hosted proxy at k-skill-proxy.nomadamas.org is pre-configured with operator-managed API keys for most services, requiring no setup from you. Running the proxy locally lets you inject your own credentials via environment variables and is useful for development, debugging, or accessing services that require personal API keys. Both use identical code from packages/k-skill-proxy/src/server.js.

Do I need to register for API keys to use the k-skill API?

For the hosted proxy, no—most endpoints work without user-provided keys. For local proxy deployment, some skills like fine-dust queries require AIR_KOREA_OPEN_API_KEY from data.go.kr. Check docs/setup.md for credential requirements per skill.

How does the k-skill API handle rate limits and caching?

The proxy uses buildRateLimiter to track per-IP request counts and createMemoryCache to store successful responses by SHA-256 hash of the request. This protects upstream services and improves response times for repeated queries. Cached responses bypass upstream calls entirely.

What happens when an upstream API returns an error?

The proxy catches failures through isFailureResponse and transforms them into a consistent JSON error envelope with error, message, and upstream fields. Your application receives predictable error handling regardless of which Korean data source failed.

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